Orders

An order is a purchase of one or more listed products, each with a quantity. Taberna computes the total from the products’ own prices, reserves any finite delivery stock for the order’s lifetime, and hands you a hosted checkout link. Use orders when your prices live in a catalogue. When the amount is composed per request, use Invoices instead. Amounts, timestamps and ids follow the conventions that hold across the API.

Create an order

POST /v1/orders — requires the orders:write scope.

Request body

Field	Required	What it is for
`items`	yes	1 to 20 line items, each `{ "productId": string, "quantity": integer }`
`customerEmail`	no	The receipt and any digital delivery, echoed in webhooks. If omitted, the hosted checkout can collect it
`extraContext`	no	Arbitrary JSON echoed back verbatim in every webhook for this order. Put your user id or purchase id here
`successUrl`	no	Where the Continue button on the completed page points
`cancelUrl`	no	The return link on the dead-end states — expired and partial
`expiresIn`	no	Minutes the order stays payable. Defaults to 30

Exact types, bounds and formats for every field are in the API Reference; the bounds that bite are collected on Request limits. About items:

Every product must belong to the key’s store, be listed, and share a single currency with the rest of the cart.
A productId that appears more than once has its quantities summed into one line — a cart is deduplicated, not rejected.
The order total is Σ (product price × quantity).

A longer expiresIn holds any reserved delivery stock out of circulation for exactly as long. Widen the window deliberately, not by default.

The `Idempotency-Key` header

Optional, 1 to 255 characters, unique per store. Retrying a create with a key this store has already used returns the original order — same id, same everything — instead of minting a duplicate, no matter how the request body changed. Keys never expire, so use one per logical purchase; your own purchase id is the natural choice. Full semantics in Idempotency.

Example

curl -X POST https://api.taberna.io/v1/orders \
  -H 'Authorization: Bearer tbrn_live_…' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: purchase_8213' \
  -d '{
    "items": [
      { "productId": "0197f8a0-1111-7aaa-8ccc-3e5d7c9b1a24", "quantity": 2 },
      { "productId": "0197f8a0-3333-7ccc-8eee-5f7d9e1b3a46", "quantity": 1 }
    ],
    "customerEmail": "buyer@example.com",
    "extraContext": { "userId": "u_123", "cartId": "c_991" },
    "successUrl": "https://yourapp.com/thanks",
    "cancelUrl": "https://yourapp.com/cart",
    "expiresIn": 60
  }'

const res = await fetch('https://api.taberna.io/v1/orders', {
	method: 'POST',
	headers: {
		Authorization: `Bearer ${process.env.TABERNA_API_KEY}`,
		'Content-Type': 'application/json',
		'Idempotency-Key': purchaseId,
	},
	body: JSON.stringify({
		items: [
			{ productId: '0197f8a0-1111-7aaa-8ccc-3e5d7c9b1a24', quantity: 2 },
			{ productId: '0197f8a0-3333-7ccc-8eee-5f7d9e1b3a46', quantity: 1 },
		],
		customerEmail: 'buyer@example.com',
		extraContext: { userId: 'u_123', cartId: 'c_991' },
		successUrl: 'https://yourapp.com/thanks',
		cancelUrl: 'https://yourapp.com/cart',
		expiresIn: 60,
	}),
});

res = requests.post(
	"https://api.taberna.io/v1/orders",
	headers={
		"Authorization": f"Bearer {api_key}",
		"Content-Type": "application/json",
		"Idempotency-Key": purchase_id,
	},
	json={
		"items": [
			{"productId": "0197f8a0-1111-7aaa-8ccc-3e5d7c9b1a24", "quantity": 2},
			{"productId": "0197f8a0-3333-7ccc-8eee-5f7d9e1b3a46", "quantity": 1},
		],
		"customerEmail": "buyer@example.com",
		"extraContext": {"userId": "u_123", "cartId": "c_991"},
		"successUrl": "https://yourapp.com/thanks",
		"cancelUrl": "https://yourapp.com/cart",
		"expiresIn": 60,
	},
)

201 Created

