Skip to main content
POST
Create an order

Authorizations

Authorization
string
header
required

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

Idempotency-Key
string

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.

Required string length: 1 - 255

Body

application/json
items
object[]
required

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.

Required array length: 1 - 20 elements
customerEmail
string<email>

Where 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).

Example:

"buyer@example.com"

extraContext
object

Arbitrary JSON to carry your own reference alongside the order. Stored verbatim, returned on reads and on webhooks, and never shown to the buyer.

Example:
successUrl
string<uri>

Where the hosted checkout sends the buyer after a successful payment. http/https only, up to 2048 characters.

Maximum string length: 2048
Example:

"https://example.com/thanks"

cancelUrl
string<uri>

Where the hosted checkout sends the buyer if they back out. http/https only, up to 2048 characters.

Maximum string length: 2048
Example:

"https://example.com/cart"

expiresIn
integer

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.

Required range: 10 <= x <= 129600
Example:

30

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.

id
string
required

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.

Example:

"7Kq2mVn8pRt3XwYz5Bd4L"

checkoutUrl
string
required

The hosted checkout page to send the buyer to. This is the one field a create call exists to produce.

Example:

"https://taberna.io/checkout/7Kq2mVn8pRt3XwYz5Bd4L"

status
enum<string>
required

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.

Available options:
pending,
completed,
partial,
expired
Example:

"pending"

expiresAt
string<date-time>
required

When the order stops accepting payment. UTC timestamp in ISO 8601, e.g. 2026-07-29T14:30:00.000Z.

Example:

"2026-07-29T14:30:00.000Z"

items
object[]
required

The products bought, priced as of creation.