Build a headless storefront, step by step

1. In Backoffice, go to Settings → Application APIs (/settings/api).
2. Click Create Application API.
3. On the Basics tab, choose the store this key belongs to and set Application Type to Store.
4. On the Access Control tab, choose a Key Type (see the table below), tick the scopes this integration actually needs, and optionally restrict Allowed Origins to your own domain(s).
5. Save. The plaintext key is shown once, immediately after creation - copy it now. From then on only a masked preview (sk_store_ab12…xyz9) is shown.

Secret vs. publishable keys

Scopes

Leaving every scope unchecked gives the key full access (anything an anonymous visitor or logged-in customer could do). Tick only what you need:

A request that touches a scope the key wasn't granted gets a 403 with code store_key_scope_denied. Read-only calls (browsing, viewing a cart) never require a scope.

curl https://your-store.example.com/api/v1/store/catalog/categories \
  -H "X-Commerce-Key: pk_store_yourstore_<secret>"

X-Storefront-Application-Key is also accepted, as a legacy alias for the same header. A missing key returns 401 with code store_key_missing.

• The server generates the session reference on your first request and returns it in the X-Session-Ref response header - you don't invent one.
• From then on, send that same value back as X-Session-Ref on every subsequent request. That's the entire contract.
• When the visitor logs in, their anonymous cart carries over onto their account automatically - there's no separate "merge cart" call to make.

curl https://your-store.example.com/api/v1/store/cart \
  -H "X-Commerce-Key: pk_store_yourstore_<secret>" \
  -H "X-Session-Ref: 8f3c1a9d2b7e4f10"

POST /api/v1/store/auth/login
{ "email": "customer@example.com", "password": "…" }

→ 200 OK
{
  "token": "eyJ…",
  "expiresIn": 3600,
  "sessionReference": "8f3c1a9d2b7e4f10",
  "refreshToken": "…",
  "user": { "id": 1, "email": "customer@example.com", "personId": 42, "accountId": 7 }
}

Send token back as Authorization: Bearer <token> on every request that needs it. It expires after expiresIn seconds (60 minutes) - call POST /api/v1/store/auth/refresh-token with the refreshToken to get a new pair before then.

Cart, catalogue, search, and checkout all work with just X-Session-Ref - no Authorization header required. Orders, saved addresses, wishlists, gift registries, and account/member management require a logged-in customer's Bearer token.

# Search the catalogue
curl "https://your-store.example.com/api/v1/store/search/products?keywords=shoes&page=1&limit=18" \
  -H "X-Commerce-Key: pk_store_yourstore_<secret>"

# Add an item to the cart
curl -X POST https://your-store.example.com/api/v1/store/cart/items \
  -H "X-Commerce-Key: pk_store_yourstore_<secret>" \
  -H "X-Session-Ref: 8f3c1a9d2b7e4f10" \
  -H "Idempotency-Key: 3f7a-add-item-1" \
  -H "Content-Type: application/json" \
  -d '{ "productId": 501, "qty": 1 }'

# Place the order
curl -X POST https://your-store.example.com/api/v1/store/checkout/orders \
  -H "X-Commerce-Key: pk_store_yourstore_<secret>" \
  -H "X-Session-Ref: 8f3c1a9d2b7e4f10" \
  -H "Idempotency-Key: 3f7a-place-order-1" \
  -H "Content-Type: application/json" \
  -d '{ }'

Every field, query parameter, and response shape for every endpoint - including the ones skipped here (shipping, payment, gift cards, wallet) - is documented and testable live at /docs/store.

{
  "type": "https://…",
  "title": "Bad Request",
  "status": 400,
  "code": "quantity_must_be_positive",
  "detail": "Quantity must be greater than 0",
  "errors": null,
  "traceId": "00-abc123…"
}

Rate limits

Every key is limited to 200 requests per minute. Login, register, forgot-password, and reset-password are limited more tightly (10 requests per 5 minutes, by caller IP) since they're the credential-guessing surface. Either limit returns 429 with a Retry-After header (seconds to wait).

• Same key + same request again → the original response is replayed, the action does not run twice.
• Same key + a different request → 422 (you're reusing a key for something else).
• Same key while the first call is still in flight → 409 with Retry-After: 2.
• No key sent → the call just runs normally, with no replay protection.

Generate a fresh key per logical action (a UUID is fine) and reuse the exact same value only when retrying that exact same action.

Click Authorize at the top of that page, paste in your key, and every "Test Request" button on the page fires a real call using it - no separate Postman setup needed.