{
  "id": "CcvnKdAXzvW8h3JaS1VJe",
  "checkoutUrl": "https://taberna.io/checkout/CcvnKdAXzvW8h3JaS1VJe",
  "status": "pending",
  "expiresAt": "2026-07-09T13:00:00.000Z",
  "items": [
    {
      "productId": "0197f8a0-1111-7aaa-8ccc-3e5d7c9b1a24",
      "title": "Pro licence",
      "quantity": 2,
      "unitPrice": "50",
      "currency": "usd"
    },
    {
      "productId": "0197f8a0-3333-7ccc-8eee-5f7d9e1b3a46",
      "title": "Priority support",
      "quantity": 1,
      "unitPrice": "9.99",
      "currency": "usd"
    }
  ]
}

unitPrice is a fiat decimal string with no trailing-zero padding — "50" is $50.00. The create response deliberately returns only what you need to proceed; GET /v1/orders/{id} returns the full order.

Errors

All of these are 400 with a { "error": … } body. Anything the request schema rejects never reaches the order logic — the validator answers first, always with the generic { "error": "Invalid request data" }. The messages below are the ones the order logic itself produces, once the body’s shape is already known to be valid.

Message	Cause
`Product not found`	A `productId` does not exist
`Product does not belong to this store`	A product belongs to a different store than the key
`Product is not available`	A product is not `listed`
`All items must use the same currency`	The cart mixes USD and EUR products
`Minimum order quantity for {title} is {n}`	Below the product’s configured minimum
`Maximum order quantity for {title} is {n}`	Above the product’s configured maximum
`Store not found`	The key’s store no longer exists
`Store has no payment methods enabled`	Enable at least one payment method in the dashboard
`Product is out of stock`	A line item could not reserve delivery stock — the whole order rolls back

Quantity bounds come from the product’s delivery configuration and default to a minimum of 1 and no maximum. See Quantity bounds.

Product does not belong to this store is the API’s one deliberate exception to reporting another store’s resources as simply missing. Treat it as a signal you have crossed keys and stores, not as a lookup to depend on — see Errors.

Retrieve an order

GET /v1/orders/{id} — requires orders:read. {id} is the order’s public short id.

200 OK

{
  "id": "CcvnKdAXzvW8h3JaS1VJe",
  "status": "completed",
  "priceAmount": "109.99",
  "priceCurrency": "usd",
  "successUrl": "https://yourapp.com/thanks",
  "cancelUrl": "https://yourapp.com/cart",
  "customerEmail": "buyer@example.com",
  "extraContext": { "userId": "u_123", "cartId": "c_991" },
  "paymentMethod": "usdc_base",
  "cryptoAmount": "109990000",
  "receivedAmount": "109990000",
  "transactions": [
    {
      "blockchain": "base",
      "txHash": "0xabc…",
      "fromAddress": "0xdef…",
      "amount": "109990000",
      "blockNumber": "21458822",
      "blockTime": "2026-07-09T12:15:02.000Z"
    }
  ],
  "items": [
    {
      "productId": "0197f8a0-1111-7aaa-8ccc-3e5d7c9b1a24",
      "title": "Pro licence",
      "image": null,
      "quantity": 2,
      "unitPrice": "50",
      "amount": "100"
    }
  ],
  "checkoutUrl": "https://taberna.io/checkout/CcvnKdAXzvW8h3JaS1VJe",
  "createdAt": "2026-07-09T12:00:04.000Z",
  "expiresAt": "2026-07-09T13:00:00.000Z",
  "completedAt": "2026-07-09T12:15:04.000Z"
}

paymentMethod, cryptoAmount, receivedAmount and transactions all describe a single payment attempt, chosen in this order: the attempt that completed the order; otherwise the best-funded one, holding the largest receivedAmount; otherwise the most recent. They are null (and transactions is []) while no attempt has been started.

The best-funded tier is not a detail. Switching token abandons an attempt but leaves it watched and payable, so the attempt that actually took the money is often older than the last quote the buyer requested. Picking it here is what keeps these fields agreeing with the order.partial webhook, which reports the attempt the indexer credited. A well-formed id that does not resolve — undecodable, unknown, or an order belonging to another store — answers 404 with { "error": "Order not found" }. An order you cannot see is reported as missing, never as forbidden. A malformed id is a 400; see Errors.

