> ## Documentation Index
> Fetch the complete documentation index at: https://docs.headlesscommerce.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete reference for the Headless Commerce REST API

# 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

```
https://api.headlesscommerce.io/v1
```

## Two API Surfaces

<CardGroup cols={2}>
  <Card title="Storefront API" icon="shop">
    `/v1/storefront/*`

    For customer-facing applications. Accessible with publishable keys (`pk_*`) or secret keys (`sk_*`).
  </Card>

  <Card title="Admin API" icon="lock">
    `/v1/admin/*`

    For back-office management. Requires secret keys (`sk_*`) only.
  </Card>
</CardGroup>

## 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        |

All responses include rate limit headers:

| 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 |

## Interactive Reference

You can also explore and test the API interactively using the [Scalar API Reference](https://api.headlesscommerce.io/reference).