README

An unofficial Laravel package for building apps on the Salla e-commerce platform: Merchant API resources, OAuth 2.0 (Easy Mode & Custom Mode), and secure webhook handling. Built against docs.salla.dev.

This is a community package, not published or maintained by Salla. Endpoint paths mirror the Merchant API docs as of this writing — please verify against the docs for anything mission critical, and open an issue/PR if something drifted.

Features

• Fluent, resource-based client: Salla::orders()->all(), Salla::products()->create([...])
• OAuth 2.0 helpers for both Easy Mode and Custom Mode
• Per-store token storage (Eloquent model + migration) for multi-tenant apps, with automatic refresh-token exchange on expiry
• A secured webhook endpoint, auto-registered, that verifies Salla's signature and dispatches Laravel events per store event (order.created, product.created, etc.)
• Typed exceptions for auth failures, rate limits, and validation errors

Installation

composer require yehia-tarek/salla-toolkit
php artisan salla:install
php artisan migrate

salla:install publishes config/salla.php and the salla_authorizations migration, and prints your webhook URL.

Add your app's credentials (from the Salla Partners Portal) to .env:

SALLA_CLIENT_ID=
SALLA_CLIENT_SECRET=
SALLA_REDIRECT_URI=https://your-app.com/salla/callback
SALLA_WEBHOOK_SECRET=
SALLA_SCOPES="offline_access"

# Only needed for private, single-store apps (skips OAuth entirely):
# SALLA_ACCESS_TOKEN=

Usage

Single-store / private apps

If you're building a private app for one store, drop a long-lived token in SALLA_ACCESS_TOKEN and skip straight to calling resources:

use YehiaTarek\SallaToolkit\Facades\Salla;

$orders = Salla::orders()->all(['status' => 'pending']);
$order  = Salla::orders()->find($orderId);

$product = Salla::products()->create([
    'name' => 'T-Shirt',
    'price' => 100,
    'product_type' => 'product',
]);

Salla::customers()->ban($customerId);

Public / multi-store apps (OAuth)

Easy Mode (recommended by Salla): send merchants straight to the install URL. Salla handles the authorization code exchange for you and delivers the resulting tokens via the app.store.authorize webhook event, which this package catches and persists automatically.

// Redirect a merchant to install your app:
return redirect(Salla::oauth()->installationUrl($appId));

Nothing else required — as long as your webhook route is reachable and SALLA_WEBHOOK_SECRET matches the secret configured on the Partners Portal, tokens land in the salla_authorizations table on their own.

Custom Mode: build your own authorize URL and handle the callback:

// routes/web.php
Route::get('/salla/connect', function () {
    return redirect(Salla::oauth()->authorizationUrl());
});

Route::get('/salla/callback', function (Illuminate\Http\Request $request) {
    $tokens = Salla::oauth()->exchangeCodeForToken($request->query('code'));
    $me = Salla::oauth()->userInfo($tokens['access_token']);

    app(\YehiaTarek\SallaToolkit\Contracts\SallaTokenRepository::class)->store(
        storeId: $me['data']['merchant']['id'] ?? $me['data']['id'],
        accessToken: $tokens['access_token'],
        refreshToken: $tokens['refresh_token'] ?? null,
        expiresAt: time() + ($tokens['expires_in'] ?? 0),
        scope: $tokens['scope'] ?? null,
    );

    return redirect('/dashboard');
});

Once a store's tokens are stored, scope every call to that store:

Salla::forStore($storeId)->orders()->all();
Salla::forStore($storeId)->products()->find($productId);

forStore() automatically refreshes the access token (and re-persists the new refresh token — Salla's are single-use) if a request comes back with a 401.

Ad-hoc token

Salla::withToken($accessToken)->orders()->all();

Pagination

Salla list endpoints return data + pagination:

$response = Salla::orders()->all(['page' => 2]);
$orders = $response['data'];
$pagination = $response['pagination']; // count, total, perPage, currentPage, totalPages, links

Or fetch every page at once (careful on large stores):

$allOrders = Salla::orders()->allPages();

Available resources

orders, products, customers, categories, brands, coupons, specialOffers, shipments, shippingCompanies, shippingZones, taxes, countries, cities, currencies, affiliates, reviews, webhooks, settings, store, exports.

Every resource supports all(), find($id), create($data), update($id, $data), and delete($id) (where Salla's API supports the corresponding verb), plus resource-specific helpers — e.g. Salla::products()->findBySku($sku), Salla::orders()->updateStatus(...), Salla::customers()->ban($id). See each class under src/Resources for the full list.

Webhooks

Point your app's Webhook URL (Partners Portal) at:

https://your-app.com/salla/webhook

(configurable via SALLA_WEBHOOK_PATH). Incoming requests are verified against X-Salla-Signature using SALLA_WEBHOOK_SECRET, then dispatched as Laravel events:

use YehiaTarek\SallaToolkit\Webhooks\Events\SallaWebhookReceived;

// Catch-all listener
Event::listen(SallaWebhookReceived::class, function (SallaWebhookReceived $event) {
    logger("Salla event: {$event->event}", $event->data());
});

// Or listen for one specific event by name
Event::listen('salla.order.created', function (array $payload) {
    // $payload['data'] is the created order
});

See the full event list at docs.salla.dev/421119m0.

If you'd rather not use the auto-registered route, set SALLA_WEBHOOK_ROUTE_ENABLED=false and wire up your own controller with the VerifySallaWebhook middleware:

Route::post('/my-webhook', MyWebhookController::class)
    ->middleware(\YehiaTarek\SallaToolkit\Middleware\VerifySallaWebhook::class);

Error handling

use YehiaTarek\SallaToolkit\Exceptions\{
    SallaAuthenticationException,
    SallaRateLimitException,
    SallaRequestException,
};

try {
    Salla::forStore($storeId)->orders()->create($data);
} catch (SallaRequestException $e) {
    // $e->statusCode(), $e->errors() (422 field errors), $e->getMessage()
} catch (SallaRateLimitException $e) {
    // $e->retryAfter() in seconds, if provided
} catch (SallaAuthenticationException $e) {
    // token missing/expired and could not be refreshed — merchant likely
    // needs to reinstall the app
}

Custom token storage

Swap the Eloquent-backed repository for your own by binding the contract in your own service provider:

$this->app->bind(
    \YehiaTarek\SallaToolkit\Contracts\SallaTokenRepository::class,
    \App\Services\RedisSallaTokenRepository::class
);

Your class just needs to implement store(), find(), and forget() — see src/Contracts/SallaTokenRepository.php.

Configuration reference

See config/salla.php for every option (API base URL, OAuth endpoints, HTTP timeouts/retries, token table name/connection, webhook path & middleware).

License

MIT