> ## Documentation Index > Fetch the complete documentation index at: https://docs.taberna.io/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Taberna is a crypto payments API. Amounts are priced in fiat (USD or EUR) and paid in crypto. > Fiat amounts are ALWAYS decimal strings ("9.99"), never numbers. Crypto amounts are integer strings in the asset's smallest unit. > Authenticate merchant endpoints with `Authorization: Bearer tbrn_live_...`. Every key is bound to one store and carries an explicit scope set, so never pass a store id to a /v1 endpoint. > A 401 means the credential is bad; a 403 means the key lacks a scope. Never retry or re-authenticate on a 403 — surface it as a configuration error. > The /v1/checkouts endpoints are deliberately unauthenticated and run in the buyer's browser. Never send an API key to a browser. > Verify webhook signatures over the RAW request body before parsing JSON, and treat delivery as at-least-once: handlers must be idempotent. > Never grant value based on a browser redirect to successUrl. Fulfil on a signature-verified webhook, or on a server-side read of GET /v1/orders/{id} or GET /v1/invoices/{id}. > There is no test mode: every payment method is a live chain moving real funds. > A merchant can run an entire shop with no code: the dashboard creates products and invoices, and every store can host a storefront at {slug}.taberna.io with its own theme, sections, branding and optional custom domain. Never assume the reader has an API integration. > Taberna issues no refunds and performs no KYC. A refund is something the merchant sends from their own payout wallet, off-platform. # List invoices > The store's invoices, newest first, optionally filtered by status. Requires the `invoices:read` scope. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/invoices openapi: 3.1.0 info: title: Taberna API description: >- Accept crypto payments for digital goods. Create orders and invoices, hand the buyer a hosted checkout link, and let webhooks tell you when the money lands. Authenticate merchant endpoints with a store API key as a bearer token (`Authorization: Bearer tbrn_live_…`). Every key is bound to one store and carries an explicit set of scopes; the scope a route requires is stated in its description and in the `x-required-scope` extension. A key without the scope gets a 403 — mint one with the scope rather than retrying. The Checkout endpoints are the exception: they are unauthenticated and meant to be called from the buyer's browser. Possession of the checkout id is the credential there, so never ship an API key to a page. Conventions: ids in links are short ids; fiat amounts are decimal strings ("9.99"); crypto amounts are integer strings in the asset's smallest unit; timestamps are ISO-8601 UTC. Errors carry `{ "error": "…" }` unless documented otherwise. version: 1.0.0 servers: - url: https://api.taberna.io description: Taberna API security: [] tags: - name: Orders description: Carts of products, paid through a hosted checkout. - name: Invoices description: Merchant-issued bills with their own payment page. - name: Invoice Templates description: Saved invoice presets, referenced by `templateId` when creating one. - name: Products description: Catalogue reads and delivery stock top-ups. - name: Store description: What the calling API key is and what it may do. - name: Webhook Deliveries description: Delivery history for the store webhook, and replay. - name: Checkout description: >- Buyer-facing hosted-page endpoints. Unauthenticated by design — never send an API key. paths: /v1/invoices: get: tags: - Invoices summary: List invoices description: >- The store's invoices, newest first, optionally filtered by status. Requires the `invoices:read` scope. operationId: getV1Invoices parameters: - in: query name: page schema: default: 1 example: 1 type: integer exclusiveMinimum: 0 description: Page to return, 1-based. - in: query name: limit schema: default: 20 example: 20 type: integer minimum: 1 maximum: 100 description: Rows per page, 1–100. - in: query name: status schema: type: string enum: - open - paid - partial - expired - voided example: open description: >- Return only invoices with this status. Where the invoice is in its lifecycle. `open` — issued and payable. `paid` — settled in full. `partial` — funds arrived but fell short. `expired` — the payment window closed unpaid. `voided` — cancelled by the merchant, no longer payable. responses: '200': description: A page of invoices. content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string description: >- The invoice'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 number: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Human-facing invoice number, counting up per store from 1. Distinct from `id`, which is what the API and the payment link use. example: 1042 status: type: string enum: - open - paid - partial - expired - voided description: >- Where the invoice is in its lifecycle. `open` — issued and payable. `paid` — settled in full. `partial` — funds arrived but fell short. `expired` — the payment window closed unpaid. `voided` — cancelled by the merchant, no longer payable. example: open url: type: string description: >- The hosted payment page for this invoice — what a customer opens to pay it. example: https://taberna.io/invoice/7Kq2mVn8pRt3XwYz5Bd4L items: type: array items: type: object properties: name: type: string description: What is being billed. example: Design retainer — July description: anyOf: - type: string - type: 'null' description: >- Optional longer note shown under the line name. Null when unset. quantity: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Units billed on this line. example: 1 unitAmount: type: string description: >- Price of one unit. Decimal string in the resource's fiat currency, e.g. `"49.99"` — a string, never a JSON number, so no precision is lost in transit. example: '49.99' amount: type: string description: >- Line total — `unitAmount` × `quantity`. Decimal string in the resource's fiat currency, e.g. `"49.99"` — a string, never a JSON number, so no precision is lost in transit. example: '49.99' required: - name - description - quantity - unitAmount - amount description: One line on the invoice. description: The billed lines, in the order they were entered. totalAmount: type: string description: >- Sum of every line. Decimal string in the resource's fiat currency, e.g. `"49.99"` — a string, never a JSON number, so no precision is lost in transit. example: '49.99' currency: type: string enum: - usd - eur description: >- The fiat currency every amount on this resource is priced in. Crypto is quoted against it at payment time. example: usd customerName: anyOf: - type: string - type: 'null' description: >- Who the invoice is addressed to, shown on the payment page. Null when unset. example: Acme GmbH customerEmail: anyOf: - type: string - type: 'null' description: >- The only address the send endpoint will email; it cannot be overridden per send. Null when unset, which also makes the invoice unsendable. example: billing@acme.example memo: anyOf: - type: string - type: 'null' description: >- Free-text note shown to the customer on the payment page. Null when unset. example: Net 14. Thanks! metadata: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' description: >- The arbitrary JSON object you attached at creation, returned untouched. Merchant-only: it never reaches the customer's payment page. example: ledgerRef: INV-2026-1042 successUrl: anyOf: - type: string - type: 'null' description: >- Where the payment page sends the customer once the invoice is paid. Null when none was set. example: https://example.com/thanks cancelUrl: anyOf: - type: string - type: 'null' description: >- Where the payment page sends the customer if they back out. Null when none was set. example: https://example.com/billing createdVia: type: string enum: - api - dashboard description: >- Where the invoice came from. `api` — this API. `dashboard` — a human created it in the Taberna dashboard. example: api expiresAt: type: string format: date-time description: >- When the invoice stops accepting payment. UTC timestamp in ISO 8601, e.g. `2026-07-29T14:30:00.000Z`. example: '2026-07-29T14:30:00.000Z' paidAt: anyOf: - type: string format: date-time description: >- UTC timestamp in ISO 8601, e.g. `2026-07-29T14:30:00.000Z`. example: '2026-07-29T14:30:00.000Z' - type: 'null' description: >- When the invoice was settled in full. Null until it is. UTC timestamp in ISO 8601, e.g. `2026-07-29T14:30:00.000Z`. voidedAt: anyOf: - type: string format: date-time description: >- UTC timestamp in ISO 8601, e.g. `2026-07-29T14:30:00.000Z`. example: '2026-07-29T14:30:00.000Z' - type: 'null' description: >- When the merchant voided the invoice. Null unless voided. UTC timestamp in ISO 8601, e.g. `2026-07-29T14:30:00.000Z`. createdAt: type: string format: date-time description: >- When the invoice was issued. UTC timestamp in ISO 8601, e.g. `2026-07-29T14:30:00.000Z`. example: '2026-07-29T14:30:00.000Z' email: type: object properties: sendCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: How many times this invoice has been emailed. example: 1 sendsRemaining: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Sends left for this invoice before the per-invoice cap is reached. example: 2 maxSends: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: The per-invoice cap on emails. example: 3 lastSentAt: anyOf: - type: string format: date-time description: >- UTC timestamp in ISO 8601, e.g. `2026-07-29T14:30:00.000Z`. example: '2026-07-29T14:30:00.000Z' - type: 'null' description: >- When the invoice was last emailed. Null if it never has been. UTC timestamp in ISO 8601, e.g. `2026-07-29T14:30:00.000Z`. cooldownUntil: anyOf: - type: string format: date-time description: >- UTC timestamp in ISO 8601, e.g. `2026-07-29T14:30:00.000Z`. example: '2026-07-29T14:30:00.000Z' - type: 'null' description: >- When the next send becomes possible, while a cooldown is in force. Null when no cooldown applies. UTC timestamp in ISO 8601, e.g. `2026-07-29T14:30:00.000Z`. canSend: type: boolean description: >- Whether this invoice's own state and allowance would let a send through right now. False means `blockedReason` says why. True is not a promise: the store and platform 24-hour caps are not evaluated here, and either can still answer 429. example: true blockedReason: anyOf: - type: string - type: 'null' description: >- Why a send would be refused — the invoice is not open, it has no customer email, its own send allowance is spent, or it is still in cooldown. Null when `canSend` is true. example: Cooldown in effect required: - sendCount - sendsRemaining - maxSends - lastSentAt - cooldownUntil - canSend - blockedReason description: The invoice's remaining email allowance. required: - id - number - status - url - items - totalAmount - currency - customerName - customerEmail - memo - metadata - successUrl - cancelUrl - createdVia - expiresAt - paidAt - voidedAt - createdAt - email description: An invoice as the merchant API reports it. description: The invoices on this page. Newest first. pagination: type: object properties: page: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: The page that was returned, 1-based. example: 1 limit: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Rows per page, as requested (max 100). example: 20 total: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Total rows matching the filter, across all pages. example: 137 totalPages: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Number of pages at this `limit`. Zero when nothing matched. example: 7 required: - page - limit - total - totalPages description: Where this page sits in the full result set. required: - data - pagination '400': description: >- The request failed validation (`{ "error": "Invalid request data" }`), or the operation is not allowed in the resource's current state. content: application/json: schema: type: object properties: error: type: string description: >- Human-readable explanation of what went wrong. Meant for logs and developers, not for branching — switch on the HTTP status instead. example: Order not found required: - error description: The standard error body, returned by every failing endpoint. example: error: Order not found '401': description: >- Missing, malformed, revoked or expired API key. The `WWW-Authenticate` header names the challenge that failed. content: application/json: schema: type: object properties: error: type: string description: >- Human-readable explanation of what went wrong. Meant for logs and developers, not for branching — switch on the HTTP status instead. example: Order not found required: - error description: The standard error body, returned by every failing endpoint. example: error: Order not found '403': description: The key is valid but was not granted the scope this route requires. content: application/json: schema: type: object properties: error: type: string description: >- Human-readable explanation of what went wrong. Meant for logs and developers, not for branching — switch on the HTTP status instead. example: Order not found required: - error description: The standard error body, returned by every failing endpoint. example: error: Order not found security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- A store API key, sent as `Authorization: Bearer `. 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. ````