Skip to main content
Developers only. If you sell through the built-in Quickshops storefront, you don’t need this section — use the Quickstart and Integrations guides instead.Headless API access requires a Pro plan and an API key from Settings → API keys.
The Quickshops Headless API is a REST API that lets you build fully custom storefronts on top of your Quickshops store. For application code, use the TypeScript SDK (@quickshops/sdk) — it wraps these routes with typed methods. Reach for raw HTTP only when debugging or integrating a language without an SDK. All responses are JSON.
Vibe-coding a storefront? Paste the one-prompt into Lovable, v0.dev, or Cursor, keep your API key on the server, and call commerce through @quickshops/sdk.

​
Base URL

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 (https://api.quickshops.app/v1). Every response also sends X-API-Version: v1. Breaking changes will ship under a new base URL (for example https://api.quickshops.app/v2). v1 continues to work during a deprecation window of at least 90 days. When an operation is deprecated, it is marked deprecated: true in the OpenAPI spec and responses include RFC 8594 Deprecation and Sunset headers before removal.

​
Routes

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

​
Hello-world flow

Prefer useStore():
  1. const store = useStore() from @quickshops/sdk
  2. store.buyNow({ productId }) → redirect to url
  3. On success, store.getCheckoutSession(sessionId)
Equivalent REST: GET /catalog → POST /checkout/session → GET /checkout/sessions/:sessionId.

​
Authentication

Every protected request requires an Authorization header with a bearer token containing your headless API key.
See Authentication for how to create and use your key.

​
Rate limits

Per API key, per minute: Exceeding a limit returns 429 with code RATE_LIMITED.

​
Error format

All errors return a JSON body with the following shape:
Common codes: UNAUTHORIZED, FORBIDDEN, NOT_FOUND, INVALID_REQUEST, CART_EMPTY, CART_MIXED_TYPES, PAYMENTS_NOT_CONFIGURED, STORE_UNPUBLISHED, RATE_LIMITED, CONFLICT, INTERNAL_ERROR.

​
API reference

Endpoint pages in the sidebar are generated from the OpenAPI spec, with an interactive playground. Prefer @quickshops/sdk in application code.

Authentication

API keys and how to authenticate requests.

TypeScript SDK

useStore(), typed client, and one-prompt install for Lovable / v0 / Cursor.

React components

@quickshops/sdk/react — Storefront.* composition and CheckoutSuccess.