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

# Quickshops Headless API Overview

> Learn how to use the Quickshops Headless REST API to build custom storefronts, manage carts, and trigger checkout from your own frontend.

<Note>
  **Developers only.** If you sell through the built-in Quickshops storefront, you don't need this section — use the [Quickstart](/quickstart) and [Integrations](/integrations/overview) guides instead.

  Headless API access requires a **Pro** plan and an API key from **Settings → API keys**.
</Note>

The Quickshops Headless API is a REST API that lets you build fully custom storefronts on top of your Quickshops store. Instead of using a Quickshops-managed template, you fetch store data, manage carts, and initiate checkout from your own frontend or backend using standard HTTP requests. All responses are JSON.

## Base URL

```
https://api.quickshops.app/v1
```

All examples prepend this base URL to the endpoint paths below. For example, `GET /products` means `GET https://api.quickshops.app/v1/products`.

## Versioning

The API is currently at version `v1`, included in the base URL. Breaking changes will ship under a new base URL (for example `https://api.quickshops.app/v2`), and `v1` will continue to work during a deprecation window.

## Routes

The table below lists every available endpoint and whether authentication is required.

| Method   | Path                             | Auth required |
| -------- | -------------------------------- | ------------- |
| `GET`    | `/health`                        | No            |
| `GET`    | `/products/store`                | Yes           |
| `GET`    | `/products`                      | Yes           |
| `GET`    | `/products/:productId`           | Yes           |
| `GET`    | `/cart/:cartId`                  | Yes           |
| `POST`   | `/cart`                          | Yes           |
| `POST`   | `/cart/:cartId/lines`            | Yes           |
| `PATCH`  | `/cart/:cartId/lines/:productId` | Yes           |
| `DELETE` | `/cart/:cartId/lines/:productId` | Yes           |
| `DELETE` | `/cart/:cartId`                  | Yes           |
| `POST`   | `/checkout/session`              | Yes           |
| `POST`   | `/subscription/portal`           | Yes           |

Every protected route uses the same headless API key in the `Authorization` header. Missing or invalid keys return `401`.

## Authentication

Every protected request requires an `Authorization` header with a bearer token containing your headless API key.

```bash theme={null}
curl https://api.quickshops.app/v1/products \
  -H "Authorization: Bearer qk_your_key_here"
```

See [Authentication](/api/authentication) for how to create and use your key.

## Rate limiting

Rate limits are enforced per key and per endpoint. If you exceed a limit you will receive a `429` response with code `RATE_LIMITED`. Back off and retry after a short delay.

## Error format

All errors return a JSON body with the following shape:

```json theme={null}
{
  "error": "Missing or invalid API key",
  "code": "UNAUTHORIZED"
}
```

| Field   | Type   | Description                              |
| ------- | ------ | ---------------------------------------- |
| `error` | string | Human-readable description of the error. |
| `code`  | string | Machine-readable error code.             |

Common error codes include `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `INVALID_REQUEST`, `RATE_LIMITED`, `CONFLICT`, and `INTERNAL_ERROR`.

## API reference

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api/authentication">
    API keys and how to authenticate requests.
  </Card>

  <Card title="Products" icon="package" href="/api/products">
    Fetch store and product data.
  </Card>

  <Card title="Cart" icon="shopping-cart" href="/api/cart">
    Create and manage carts.
  </Card>

  <Card title="Checkout" icon="credit-card" href="/api/checkout">
    Create Stripe Checkout sessions.
  </Card>

  <Card title="Subscriptions" icon="repeat" href="/api/subscriptions">
    Manage subscription portal sessions.
  </Card>

  <Card title="TypeScript SDK" icon="terminal" href="/sdk/installation">
    Use the TypeScript SDK instead of raw HTTP requests.
  </Card>
</CardGroup>