List orders

GET /v1/orders — requires orders:read. Newest first.

Query parameter	Type	Notes
`page`	integer	Defaults to `1`
`limit`	integer	1 to 100, defaults to `20`
`status`	enum	`pending`, `completed`, `partial`, `expired`
`createdAfter`	string	ISO-8601 with a `Z` or an offset. Inclusive lower bound
`createdBefore`	string	ISO-8601 with a `Z` or an offset. Inclusive upper bound

200 OK

{
  "data": [ /* orders, in the shape above */ ],
  "pagination": { "page": 1, "limit": 20, "total": 137, "totalPages": 7 }
}

Expire an order

POST /v1/orders/{id}/expire — requires orders:write. Ends a pending order now rather than waiting out its window. This fires the order.expired webhook and returns any reserved delivery stock to the pool, which is the main reason to call it: an abandoned cart holding the last five licence keys is worth reclaiming. Returns 200 with the full order, now expired.

Status	Message	Cause
`400`	`Invalid request data`	`{id}` is not a well-formed short id
`404`	`Order not found`	Well-formed id that does not resolve: unknown, or from another store
`400`	`Only pending orders can be expired`	Already `completed`, `partial` or `expired` — including an order this very call just turned `partial`
`400`	`Order has already been completed`	It completed while the request was in flight
`400`	`Order has a payment in progress — try again after it expires`	A payment attempt is live; its quote must lapse first

Like voiding an invoice, the call retires every still-watchable attempt first, so no lapsed-but-unreaped deposit address is left collecting funds for an order that can no longer be paid. If one of those attempts was holding funds, retiring it turns the order partial — terminal — and the call then fails with Only pending orders can be expired. Re-read the order to see the partial status. An order that was already expired when the call arrived is refused with Only pending orders can be expired. The one case that returns a body instead is the narrow race where a concurrent request expires it after this one read it — then you get the expired order back, because your intent already holds.

Statuses

Status	Meaning
`pending`	Payable. The buyer may start and retry payment attempts. Initial state.
`completed`	An attempt received the full amount on-chain. Terminal — fulfil here.
`partial`	An attempt’s window lapsed holding a non-zero but insufficient amount. Terminal; resolve manually.
`expired`	The window elapsed with nothing received, or you called the expire endpoint. Terminal.

Note that picking a coin does not change the order’s status — it creates a payment attempt under the order, which stays pending. See Payment lifecycle for the attempt-level state machine and what each transition means.

Multi-item and currency rules

One currency per order

An order snapshots exactly one currency, taken from its products. Mixing a USD product with a EUR product is All items must use the same currency. If you sell in both, keep separate carts.

Duplicate products are merged

The response’s items array may therefore be shorter than the array you sent.

Prices are snapshotted

items[].title, unitPrice and image are captured at creation. Editing the product later never rewrites a past order — which is what makes webhooks and receipts trustworthy after the fact.

Stock reservation is all-or-nothing

Every line item that needs finite stock reserves it inside one transaction. If any line cannot, the whole create fails with Product is out of stock and nothing is held. Reservations are released when the order expires.

Get started

Charging a customer

Getting paid

Reference

Create an order

Request body

The `Idempotency-Key` header

Example

Errors

Retrieve an order

List orders

Expire an order

Statuses

Multi-item and currency rules

One currency per order

Duplicate products are merged

Prices are snapshotted

Stock reservation is all-or-nothing

​Create an order

​Request body

​The Idempotency-Key header

​Example

​Errors

​Retrieve an order

​List orders

​Expire an order

​Statuses

​Multi-item and currency rules

​One currency per order

​Duplicate products are merged

​Prices are snapshotted

​Stock reservation is all-or-nothing

Create an order

Request body

The `Idempotency-Key` header

Example

Errors

Retrieve an order

List orders

Expire an order

Statuses

Multi-item and currency rules

One currency per order

Duplicate products are merged

Prices are snapshotted

Stock reservation is all-or-nothing