API Reference
The Headless Commerce API is organized around REST. It accepts JSON request bodies, returns JSON responses, and uses standard HTTP verbs and status codes.Base URL
Two API Surfaces
Storefront API
/v1/storefront/*For customer-facing applications. Accessible with publishable keys (pk_*) or secret keys (sk_*).Admin API
/v1/admin/*For back-office management. Requires secret keys (sk_*) only.Common Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <api_key> |
Content-Type | For POST/PATCH | application/json |
X-Customer-Token | Conditional | Customer JWT for authenticated storefront endpoints |
Idempotency-Key | Recommended | Unique key for critical POST requests |
Rate Limiting
Requests are rate-limited per store based on plan:| Plan | Limit |
|---|---|
| Free | 100 req/min |
| Starter | 500 req/min |
| Pro | 2,000 req/min |
| Enterprise | Custom |
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests per minute |
X-RateLimit-Remaining | Remaining requests in current window |
X-RateLimit-Reset | Unix timestamp when the window resets |