Skip to main content
These hold everywhere in the API, in both directions. Every other Build page assumes them rather than restating them.

​
Base URL

Programmatic endpoints live under the versioned /v1 prefix. The buyer-facing hosted pages live on a separate host, and Taberna returns their full URLs (checkoutUrl for orders, url for invoices) when you create the resource — never construct them yourself.

​
Money

Do not parse either into a float for arithmetic. Use a decimal library or integer minor units. "50" means fifty, not fifty cents, and crypto amounts do not all have 18 decimals.
Fiat pricing currencies are usd and eur. Nothing else is accepted.

​
Timestamps

ISO-8601, UTC — "2026-07-09T12:30:00.000Z". Query parameters that take a timestamp (createdAfter, createdBefore) accept a Z or an explicit offset.

​
Resource ids

Two kinds, and they are not interchangeable.
  • Public short ids address orders and invoices: 21 or 22 base58 characters, like CcvnKdAXzvW8h3JaS1VJe. This is the value that appears in checkout links, the value every webhook carries as data.id, and the value every /v1 path parameter takes for those two resources.
  • UUIDs address products, stores and webhook deliveries.
Short ids are validated against the base58 pattern before any lookup runs, on every route that takes one. A malformed short id is therefore 400 { "error": "Invalid request data" }, not a 404. See Errors.

​
Errors

Every non-2xx response carries the same body:
There is one documented exception: the invoice-send endpoint adds code and retryAfterSeconds. Full detail on Errors.

​
Idempotency

POST /v1/orders and POST /v1/invoices accept an optional Idempotency-Key header, 1 to 255 characters, unique per store. Send it on every create. See Idempotency.

​
Field-level detail

Every request and response field carries its own description, format and example in the API Reference. This page is the shape; that tab is the contract.