Skip to content

Storefront API

The Storefront API lets you build your own front end — a Next.js site, a mobile app, a kiosk — on a CIQRA store. It reads what the store’s website shows a visitor and runs a bag; payment happens on the store’s own hosted checkout.

It is not the App API: it needs no app, no OAuth and no scopes, and it can never read customers, orders or anything a staff member manages.

Call the store’s own domain (its primary domain, or its *.myciqra.com address):

https://{store domain}/api/storefront/v1

The version is in the path. Fields are only ever added to v1; a rename or a removal would be a v2.

The merchant creates tokens in the admin (Settings → Storefront API). A token looks like ciqra_sfp_… and is public by design — it may ship in a browser bundle or an app. Send it on every request:

GET /api/storefront/v1/products HTTP/1.1
Host: shop.example.com
X-Ciqra-Storefront-Access-Token: ciqra_sfp_…
  • A token belongs to one store. On another store’s domain it is unknown (401 invalid_token).
  • The token is shown once, when it is created; the store keeps only its hash. Revoking it takes effect on the next request.
  • Each token has its own allowed origins and rate (see below). A store can have 10 active tokens.

A browser calling from another web origin must be on the token’s allowed origins list:

  • an origin is https://host or https://host:port — no path, no wildcard; http:// only for localhost;
  • matching is exact: https://shop.example.com never admits https://evil-shop.example.com;
  • the preflight (OPTIONS) is answered for any origin an active token of the store lists; the real request is then checked against the token it carries (403 origin_not_allowed otherwise);
  • responses never carry Access-Control-Allow-Credentials. Use credentials: "omit" — the API ignores cookies anyway.

A request without an Origin header (your server) has no CORS to satisfy.

The API removes every cookie from the request before anything reads it, so no shopper session, member bag or B2B price can ride a public token, and no catalogue or bag response has a field for a name, e-mail, phone, address or order. A shopper’s own account is reached only with a customer token (see Customer accounts).

Method Path What it does
GET /shop Store name, domain, base and enabled currencies, locales, API version.
GET /products A page of products. ?collection=, ?category=, ?sort= (default, newest, title, price-asc, price-desc, best-selling), ?page= (1–500), ?limit= (1–100, default 24).
GET /products/{handle} One product: description, images, options, variants with price, compare-at price and availability.
GET /collections The listed collections.
GET /collections/{handle} One collection (its products: /products?collection={handle}).
GET /categories The category tree.
GET /search?q= Products matching q (2–200 characters), in relevance order, paged like /products.
POST /cart A new, empty bag.
GET /cart The bag named by X-Ciqra-Cart-Token.
POST /cart/lines Add a variant: { "variantId", "quantity", "properties", "components", "note" }.
PUT /cart/lines/{lineId} Set a line’s quantity (0 removes it).
DELETE /cart/lines/{lineId} Remove a line.
POST /checkout A one-use link to the store’s checkout for this bag.

Only what an anonymous visitor of the store may browse is returned: drafts, members-only products and products the market does not sell are absent (404).

  • Language: Accept-Language, or ?locale=en. Names, descriptions and links come back in that language when the store has it.
  • Currency: X-Ciqra-Currency: USD or ?currency=USD, if the store enabled it; otherwise the base currency. The API never guesses from the caller’s country, so the same request always answers the same body.

Amounts are decimals in the currency named next to them ({ "amount": 19.9, "currencyCode": "EUR" }), already converted.

The bag travels in a header, never a cookie:

  1. POST /cart (or the first POST /cart/lines without a bag) answers X-Ciqra-Cart-Token: g-… — keep it client-side.
  2. Send it as X-Ciqra-Cart-Token on every bag call.

Adding a line applies exactly the rules of the store’s product page: stock (never more than is sellable), personalization fields, bundle picks, gift notes and market price lists. A refusal comes back with its code:

Status error Meaning
404 variant_not_found No such variant for sale here.
409 out_of_stock Nothing left to add.
409 not_sold_in_market The market’s price list does not sell it.
422 personalization_invalid / bundle_invalid Required fields or bundle picks are missing or wrong.

Raising a line above stock lowers it to what is sellable and adds X-Ciqra-Cart-Stock: adjusted.

POST /checkout answers { "checkoutUrl", "expiresAt" }. Send the shopper’s browser there (a redirect or a new tab). The link works once, for 30 minutes: it moves the bag onto the store’s domain and opens the store’s checkout. After it, the bag token you held no longer addresses that bag — the contact details and address the shopper types at checkout stay between the shopper and the store. Start a new bag for the next order.

A shopper signs in with the store’s own e-mail and password, and you get a customer token for them:

POST /api/storefront/v1/customer/token
X-Ciqra-Storefront-Access-Token: ciqra_sfp_…
Content-Type: application/json
{ "email": "[email protected]", "password": "…" }

The answer is { "accessToken": "ciqra_sfc_…", "expiresAt": "…" }. Send it as X-Ciqra-Customer-Access-Token together with the public token.

Method Path What it does
POST /customer/token Sign in. 401 invalid_credentials, 403 email_not_confirmed, 429 locked / rate_limited, 400 captcha.
POST /customer/token/renew A fresh token; the one you sent stops working (rotation).
DELETE /customer/token Sign out this client.
DELETE /customer/tokens Sign out every client of this shopper.
GET /customer/ The shopper’s profile: name, e-mail, phone, language.
GET /customer/orders The shopper’s orders, newest first (?page=, ?limit=).
GET /customer/orders/{number} One order: lines, totals, shipping address, tracking.
POST /customer/orders/{number}/reorder Puts the order’s items back into the bag (X-Ciqra-Cart-Token) under the same rules as adding them.

Rules worth knowing:

  • A customer token lives 14 days. It works only on the store that issued it, only together with the public token that minted it, and ends at once when the shopper changes or resets their password, the account is closed, or the merchant revokes the public token. A token that is no longer valid answers 401 invalid_customer_token — sign in again.
  • Accounts are per store: the same e-mail in two CIQRA stores is two unrelated accounts.
  • If the store protects sign-in with a captcha, send its response token in X-Captcha-Token.
  • Sign-in has its own budget per public token and client address, on top of the store’s per-account lockout.
  • Every customer response is Cache-Control: no-store, and a catalogue read that carries a customer token is never marked shareable.

Catalogue reads (/shop, /products, /collections, /categories, /search) answer Cache-Control: public, max-age=60, stale-while-revalidate=300 with an ETag and Vary: Origin, Accept-Language, X-Ciqra-Currency, X-Ciqra-Storefront-Access-Token; revalidate with If-None-Match for a 304. Your CDN may cache them on those keys. Bag, checkout and every error answer Cache-Control: no-store.

Each token has a budget the merchant sets (60 to 6,000 requests a minute, default 600; bursts up to 120), and the store has a ceiling across all its tokens. Over it you get 429 rate_limited with Retry-After in seconds. Use one token per client (web, app, server) so one does not spend another’s budget.

Every refusal is { "error": "<code>", "message": "<sentence>" } with the HTTP status: 400 bad input, 401 invalid_token, 403 origin_not_allowed, 404 not found (also when the store has switched the API off), 409 conflict, 422 invalid fields, 429 rate_limited.