Authentication#
The Checkout APIs support two access modes: guest and authenticated.
Store-Identifier is required on all requests. Bearer token authentication is required only on endpoints that explicitly enforce user identity (for example, cart assignment).| Mode | Authorization | Use when |
|---|
| Guest | Not required | Creating carts, adding items, applying coupons, retrieving guest carts |
| Authenticated | Required on protected routes | Assigning a cart to a user and operating in user-identity flows |
Cart generation supports both contexts:without auth token: cart is created in guest context
with valid auth token: cart can be created in authenticated customer context
| Header | Required | Description |
|---|
Store-Identifier | Yes | Identifies the target store for every request |
s-source | Yes | Request source identifier app |
s-app-name | Yes | Name of the calling application |
s-app-version | Yes | Version of the calling application |
Authorization | Conditional | Bearer token in the format Bearer <token>. Required for authenticated/user-scoped operations |
These headers are recommended for analytics, attribution, and campaign tracking.| Header | Required | Description |
|---|
s-utm-source | No | Traffic source |
s-utm-campaign | No | Campaign identifier |
s-utm-medium | No | Marketing medium |
s-utm-term | No | Paid keyword / search term |
s-utm-content | No | Content variation identifier |
s-utm-referrer | No | Referrer source URL or identifier |
Examples#
These examples demonstrate the minimum required headers for both guest and authenticated Checkout API requests.
Optional tracking headers can also be included to support analytics, attribution, and campaign reporting.Guest Request#
Authenticated Request#
Common Error Responses#
| Status | Meaning |
|---|
400 | Missing token on endpoint that requires authentication |
401 | Invalid or expired token |
403 | Token is valid but cart access is forbidden (ownership/scope rules) |
404 | Cart not found or invalid cart identifier |
Modified at 2026-07-29 11:46:05
