Skip to content

The shop protocol ​

The addresses a product page and its checkout talk to once the shop module is on: shop/1. What is left of each variant; a cart priced, with the ways of sending it that its country is offered; the checkout, which goes to pay; and the order's page, the one the buyer comes back to from Stripe. What the module reads from the schema is modules; the counts are set with set_stock and corrected by the owner in the panel.

preflight with try_order walks these addresses as a buyer does, on the preview or the address, under the caller's session — a test order on Stripe's sandbox, given back by Stripe's own message — so a page can be proved before anybody else uses it. With VAT on, the parcel goes to the business's own address and the payment is taxed on the sandbox as a live one would be.

At a glance ​

wherethe site's own host, and the same address under a preview; every answer Cache-Control: no-store
the versionshop/1, named in X-Jtk-Shop: 1 on every request; absent is version 1
a productits entry's id, as the build has it
a cart line{ product, variant, qty, answers }: the product's id, the variant's _key, 1 to 999, and an answer for each customization it asks, by the customization's _key — a choice's _key, true, or a text. At most 100 lines
moneywhole minor units of the site's one currency, currency beside them in lower case: 2990 is 29.90
the pricethe platform's, from what is published, every time: the page shows a price and the checkout holds it to the total it showed
the challengeon POST /api/checkout, for a stranger, every time it carries a cart: GET /api/turnstile for the key, a fresh token sent as turnstile; { order } alone is exempt
a field that is not in the table400 JTK_E_SHOP_FIELD_UNKNOWN to somebody the site knows; dropped for a stranger, and get_site lists it in shop_drops
the holdthe stock of a tracked line is held 31 minutes from the press; the last item goes to the first who goes on to pay
a callat most 64 KiB

Versions ​

The protocol has a version, and a page says which it speaks: the header X-Jtk-Shop on every request to the addresses below, 1 today. A page that sends none is version 1. As the booking protocol does, the platform keeps answering every version a live site still speaks, and within a version the protocol only grows: a field may be added to what a page sends or to an answer, and nothing is renamed, removed or changed in meaning or unit. A version the platform does not answer is refused to anybody, before anything is asked, with JTK_E_SHOP_PROTOCOL (400 { error, said, supported }), naming the versions it does answer.

The addresses ​

All on the site's own host. Every answer is Cache-Control: no-store.

