Headless API quickstart
Connect a website, mobile app, server or AI agent to a Queek store. Get keys from Channels → Headless API, read the catalogue, build a cart and hand it to Queek checkout. Formerly called the Storefront API.
The Headless API lets you sell a Queek store through something you build: a website, a mobile app, a server or an AI agent. (It used to be called the Storefront API; every address and header is unchanged.) The store's products, collections, promotions, reviews, pages and blog already exist on Queek. You read them, manage a cart and, if you want accounts, sign customers in. Queek runs checkout, payment and delivery, so your code never touches payments.
Building this with an AI tool (Claude, ChatGPT, Cursor, Lovable, Bolt, v0)?
Open the connection in the dashboard, press Copy for AI and paste the text into the tool. The tool should read this page and Rules for AI builders before it writes code. Never paste a secret key into an AI chat.
You will end this page with a cart handed to Queek checkout. Every snippet is a complete request: put a real key in it and it runs.
Connect a site or app
The merchant (or you, on a dev store) does this once in the Queek dashboard:
- Install Headless API once from the Apps window (it is free and built by Queek). Installing adds it to the sidebar under Channels. A store that already had connections is installed already.
- Open Channels → Headless API and press Connect a site or app.
- Under What are you building?, pick one:
| You pick | You get | Websites | Good to know |
|---|---|---|---|
| Website | A public key | You must list the site, for example https://shop.example.com | Browser code runs only from a listed website. |
| Mobile app | A public key | None | An app sends no website address, so none is checked. You can give an app link to return to after checkout (myapp://checkout/done). |
| Server or backend | A public key and a secret key | None | The secret key is shown once. Keep it on your server. |
| AI agent | A public key | None | The agent can browse products and build carts only. It cannot reach accounts, orders or checkout calls. |
| Testing on my computer | A pk_test_ key | This computer is always allowed | Dev stores only. Uses the dev store's sample data and never real money. You can go live later. |
- Give it a name, add the website address if it asks for one, and optionally the page customers should return to after checkout.
- Save. The dashboard shows your keys. Copy the secret key now if you got one: it is never shown again.
Queek sets safe defaults for the type you pick, so you never choose scopes or origins by hand. See Manage a connection for everything you can change later.
| Key | Looks like | Where it belongs |
|---|---|---|
| Public key | pk_live_… (pk_test_… on a dev store) | Browser and app code. Safe to ship, because a website key only works from the websites you listed. |
| Secret key | sk_live_… (sk_test_… on a dev store) | Servers only. Never in a browser, an app, a public repository or a NEXT_PUBLIC_ or VITE_ variable. |
Which plan do I need?
A live store needs an active paid website plan before its keys work. Without one, every
request answers 403 plan_inactive and the connection page shows a banner. A dev store
is free, so you can build and test first.
Copy for AI
Every connection page has a Copy for AI button. It copies a short brief, never the rules, a secret key or a dev store's password. A Server connection's brief says the secret key is not included; on a dev store it adds the storefront-password step:
Queek connection: My website
Connection number: 101
Type: Website
API address: https://client.usequeek.com/v1
API access: active
Public key: pk_live_your_key_here
Allowed websites: https://shop.example.com
Build me a store website for this Queek store using this connection.
Read this first: https://docs.usequeek.com/docs/storefront/rules-for-ai-builders
Quickstart: https://docs.usequeek.com/docs/storefront
AI guide: https://client.usequeek.com/llms.txt
Skill: https://usequeek.com/skills/headless.md
Deploy: https://docs.usequeek.com/docs/storefront/deployThe rules live in these docs, so the AI always reads the current version.
Rules for AI builders is the page it must follow, and
https://client.usequeek.com/openapi.json is the full endpoint list.
Make the first request
Every call carries the key in X-Client-Key, and the base URL is
https://client.usequeek.com/v1.
curl https://client.usequeek.com/v1/store/info \
-H "X-Client-Key: pk_live_your_key_here" \
-H "Origin: https://shop.example.com" \
-H "Accept: application/json"store/info is the one call you always make first. It returns the store's name, slug,
currency, opening hours and address — and, on your own key, storefront_url, checkout_url,
unmasked contact, and the brand kit (logo, colour tokens, fonts, socials) you build the
site's look from.
The Origin line is only for testing a website connection from a terminal: a browser adds it
by itself, and a mobile app, server or AI agent connection needs no Origin at all. Use a website
you listed. A request from a website that is not listed is refused with 403 origin_not_allowed,
and the connection page offers a one-click Allow for it.
Read the catalogue
curl "https://client.usequeek.com/v1/store/products?per_page=20&page=1" \
-H "X-Client-Key: pk_live_your_key_here" \
-H "Origin: https://shop.example.com"Walk the whole catalogue with the cursor: send the reply's next_cursor as starting_after
on the next request, and stop when has_more is false. Treat the cursor as opaque and never
combine it with page; a cursor that is stale, edited or reused under different filters answers
422 starting_after_invalid. For numbered pages (shop pages, sitemaps) send page instead.
Numbered pages stop at page 50 (page_too_deep), so walk the cursor for anything deeper. The
first page carries meta.total_count, exact up to 1,000 and then capped at 1,000 with
meta.total_count_capped; later pages carry no total.
keyword, category_slug, sort, has_video and metafield[…] narrow the list. per_page
(or limit on a cursor walk) caps at 100. Add locale to read a published store language; an
unknown or unpublished code falls back to the primary locale, and Content-Language says which
one you got.
Every price you receive is the final customer price in the store's currency. Display
it as given; never recompute it, and never type a price or a stock level into your code.
Identify products, categories and collections by the slug or id a listing returned. Never
invent one.
Take the first order
Generate one random UUID per shopper and send it as X-Cart-Session on every cart call.
That header is the cart's identity.
curl -X POST https://client.usequeek.com/v1/store/cart/items \
-H "X-Client-Key: pk_live_your_key_here" \
-H "Origin: https://shop.example.com" \
-H "X-Cart-Session: 3f1a8e64-4f2c-4a1d-9d2e-2f7b0c8a5d11" \
-H "Content-Type: application/json" \
-d '{"product_id": "the-id-from-a-listing", "quantity": 1}'A reply of result: "added" carries the cart. A reply of result: "customise" means the
product needs a variant or add-on choice: show the options it returned and call again with
variant_id. product_id, variant_id and cart_id are UUIDs taken from earlier replies.
Without a signed-in customer, X-Cart-Session is required: a cart call without it answers
422 validation_failed. With a customer token the header is ignored (see
Authentication).
Before you send the shopper anywhere, re-check the cart against current stock and prices. The
cart's id is data.cart.id in the add-line reply above. The reply carries is_valid and a list
of validation_errors: if the cart is not valid, fix it before the handoff.
curl -X POST https://client.usequeek.com/v1/store/cart/validate \
-H "X-Client-Key: pk_live_your_key_here" \
-H "Origin: https://shop.example.com" \
-H "X-Cart-Session: 3f1a8e64-4f2c-4a1d-9d2e-2f7b0c8a5d11" \
-H "Content-Type: application/json" \
-d '{"cart_id": "the-cart-id-from-the-add-reply"}'A shopper's cart (the X-Cart-Session flow above) carries checkout_url: the store's own
address (its connected custom domain, else <handle>.queek.app) plus /checkout?cart= and that session id, for example
https://your-store.queek.app/checkout?cart=3f1a8e64-4f2c-4a1d-9d2e-2f7b0c8a5d11. It is on
the cart in the add-line reply (data.cart.checkout_url), the validate reply
(data.checkout_url) and each cart in a cart read. Send the shopper there —
window.location.assign(checkout_url) — and Queek shows exactly this cart and completes
address, delivery, payment and order confirmation.
The same flow in browser JavaScript, complete:
const API = 'https://client.usequeek.com/v1';
const KEY = 'pk_live_your_key_here'; // a public key: safe in browser code
// One random id per shopper, remembered between visits.
const session = localStorage.getItem('cart-session') ?? crypto.randomUUID();
localStorage.setItem('cart-session', session);
async function call(path, body) {
const res = await fetch(`${API}${path}`, {
method: body ? 'POST' : 'GET',
headers: {
'X-Client-Key': KEY,
'X-Cart-Session': session,
Accept: 'application/json',
'Content-Type': 'application/json',
},
body: body ? JSON.stringify(body) : undefined,
});
const json = await res.json();
if (!res.ok) throw new Error(json.error?.code ?? 'request_failed');
return json.data;
}
const added = await call('/store/cart/items', { product_id: 'the-id-from-a-listing', quantity: 1 });
if (added.result !== 'added') {
// 'customise': show the options in `added`, then call again with the shopper's `variant_id`.
throw new Error('The shopper must choose a variant first');
}
const cart = await call('/store/cart/validate', { cart_id: added.cart.id });
if (cart.is_valid) {
window.location.assign(cart.checkout_url); // Queek takes it from here
}That is the whole checkout integration. There is no order-creation endpoint to call and no payment step to implement.
Bring the customer back to your site
If the connection lists After checkout, send customers back to links, the checkout_url
ends with &return_url= and the first link, and once the customer has paid Queek sends them
there with ?queek_order= and the order's number added:
https://your-store.queek.app/checkout?cart=3f1a8e64-…&return_url=https%3A%2F%2Fshop.example.com%2FthanksWith several links listed, add return_url=<one of them> to the cart request you read
checkout_url from (for example GET /store/cart?return_url=…) to choose which one. A link the
merchant did not list is ignored, never used. With no links listed, customers see Queek's own
thank-you page. The return page is a thank-you page, not proof of payment: see
Rules for AI builders.
Check that it is working
Back on the connection page, Is it working? reads Waiting for your site… until the first request your key is accepted for, then Connected — first request 2 seconds ago. Orders that start from this connection's carts appear under Orders and revenue.
If something is refused, the Problems card says what and why in plain words, with a
one-click fix where one exists (for example Allow shop.example.com). The same refusals
reach your code as an error.code; see
Manage a connection.
Before you ship
| Concern | What to do |
|---|---|
| Going live | Build against a dev store with a Testing on my computer connection, then go live: a new connection on your live store with live keys. |
| Websites | List only the exact https:// addresses your site runs on. * is never accepted on a live connection. |
| Rate limits | 180 requests per minute per key and IP. A 429 carries Retry-After. See Authentication. |
| Failures | Branch on error.code, never on message, and quote error.request_id when you ask for help. See Versioning & errors. |
| Caching | Reads answer with an ETag. Send it back as If-None-Match and an unchanged resource costs a 304. |
| Order status | Queek runs fulfilment, so a storefront never fulfils. Only an external fulfilment system listens to orders/paid, never to the checkout redirect. See Webhooks. |
| Deploying | Use the production address, never a preview address, and live keys on a live store. See Deploy your headless site. |
Where to go next
Deploy your headless site
Pick Server or Website, set the keys on Vercel, Netlify or Cloudflare, allow the production address and go live.
Next.js starter
A server-rendered storefront on the Headless API with a Server connection. Fetch it with npx degit usequeek/developers/examples/nextjs-headless my-store.
Rules for AI builders
The short list of rules an AI tool must follow when it builds on a store: checkout, keys, prices, sign-in, webhooks.
Manage a connection
Replace or turn off a key, allowed websites, return links, status, errors, going live and disconnecting.
Authentication
Public vs secret keys, websites, customer sign-in, rate limits and what each failure means.
Endpoint reference
Every endpoint, parameter and response, generated from the live OpenAPI spec.
Dev stores
Build against a dev store with test keys; create a live connection to go live.
Custom fields
The store's own typed fields on products, variants, collections, blog posts, orders and customers.
Payments
What happens between checkout_url and orders/paid, and the Idempotency-Key contract.
Webhooks
Order events pushed to your server, signed with Standard Webhooks.
The reference is generated from the committed OpenAPI document, spec/openapi.json. Import it
into any OpenAPI client to explore the API interactively.