Key Concepts

Checkout URL

Every successful cart response includes:

id

checkout_url

Use checkout_url to redirect the customer to hosted checkout when the cart is ready.

{
  "id": "abc123",
  "checkout_url": "https://salla.sa/store/checkout/abc123"
}

Flexible Product Identification (Add Item)

When adding an item, products can be referenced using:

Type	Description	Best for
`id`	Internal product ID	Direct catalog references
`variant_id`	Specific variant ID	Variant-first integrations
`sku`	Stock Keeping Unit	Inventory/SKU-driven systems

Request body fields:

identifier_type

identifier

quantity

optional: options, notes, amount, bundle

Item Mutation Model (Current V2)

The current implementation uses route item IDs for update/delete:

Add: POST /v2/checkout/{cart}/items (identifier-based payload)

Update: PATCH /v2/checkout/{cart}/items/{item} (item id in path)

Delete: DELETE /v2/checkout/{cart}/items/{item} (item id in path)

{item} must belong to {cart}; otherwise a 404 not_found response is returned.

Cart Response Structure

Cart payload is returned in successful operations and includes:

Section	Description
Identity	`id`, `store_id`, `checkout_url`
Count	`count`
Currency	`currency.label`, `currency.code`
Scope	store scope context (`scope.id`, `scope.type`) or `null`
Amounts	`amounts` map (for example subtotal/discount/tax/total/offers when applicable)
Shipping	`shipping.requires_shipping`
Coupon	current coupon code or `null`
Features	`coupon`, `gift`, `loyalty`, `guest_checkout` flags
Discounts	normalized discounts map (`coupon`, `offers`, `bundle`, `loyalty_prize` when available)
Settings	feature-dependent settings (for example gift settings)
Options	cart-level order options
Items	included only when requested via query

Items Inclusion

By default, line items are omitted.

Use:

include_items=true

Ownership and Assignment

V2 carts are created in guest context and can later be assigned to an authenticated user.

Ownership is represented by the cart's customer assignment state

Current behavior:

Generate cart (POST /v2/checkout/generate)

Cart operates in guest context (internally uses guest customer semantics)

Assign via POST /v2/checkout/{cart}/assign (requires JWT auth)

The cart transitions from guest ownership to authenticated customer ownership

Assignment is blocked (403) when the cart is already assigned to a non-guest customer.

Scope Context (Store Context)

scope describes store operational context (for example scope/location context used for product availability, pricing, and checkout validation), independent from customer ownership.

scope is returned as:

{
  "scope": {
    "id": "scope_123",
    "type": "Scope"
  }
}

When no store scope is active, scope can be null.

Authentication Model

Store-Identifier is required for all requests.

Guest flow can use optional auth middleware.

Assign endpoint requires JWT authentication:

POST /v2/checkout/{cart}/assign

Error Envelope

Errors follow a consistent envelope:

{
  "status": 422,
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "fields": {
      "quantity": [
        "The quantity must be at least 1."
      ]
    }
  }
}

Common status outcomes across cart operations:

400 bad request (for example invalid coupon)

401 unauthorized (missing/invalid token on protected operations)

403 forbidden (assignment/access constraints)

404 not found (cart/item/product/identifier resolution failures)

422 validation or business-rule failure

Treat status codes as operation-specific outcomes; exact behavior depends on endpoint and action path.

Key Concepts

Key Concepts#

Checkout URL#

Flexible Product Identification (Add Item)#

Item Mutation Model (Current V2)#

Cart Response Structure#

Items Inclusion#

Ownership and Assignment#

Scope Context (Store Context)#

Authentication Model#

Error Envelope#

Key Concepts

Checkout URL

Flexible Product Identification (Add Item)

Item Mutation Model (Current V2)

Cart Response Structure

Items Inclusion

Ownership and Assignment

Scope Context (Store Context)

Authentication Model

Error Envelope