GET /api/stock?product=<id>[&product=<id>…]{ products: [{ id, served, variants: [{ key, sku, state, left? }] }] } — each product in the order asked, its id as asked, and its variants in the product's order, by their _key and SKU. 400 for no product, more than 100, or one that is not an entry's id; 409 with a sentence for a site whose schema does not turn the shop on, or whose plan has lapsed
POST /api/shipping{ lines, country, locale? } → 200 { currency, lines: [{ line, product, variant, sku, title, labels, answers, unit, qty, total }], refused: [{ line, code, says }], subtotal, country, sends, cannot_send, abroad, vat_included, own_currency, methods: [{ method, name, pickup, price, free }] }. The cart priced from what the site serves, the lines it refused and why (code is not_sold, off_sale, quantity, answer or too_large; line is the cart's, from 0, and -1 for the whole cart), and the methods the country is offered, each with its price and its name, one line of at most 60 characters: a method whose name is longer is offered to nobody. sends is whether the business sends to the country; cannot_send that it does and no method carries this parcel; abroad that the parcel leaves the business's customs area, so the page says so. vat_included — the business's VAT switch is on, so its prices include VAT: say «incl. VAT» beside them. It is the business's switch, not Stripe's word on a sale: it may be on while Stripe charges no VAT — a registration that lapsed — and a buyer abroad (abroad) may be charged none at the checkout. own_currency — Stripe's page may show a buyer from abroad the price in their own currency, for 2–4% more: «You can pay in your own currency» beside the pay button. Both are the site's switches as they are now, false until the owner turns them on, and the quote a refused checkout carries says them too. A cart with a refused line is offered no method. locale is the language the page is in — a tag such as en or fr-CH — and the lines' title, labels and answers are read in it where the site has that language, the site's own words otherwise: see the buyer's language. Nothing is held and no order is written
POST /api/checkout{ lines, country, method, buyer: { name, email, phone? }, address?: { line1, line2?, postal_code, city }, total, attempt?, return, locale?, turnstile? } → 201 { order, url, expires_at }: the order's token, and Stripe's page to send the buyer to. See going to pay. A second ask is { order } alone
GET /api/order?token=<order>{ state, number?, lines, subtotal, shipping, total, currency, method, pickup, pay_url? } — what the page after payment shows: state is waiting, paid, lapsed or cancelled, the number once it is paid, the lines as they were frozen, what they came to and the method's name. Never the buyer's contact or address. 404 for a token that is nobody's. See the page after payment

The page names the site by nothing: the address it asks is on the site's own host, and the platform answers for that site. Anything in the query that is not in the table is not passed on. A body is a JSON object, or it is refused 400 { error: "invalid_body" }.

A cart, priced:

json
{
  "currency": "chf",
  "lines": [
    {
      "line": 0,
      "product": "0193a5c3-6b1c-7d20-9a31-5e4d3c2b1a02",
      "variant": "v1",
      "sku": "FOX-S-RED",
      "title": "Fox",
      "labels": ["S", "Red"],
      "answers": [{ "key": "engraving", "name": "Engraving", "text": "Ada", "adds": 500 }],
      "unit": 3490,
      "qty": 2,
      "total": 6980
    }
  ],
  "refused": [],
  "subtotal": 6980,
  "country": "CH",
  "sends": true,
  "cannot_send": false,
  "abroad": false,
  "vat_included": true,
  "own_currency": false,
  "methods": [
    { "method": "post", "name": "Post, 2–3 days", "pickup": false, "price": 790, "free": false },
    { "method": "pickup", "name": "Pick up in the shop", "pickup": true, "price": 0, "free": false }
  ]
}

The checkout that follows it, for the first method: the page showed 6980 and 790, so a total of 7770:

json
{
  "lines": [{ "product": "0193a5c3-6b1c-7d20-9a31-5e4d3c2b1a02", "variant": "v1", "qty": 2, "answers": { "engraving": "Ada" } }],
  "country": "CH",
  "method": "post",
  "buyer": { "name": "Ada Lovelace", "email": "ada@example.ch", "phone": "+41 79 000 00 00" },
  "address": { "line1": "Bahnhofstrasse 1", "line2": "", "postal_code": "8001", "city": "Zürich" },
  "total": 7770,
  "attempt": "0193a5c4-2f6e-7c81-b3d0-8e1f5a7c9d24",
  "return": "/thanks",
  "locale": "en",
  "turnstile": "0.AbC…"
}
json
{ "order": "T9zq…", "url": "https://checkout.stripe.com/c/pay/cs_live_…", "expires_at": "2026-11-14T12:31:00Z" }

The order's page, for that order once it is paid:

json
{
  "state": "paid",
  "number": 1001,
  "lines": [
    {
      "line": 0,
      "product": "0193a5c3-6b1c-7d20-9a31-5e4d3c2b1a02",
      "variant": "v1",
      "sku": "FOX-S-RED",
      "title": "Fox",
      "labels": ["S", "Red"],
      "answers": [{ "key": "engraving", "name": "Engraving", "text": "Ada", "adds": 500 }],
      "unit": 3490,
      "qty": 2,
      "total": 6980
    }
  ],
  "subtotal": 6980,
  "shipping": 790,
  "total": 7770,
  "currency": "chf",
  "method": "Post, 2–3 days",
  "pickup": false
}

Going to pay ​

The checkout is one call of the page, and two of the platform's: the shop, then billing, which opens the payment at Stripe. In the first the cart is priced again from what is published and the method is found among what the country is offered; the total the page showed — the subtotal and the method's price — is compared with what it comes to now, and a price that changed in between is refused 409 { error: "total", quote } with the new answer, so the page shows it and the buyer goes on knowing. Nothing is written then. Otherwise the order is written with its lines frozen as they were priced — in the page's locale, where the site has that language (the buyer's language) — and the stock of its tracked lines is held for 31 minutes. A line short of stock refuses the checkout 409 { error: "short", short: [{ sku, wanted, available }], quote }: the last item goes to the first buyer who goes on to pay, and a buyer who is refused leaves nothing of theirs behind. The second call opens the order's one payment, and the answer is Stripe's page, 201.

  • A press is one order. attempt is a token the page makes when the buyer presses pay — random, 16 to 128 letters, digits, - and _; a crypto.randomUUID() is one — and sends again, the same, on every retry of that press: an answer that was lost, or a button pressed twice, is the same order with one hold. It is bound to its buyer: the order is answered only to a press whose buyer.email is the order's, in any case, and the same attempt with another buyer's email is refused 409 { error: "attempt" }, with nothing written. An attempt of any other shape is refused 400, and one left out makes every press a new order. A retry that carries the cart is a checkout like the first, so it passes the challenge again with a fresh widget token. A press that was answered 201 is over; the page mints a new attempt for every new press — after a 201, and after any refusal that says to make a new one.
  • A second ask holds nothing. When the page was not given Stripe's page — 502 try_again, or the connection broke — it asks again with the order's token and no cart: { order }. Billing opens the order's one payment, or answers the one it opened — the same page while it is open — and holds nothing more. A payment is opened only while 30 minutes and 30 seconds of the hold are left, because Stripe counts its half-hour from its own clock; after that, an order with no payment open is answered 410 too_late, is given up and has its stock put back on the shelf, and the cart goes to pay again with a new attempt.
  • What Stripe says decides the hold. Once a payment page is open, the hold ends only on Stripe's word: paid, and the stock is the buyer's; or that the page expired, and it is given back. An order no payment was ever opened for is given back when its 31 minutes end, or when none can be opened any more. A buyer is told an order has lapsed only on Stripe's word that it expired.
  • The return. return is a path on the host the page is on, never an address; the platform puts it on that host. Under a preview it is on the preview's host and under /p/<slug>/, as the page's own under() makes it, and the checkout is a test, paid in Stripe's test mode. It is checked when the order is written and kept on it: a second ask does not name a new one.
  • The buyer's details are kept as typed and handed on as typed — an address in another script is an address. A name is 1 to 120 characters; an email is an address with a dot in its domain, at most 254 bytes — the confirmation is sent to it; a phone is optional, at most 40 characters of digits, spaces and +-(); a delivery asks line1 (1 to 200), line2 (up to 200), postal_code (1 to 20) and city (1 to 100), each on one line. A pick-up asks no address. What is wrong comes back as 400 { error: "buyer", fields: ["buyer.email", "address.line1", …] }.
  • The challenge is passed by every call that carries a cart, and a widget's token can be spent once. A press sent again with its cart — the same attempt, because the answer was lost and the page has no order token — is challenged again, so it needs a fresh token from the widget: the one the first call spent is refused 403 challenge. Only a second ask, { order } with no cart, is never challenged: it holds nothing. Where the host has no widget, nothing is asked and nothing is sent.

