Appearance
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
| where | the site's own host, and the same address under a preview; every answer Cache-Control: no-store |
| the version | shop/1, named in X-Jtk-Shop: 1 on every request; absent is version 1 |
| a product | its 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 |
| money | whole minor units of the site's one currency, currency beside them in lower case: 2990 is 29.90 |
| the price | the platform's, from what is published, every time: the page shows a price and the checkout holds it to the total it showed |
| the challenge | on 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 table | 400 JTK_E_SHOP_FIELD_UNKNOWN to somebody the site knows; dropped for a stranger, and get_site lists it in shop_drops |
| the hold | the 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 call | at 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.
attemptis a token the page makes when the buyer presses pay — random, 16 to 128 letters, digits,-and_; acrypto.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 whosebuyer.emailis the order's, in any case, and the sameattemptwith another buyer's email is refused409 { error: "attempt" }, with nothing written. Anattemptof any other shape is refused400, 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 answered201is over; the page mints a newattemptfor every new press — after a201, 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 answered410 too_late, is given up and has its stock put back on the shelf, and the cart goes to pay again with a newattempt. - 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.
returnis 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 ownunder()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 asksline1(1 to 200),line2(up to 200),postal_code(1 to 20) andcity(1 to 100), each on one line. A pick-up asks no address. What is wrong comes back as400 { 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 refused403 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 carriespay_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 itsnumber, 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: thelocalethe 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
localeto 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-CHis 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
localethe 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, sincelocaleis the contract's. A press asked for again by itsattemptis 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
nameis 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/stocktakes nolocale.
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:
| status | error | said by | with it |
|---|---|---|---|
| 400 | JTK_E_SHOP_PROTOCOL | the platform | said, supported |
| 400 | JTK_E_SHOP_FIELD_UNKNOWN | the platform, to somebody the site knows | fields (paths), takes |
| 400 | invalid_body | the edge | the body is not a JSON object |
| 400 | buyer | the shop | fields: buyer.email, address.line1, … |
| 400 | return | the shop; billing, again | the return cannot be used |
| 400 | nothing_to_pay | the shop | an empty cart, or one that costs nothing |
| 403 | challenge | the edge | the widget's token is missing or no good |
| 403 | showcase | the edge | message — 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 |
| 409 | refused · method · total | the shop | quote, the new answer |
| 409 | short | the shop | short: [{ sku, wanted, available }], quote |
| 409 | attempt | the shop | this press's token belongs to another checkout: make a new one |
| 410 | lapsed | the shop | the press's order is gone: a new attempt |
| 429 | too_many · open_checkouts | the shop | an address asking for too many checkouts in an hour; a buyer with four checkouts open already |
| 424 | no_payee | the shop | no 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 |
| 404 | not_found | billing | order — nobody's order on this site |
| 409 | paid | billing | order — already paid: show its page |
| 410 | lapsed · too_late · too_small | billing | order — 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 |
| 422 | address | billing | order — 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 |
| 424 | no_payee | billing | order — 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 |
| 502 | try_again | billing, the edge | order — Stripe was not reached or has not said: ask again with the order's token |
| 500 | internal | billing | order — 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,leftis 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 noleftis 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, aweightthat is not whole grams of 0 or more, picks that do not name the product's options, anon_salethat is nottrueorfalse). Every variant of a product is off sale when a customization a buyer must answer does not hold (achoicewith no choices, atextwithout amaxof 1 to 500, arequiredthat is nottrueorfalse, anaddsthat is not money): no line of it can be sold. So is every variant of a product over by its own date, its collection'sends_bykeeping 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.