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.
Base URL
Section titled “Base URL”Call the store’s own domain (its primary domain, or its *.myciqra.com address):
https://{store domain}/api/storefront/v1The version is in the path. Fields are only ever added to v1; a rename or a removal would be a v2.
Access tokens
Section titled “Access tokens”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.1Host: shop.example.comX-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.
Browsers and CORS
Section titled “Browsers and CORS”A browser calling from another web origin must be on the token’s allowed origins list:
- an origin is
https://hostorhttps://host:port— no path, no wildcard;http://only forlocalhost; - matching is exact:
https://shop.example.comnever admitshttps://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_allowedotherwise); - responses never carry
Access-Control-Allow-Credentials. Usecredentials: "omit"— the API ignores cookies anyway.
A request without an Origin header (your server) has no CORS to satisfy.
No personal data without a customer token
Section titled “No personal data without a customer token”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).
Endpoints
Section titled “Endpoints”| 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 and currency
Section titled “Language and currency”- Language:
Accept-Language, or?locale=en. Names, descriptions and links come back in that language when the store has it. - Currency:
X-Ciqra-Currency: USDor?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
Section titled “The bag”The bag travels in a header, never a cookie:
POST /cart(or the firstPOST /cart/lineswithout a bag) answersX-Ciqra-Cart-Token: g-…— keep it client-side.- Send it as
X-Ciqra-Cart-Tokenon 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.
Checkout
Section titled “Checkout”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.
Customer accounts
Section titled “Customer accounts”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/tokenX-Ciqra-Storefront-Access-Token: ciqra_sfp_…Content-Type: application/json
{ "email": "shopper@example.com", "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.
Caching
Section titled “Caching”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.
Rate limits
Section titled “Rate limits”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.
Errors
Section titled “Errors”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.