The page after payment ​

Stripe sends the buyer back to return with order=<token> on its address, and with left=1 when they left Stripe's page without paying. The page then asks GET /api/order?token=<order>:

  • waiting — Stripe has not said yet: a buyer who has just paid is here for a moment, and one who left is here for good. Ask again after a few seconds, and say so. While the order waits and its payment page is still open the answer carries pay_url: the same Stripe page, to go back to paying — the one address of Stripe's the order's page ever gives, and only for as long as the hold lasts.
  • paid — with its number, counted per site from 1001. The owner is told, in the site's language, and the buyer is sent a confirmation by email in the order's language: the locale the checkout gave, the site's own where it gave none.
  • lapsed — the payment page expired, or the order was given up. Nothing was taken; the cart goes to pay again.
  • cancelled — it was paid and refunded in full before it was fulfilled. The number it had is still its own.

The buyer's language ​

A site may have more than one language, and the cart can be opened on any of its pages. Both POST /api/shipping and POST /api/checkout take an optional locale: the language the page is in, a tag as the site's schema spells it (en, fr-CH; the case of the tag does not matter). The products are read in it where the site has that language, laid over by their translations, so a line with no translation says the site's own words and a price is the same in every language.

  • The cart and the order say the same. The shipping answer's lines carry the titles the checkout then freezes, so a cart shown in English is paid for in English. A page sends the same locale to both.
  • The order keeps it. The lines are frozen in it, and the order's page (GET /api/order) shows them as they were frozen, whatever language it is opened in. The buyer's letters — the confirmation, on its way and ready for pick-up — are written in it, as far as the platform's letters are written in the language (fr-CH is French), and in the site's own otherwise. The owner's letter stays in the site's language.
  • A language the site has not got is the site's own. A locale the site does not have, or one that is no tag, is read as none: a buyer is never refused for the page's word, and neither is a test session, since locale is the contract's. A press asked for again by its attempt is the order it was, in the language it was taken in.
  • The language chooses the words, never what is sold. A language is not a market — a zone is — and a cart filled on one language's page may be checked out from another's. A product the page's language does not offer is priced and sold all the same, in the site's own words; only a product the site's own copy does not serve is refused not_sold. The shipping answer and the checkout agree on it.
  • A shipping method's name is the site's own words in every language: the settings are read as the site wrote them, and only the products are read in the page's language.
  • The stock is no words. GET /api/stock takes no locale.

Abroad ​

abroad in the shipping answer is true when the parcel leaves the business's customs area: Switzerland and Liechtenstein are one, the European Union's customs union, with Monaco and San Marino, is another, and any other country is its own. Say so before payment — customs duties are paid at the door by the buyer — in the checkout step, beside the price, for a method that sends: a buyer who picks up in the shop takes the parcel across no border.

Refusals ​

A refusal a page can act on is JSON, { "error": … }, with its status:

