Adapters
Salla
Salla platform adapter — maps Salla's API to the unified CommerceAdapter interface.
The @commercejs/adapter-salla package implements the CommerceAdapter interface for Salla, the leading eCommerce platform in Saudi Arabia and the MENA region.
Installation
pnpm add @commercejs/adapter-salla
Configuration
import { createSallaAdapter } from '@commercejs/adapter-salla'
const adapter = createSallaAdapter({
token: 'your-salla-api-token',
baseUrl: 'https://api.salla.dev/admin/v2',
})
| Option | Type | Required | Description |
|---|---|---|---|
token | string | Yes | Salla API access token |
baseUrl | string | No | API base URL |
Supported Domains
The adapter implements these sub-adapters:
| Domain | Methods | Status |
|---|---|---|
| Catalog | getProducts, getProduct, getCategories | ✅ Implemented |
| Cart | getCart, addToCart, removeFromCart, updateCartItem | ✅ Implemented |
| Customer | getCustomer, login, register | ✅ Implemented |
| Order | getOrders, getOrder, createOrder, getOrderStatus, getOrderHistory | ✅ Implemented |
| Store | getStoreInfo | ✅ Implemented |
| Brand | getBrands, getBrand | ✅ Implemented |
| Country | getCountries | ✅ Implemented |
Data Mapping
The adapter transforms Salla's API responses into unified CommerceJS types. Key mappings:
Product Mapping
| Salla Field | CommerceJS Field | Notes |
|---|---|---|
name | name | Wrapped in LocalizedString |
regular_price.amount | price.amount | Normalized to DiscountablePrice |
sale_price.amount | price.compareAtAmount | Original price before discount |
images[].url | images[].url | Mapped to Image type |
options | options | Mapped to ProductOption |
skus | variants | Mapped to ProductVariant |
Order Status Mapping
| Salla Status | CommerceJS Status |
|---|---|
created | pending |
in_progress | processing |
completed | delivered |
cancelled | cancelled |
refunded | refunded |
Usage Examples
Fetch Products
const products = await adapter.catalog.getProducts({
limit: 10,
page: 1,
})
// Returns PaginatedResult<Product>
Get Single Product
const product = await adapter.catalog.getProduct('product-123')
// Returns Product with variants, images, options
Fetch Orders
const orders = await adapter.order.getOrders({
limit: 20,
page: 1,
})
// Returns PaginatedResult<Order>
Get Order Timeline
const history = await adapter.order.getOrderHistory('order-456')
// Returns OrderHistoryEntry[] - status changes with timestamps
Error Handling
The adapter wraps Salla API errors in CommerceError:
import { isCommerceError } from '@commercejs/types'
try {
await adapter.catalog.getProduct('nonexistent')
} catch (err) {
if (isCommerceError(err)) {
// err.code === 'NOT_FOUND'
// err.message === 'Product not found'
}
}