Queek docs

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:

  1. 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.
  2. Open Channels → Headless API and press Connect a site or app.
  3. Under What are you building?, pick one:
You pickYou getWebsitesGood to know
WebsiteA public keyYou must list the site, for example https://shop.example.comBrowser code runs only from a listed website.
Mobile appA public keyNoneAn 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 backendA public key and a secret keyNoneThe secret key is shown once. Keep it on your server.
AI agentA public keyNoneThe agent can browse products and build carts only. It cannot reach accounts, orders or checkout calls.
Testing on my computerA pk_test_ keyThis computer is always allowedDev stores only. Uses the dev store's sample data and never real money. You can go live later.
  1. Give it a name, add the website address if it asks for one, and optionally the page customers should return to after checkout.
  2. 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.

KeyLooks likeWhere it belongs
Public keypk_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 keysk_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/deploy

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

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

A page of products
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.

Add a line
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.

Validate, then hand off
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:

Add, validate, hand off
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%2Fthanks

With 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

ConcernWhat to do
Going liveBuild against a dev store with a Testing on my computer connection, then go live: a new connection on your live store with live keys.
WebsitesList only the exact https:// addresses your site runs on. * is never accepted on a live connection.
Rate limits180 requests per minute per key and IP. A 429 carries Retry-After. See Authentication.
FailuresBranch on error.code, never on message, and quote error.request_id when you ask for help. See Versioning & errors.
CachingReads answer with an ETag. Send it back as If-None-Match and an unchanged resource costs a 304.
Order statusQueek runs fulfilment, so a storefront never fulfils. Only an external fulfilment system listens to orders/paid, never to the checkout redirect. See Webhooks.
DeployingUse the production address, never a preview address, and live keys on a live store. See Deploy your headless site.

Where to go next

The reference is generated from the committed OpenAPI document, spec/openapi.json. Import it into any OpenAPI client to explore the API interactively.

On this page