statuserrorsaid bywith it
400JTK_E_SHOP_PROTOCOLthe platformsaid, supported
400JTK_E_SHOP_FIELD_UNKNOWNthe platform, to somebody the site knowsfields (paths), takes
400invalid_bodythe edgethe body is not a JSON object
400buyerthe shopfields: buyer.email, address.line1, …
400returnthe shop; billing, againthe return cannot be used
400nothing_to_paythe shopan empty cart, or one that costs nothing
403challengethe edgethe widget's token is missing or no good
403showcasethe edgemessage — a studio looking at the sample under its preview reads it and never checks out on it: POST /api/checkout is refused before anything is asked of the platform
409refused · method · totalthe shopquote, the new answer
409shortthe shopshort: [{ sku, wanted, available }], quote
409attemptthe shopthis press's token belongs to another checkout: make a new one
410lapsedthe shopthe press's order is gone: a new attempt
429too_many · open_checkoutsthe shopan address asking for too many checkouts in an hour; a buyer with four checkouts open already
424no_payeethe shopno order: the studio's plan holds no shop line for this launched site, so the shop takes no new one — an attempt that has its order is still answered with it; the buyer starts again later
404not_foundbillingorder — nobody's order on this site
409paidbillingorder — already paid: show its page
410lapsed · too_late · too_smallbillingorder — given up, and its hold given back; too_late is a second ask with too little of the hold left, too_small a total under Stripe's least charge in the site's currency. A new cart, a new attempt
422addressbillingorder — Stripe cannot work out the VAT for the delivery's address: the order is given up and its hold given back; the buyer checks the address and starts again
424no_payeebillingorder — the business cannot be paid yet: the order is given up and its hold given back, and the buyer starts again later with a new cart and a new attempt
502try_againbilling, the edgeorder — Stripe was not reached or has not said: ask again with the order's token
500internalbillingorder — ours; asking again will not mend it: the order is given up and its hold given back, and the buyer starts again later

A refusal of the shop's with no JSON — a sentence — is for the developer to read: the site's schema does not turn the shop on, its plan has lapsed, it has no currency, or the call is larger than 64 KiB. So are three more: a stock call that asks after no product, after more than 100, or after one that is not an entry's id (400); a checkout whose attempt is there and is not 16 to 128 letters, digits, - and _ (400 — one left out is taken, and every press of it is a new order); and a fault of ours, 500 with the sentence internal error. A dev session's twin answers 404 to all four addresses: only the site itself, or a preview of it, takes orders.

When billing's answer is 502 try_again or the connection broke after the order was made, the answer says the order, and the page asks again with it. When the shop itself could not be reached — at any of the four addresses — the answer is 502 { error: "try_again" } with no order: ask again, and for a checkout with the same attempt, which is the same order if it was made.

Fields outside the contract ​

The names and shapes above are the whole of it, at every depth of a cart (lines[0].colour), as the API's own structs declare them. A field that is not there — or a number sent as a string — is refused to somebody the site knows (a preview, the studio, its agent) with 400 { error: "JTK_E_SHOP_FIELD_UNKNOWN", fields, takes }: which paths were wrong, and every name that would have been read. From a stranger it is dropped and the cart is read without it, so a buyer is never turned away for the page's mistake — which is why the checkout is tried on the preview before anybody else uses it. Dropped is not unheard: get_site answers with shop_drops — each name, where it was sent, how many times this month — until the page stops sending it. A name is kept only where a page could have meant it: letters, digits, _ and -, in a path of at most 60 characters (lines[].colour), or $, the platform's own name for a body that is not an object at all; every other key a request carries is counted as (a name that is no field), which a stranger's text never reaches.

What is left ​

A variant is in one of three states:

  • in_stock — it can be bought. For a tracked product, left is how many: what is on hand less what checkouts hold while their buyers pay. A product that is not tracked (tracked: false, made to order) is never sold out, and no left is told of it.
  • sold_out — none left: what is on hand is held or gone, or the SKU's stock was never set. A SKU without stock has none — nothing is made up, so a tracked product is sold out until its stock is set.
  • off_sale — not sold, whatever its stock: taken off sale (on_sale: false), or a variant that does not hold (no SKU, a price that is not money, a weight that is not whole grams of 0 or more, picks that do not name the product's options, an on_sale that is not true or false). Every variant of a product is off sale when a customization a buyer must answer does not hold (a choice with no choices, a text without a max of 1 to 500, a required that is not true or false, an adds that is not money): no line of it can be sold. So is every variant of a product over by its own date, its collection's ends_by keeping it on show.

left is told to anyone who asks. Whether a visitor reads 3 left or only in stock is the page's to decide; the count is the same either way.

A product the site does not serve ​

A product the site does not serve is served: false, with no variants — not an error, and nothing to count: one that is hidden, an id of nothing, or one saved in the panel and not yet published. The answer is read from what the site serves, never from the draft. A product deleted in the panel is still served until the publish that takes it off, and is answered until then.

Never cached ​

What is left changes with every checkout, so no answer is cached, by the platform or by the browser: ask with cache: "no-store" when the page is shown. A count a minute old is a buyer sent to pay for the last item somebody else is already holding.