Overview

The Storefront API is a stateless HTTP API. This page covers the conventions that apply everywhere; the interactive reference documents every endpoint and lets you send test requests from your browser.

Base URL & versioning

All public endpoints live under /v1:

GET https://api.your-storekit.com/v1/products

Utility and integration routes sit at the root: GET /health, the OpenAPI document at GET /openapi.json, webhooks under /webhook/*, and the payment browser callback at /payment/callback.

Authentication

Two headers, covered in depth in Authentication:

X-Store-Key: sk_live_xxx              # identifies the store (required on /v1)
Authorization: Bearer <session-token> # identifies the customer (when needed)

Public catalog endpoints need only the store key. Customer endpoints (cart me, checkout, orders, addresses, coupons, downloads, payment) also need the bearer token.

Content type

Requests and responses are JSON. Send Content-Type: application/json on requests with a body.

Errors

Every 4xx/5xx JSON response uses one envelope:

{ "error": "Product not found", "code": "NOT_FOUND" }

code is stable and machine-readable. Standard codes by status:

Some routes add domain-specific codes (INSUFFICIENT_STOCK, STALE_CHECKOUT, COUPON_EXPIRED, …). One endpoint, POST /v1/coupons/validate, intentionally returns 200 with { valid, reason? } instead of an error.

Pagination

List endpoints use cursor pagination:

{ "data": [ ], "nextCursor": "…", "hasMore": true }

Pass nextCursor back as the cursor query param. Default limit is 20, max 100. Treat the cursor as opaque. See Pagination & filtering.

Outlet selection

Multi-outlet stores can scope a request with X-Outlet-Id. Omit it to use the store's default outlet.

CORS

Browser calls are allowed only from origins on the store's allowlist. If you're calling the API directly from a browser app, make sure your origin is permitted (server-side calls aren't subject to CORS). The SDK's Next.js adapter avoids this entirely by proxying through your own origin.

Rate limits

Requests are rate limited per API key. See Rate limits.