Create an order
Creates a pending order for a cart of listed products and returns the hosted checkout link to send the buyer. Requires the orders:write scope.
All items must share one currency, and stock for finite products is reserved for the order’s lifetime — an order that expires releases it again.
Authorizations
A store API key, sent as Authorization: Bearer <key>.
A key looks like tbrn_live_ followed by 48 hex characters, e.g. tbrn_live_4f2a...c91b. Mint one in the Taberna dashboard under Developers → API Keys, tick the scopes the integration needs, and copy it there and then — the full value is shown once and only its hash is stored, so a lost key is replaced rather than recovered.
One key belongs to one store and carries a fixed scope set. Send it from a server, never from a browser: it can create orders and invoices and read every order the store has.
Headers
Optional replay guard, 1–255 characters. Retrying a create with a key already used by this store returns the original resource instead of making a second one.
1 - 255Body
The cart: one entry per product, 1–20 of them. A single-product purchase is a one-entry cart. Every item must be a listed product of this store, and all of them must share one currency.
1 - 20 elementsWhere to send the receipt and any digital delivery. Optional here — if you omit it, the hosted checkout collects it from the buyer (and requires it, when the store is configured that way).
"buyer@example.com"
Arbitrary JSON to carry your own reference alongside the order. Stored verbatim, returned on reads and on webhooks, and never shown to the buyer.
Where the hosted checkout sends the buyer after a successful payment. http/https only, up to 2048 characters.
2048"https://example.com/thanks"
Where the hosted checkout sends the buyer if they back out. http/https only, up to 2048 characters.
2048"https://example.com/cart"
How long the buyer has to pay, in minutes (10–129600). Reserved stock is held for exactly this long. Defaults to 30 when omitted — the same window every hosted flow uses.
10 <= x <= 12960030
Response
The order, with the checkout link to send the buyer. A replayed Idempotency-Key returns the original order with this same status.
A newly created order and the link to send the buyer.
The new order's id. Base58 short id, 21–22 characters (never 0, O, I or l), e.g. 7Kq2mVn8pRt3XwYz5Bd4L — the value that appears in checkout and invoice links, and the one this API takes as a path id.
"7Kq2mVn8pRt3XwYz5Bd4L"
The hosted checkout page to send the buyer to. This is the one field a create call exists to produce.
"https://taberna.io/checkout/7Kq2mVn8pRt3XwYz5Bd4L"
Where the order is in its lifecycle. pending — created, waiting for the buyer to pay. completed — paid in full; any digital delivery has been released. partial — funds arrived but fell short of the locked quote. expired — the payment window closed without full payment, and any reserved stock went back to the pool. A freshly created order is always pending.
pending, completed, partial, expired "pending"
When the order stops accepting payment. UTC timestamp in ISO 8601, e.g. 2026-07-29T14:30:00.000Z.
"2026-07-29T14:30:00.000Z"
The products bought, priced as of creation.