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.

Create an order

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

Request body

Field	Type	Required	Notes
`items`	array	yes	1 to 20 line items, each `{ "productId": string, "quantity": integer }`. `quantity` is 1 to 1,000,000.
`customerEmail`	string	no	Used for the receipt and any digital delivery, and echoed back in webhooks. If omitted, the hosted checkout can collect it from the buyer.
`extraContext`	object	no	Arbitrary JSON attached to the order and echoed back verbatim in every webhook for it. Put your user id or purchase id here.
`successUrl`	string	no	`http`/`https` URL, at most 2048 characters. Once payment completes the hosted page shows a Continue button linking here.
`cancelUrl`	string	no	`http`/`https` URL, at most 2048 characters. Shown as a return link on the dead-end states — expired and partial.
`expiresIn`	integer	no	How long the order stays payable, in minutes: 10 to 129,600 (90 days). Defaults to 30.

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. This holds no matter how the request body changed: one key, one order. Keys never expire, so a create months later that reuses an old key returns that old order. Use one key per logical purchase; your own purchase id is the natural choice. A key outside the 1–255 range is rejected with { "error": "Idempotency-Key must be between 1 and 255 characters" }.

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 — an empty items, more than 20 line items, expiresIn outside 10 to 129,600, a quantity outside 1 to 1,000,000, a productId that is not a UUID, a successUrl that is not http(s) or is over 2048 characters — never reaches the order logic. The validator answers first, always with the same generic body:

400 Bad Request

{ "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 Products and delivery.

Product does not belong to this store distinguishes “another store’s id” from “no such id”, where the rest of the API reports a resource you cannot see as simply missing. Treat it as a signal you have crossed keys and stores — a live key against a test store’s product ids, say — not as a lookup you should depend on.

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.

An id that is not a well-formed short id fails the route’s validation and answers 400 with { "error": "Invalid request data" }. An id that is well-formed but 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.

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`
`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

Expiring an order that a concurrent request already expired is not an error — 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.

Two things that are easy to get wrong:

Picking a coin does not change the order’s status. It creates a payment attempt under the order, which stays pending. The order.processing webhook fires when the first attempt is created, as a “buyer engaged” signal — it is not a status.
An attempt that lapses with zero funds does not affect the order. The buyer can keep retrying with fresh quotes until the order itself expires.

See Payment lifecycle for the attempt-level state machine.

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

Sending the same productId in two entries sums the quantities into one line item. The response’s items array therefore may 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

​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

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