Skip to main content
Every cart has three values that belong together: cart.id, the secret cartAccessToken, and the current cart.revision. The SDK persists them through the sessionStore you provide.

Start a session

marketplaceId is optional source attribution, such as "web" or "mobile"; it is not a location ID. The route already supplies the location scope. Store the response capability in sessionStorage for browsers or secure device storage for mobile. Do not use a URL, cookie shared across origins, analytics property, or application log.

Add an item

Read and mutate the cart

The SDK sends the capability automatically. For raw REST calls, send X-Cart-Token on every cart read and write. Send If-Match and a stable Idempotency-Key on every mutation. Pass includeCustomerContext: true only when a signed-in shopper still has a guest-capability cart and discount validation needs customer context. Omit it for a guest; a claimed cart uses the customer JWT automatically.

Handle conflicts safely

The API returns CART_CONFLICT when If-Match is stale. The SDK refreshes the stored revision but deliberately does not repeat the failed mutation. Replace the UI cart with the fresh server state, explain the change, and require the user to retry.

End the capability lifecycle

cart.delete() clears the SDK session. cart.claim() removes the guest capability while retaining the authoritative revision for customer-authenticated access. After checkout reaches completed or failed, clear the persisted capability once terminal handling such as a same-page rating is finished.

Checkout Flow

Protect payment creation and order-result polling.

Error Codes

Handle authorization and concurrency failures.