Invoices

An invoice is a bill with line items and amounts you supply in the create call. No product setup, no catalogue — which makes it the right tool whenever the amount is decided at request time: account credits, usage top-ups, consulting fees, one-off bills. Every invoice gets a per-store sequential number, its own hosted payment page, and an arbitrary metadata object echoed back in every webhook for it. Amounts, timestamps and ids follow the conventions that hold across the API.

Create an invoice

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

Request body

Field	Required	What it is for
`items`	see note	Up to 100 line items. See the item shape below
`templateId`	no	UUID of a dashboard-created invoice template. Supplies defaults for `items`, `memo` and expiry
`currency`	no	`usd` (default) or `eur`
`customerName`	no	Shown on the hosted page as who the invoice is billed to
`customerEmail`	no	Stored and echoed in webhooks; not shown on the public page. Required by the send endpoint, and the receipt goes here once paid
`memo`	no	Free-text note shown on the hosted page
`metadata`	no	Arbitrary JSON echoed back verbatim in every `invoice.` webhook. Use this to correlate with your own records*
`successUrl`	no	Where the Continue button on the paid page points
`cancelUrl`	no	The return link on the dead-end states — expired, voided, partial
`expiresIn`	no	Minutes the invoice stays payable. Defaults to the template’s expiry, or 1440 (24 hours)

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

items and templateId are jointly required — supply at least one. A body with neither fails schema validation and comes back as the generic { "error": "Invalid request data" }. When both are present, items replaces the template’s items wholesale rather than merging with them. The same wholesale-replacement rule applies to memo and the expiry.

Each entry in items carries a name, an optional description, a quantity and a unitAmount — a fiat decimal string like "1" or "9.99", never a number. The invoice total is Σ (unitAmount × quantity), and must come out greater than zero.

The `Idempotency-Key` header

Identical semantics to orders: optional, 1 to 255 characters, unique per store. A retried create with a key this store has used before returns the original invoice instead of minting a second one, whatever the body says. Keys never expire. See Idempotency.

Example

curl -X POST https://api.taberna.io/v1/invoices \
  -H 'Authorization: Bearer tbrn_live_…' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: purchase_8213' \
  -d '{
    "items": [{ "name": "124 credits", "quantity": 1, "unitAmount": "124" }],
    "customerEmail": "buyer@example.com",
    "customerName": "Ada Lovelace",
    "expiresIn": 60,
    "metadata": { "userId": "u_123", "credits": 124, "purchaseId": "p_8213" },
    "successUrl": "https://yourapp.com/topup/success",
    "cancelUrl": "https://yourapp.com/topup"
  }'

const res = await fetch('https://api.taberna.io/v1/invoices', {
	method: 'POST',
	headers: {
		Authorization: `Bearer ${process.env.TABERNA_API_KEY}`,
		'Content-Type': 'application/json',
		'Idempotency-Key': purchaseId,
	},
	body: JSON.stringify({
		items: [{ name: `${credits} credits`, quantity: 1, unitAmount: String(credits) }],
		customerEmail: user.email,
		expiresIn: 60,
		metadata: { userId: user.id, credits, purchaseId },
		successUrl: 'https://yourapp.com/topup/success',
		cancelUrl: 'https://yourapp.com/topup',
	}),
});
if (!res.ok) throw new Error((await res.json()).error);
const invoice = await res.json();
// Send the customer to invoice.url

res = requests.post(
	"https://api.taberna.io/v1/invoices",
	headers={
		"Authorization": f"Bearer {api_key}",
		"Content-Type": "application/json",
		"Idempotency-Key": purchase_id,
	},
	json={
		"items": [{"name": f"{credits} credits", "quantity": 1, "unitAmount": str(credits)}],
		"customerEmail": user.email,
		"expiresIn": 60,
		"metadata": {"userId": user.id, "credits": credits, "purchaseId": purchase_id},
		"successUrl": "https://yourapp.com/topup/success",
		"cancelUrl": "https://yourapp.com/topup",
	},
)
res.raise_for_status()
invoice = res.json()

201 Created

{
  "id": "CcvnBwRQaKY1rXSMLrbYe",
  "number": 42,
  "status": "open",
  "url": "https://taberna.io/invoice/CcvnBwRQaKY1rXSMLrbYe",
  "items": [
    {
      "name": "124 credits",
      "description": null,
      "quantity": 1,
      "unitAmount": "124",
      "amount": "124"
    }
  ],
  "totalAmount": "124",
  "currency": "usd",
  "customerName": "Ada Lovelace",
  "customerEmail": "buyer@example.com",
  "memo": null,
  "metadata": { "userId": "u_123", "credits": 124, "purchaseId": "p_8213" },
  "successUrl": "https://yourapp.com/topup/success",
  "cancelUrl": "https://yourapp.com/topup",
  "createdVia": "api",
  "expiresAt": "2026-07-09T13:00:00.000Z",
  "paidAt": null,
  "voidedAt": null,
  "createdAt": "2026-07-09T12:00:00.000Z",
  "email": {
    "sendCount": 0,
    "sendsRemaining": 3,
    "maxSends": 3,
    "lastSentAt": null,
    "cooldownUntil": null,
    "canSend": true,
    "blockedReason": null
  }
}

Redirect the customer to url. The hosted invoice page shows the line items, the total, your store branding, and the same pick-a-token → locked-quote payment flow as the order checkout.

createdVia is api for invoices your server created and dashboard for ones a human issued. The email object is the live send allowance — see Emailing an invoice.

Errors

All 400 with a { "error": … } body. Anything the request schema rejects never reaches the invoice logic — the validator answers first, always with the generic { "error": "Invalid request data" }. The same item-count and expiry bounds are enforced on templates when they are authored, so resolving items or the expiry from a template cannot smuggle a violation past this either. The messages below are the ones the invoice logic itself produces, once the body’s shape is already known to be valid.

Message	Cause
`Invoice total must be greater than zero`	The computed total is zero — every line is `"0"`
`Template not found`	Unknown `templateId`, or one from another store
`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

Retrieve an invoice

GET /v1/invoices/{id} — requires invoices:read. {id} is the invoice’s short id. Returns the same shape as the create response plus a transactions array: the on-chain transfers that paid it, across every payment attempt.

200 OK

{
  "id": "CcvnBwRQaKY1rXSMLrbYe",
  "number": 42,
  "status": "paid",
  "totalAmount": "124",
  "currency": "usd",
  "paidAt": "2026-07-09T12:15:04.000Z",
  "transactions": [
    {
      "blockchain": "solana",
      "txHash": "5Nx…",
      "fromAddress": "9xQ…",
      "amount": "124000000",
      "blockNumber": "298471223",
      "blockTime": "2026-07-09T12:15:02.000Z"
    }
  ]
}

A well-formed id that does not resolve — undecodable, unknown, or an invoice belonging to another store — answers 404 with { "error": "Invoice not found" }. A malformed id is a 400; see Errors.

List invoices

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

Query parameter	Type	Notes
`page`	integer	Defaults to `1`
`limit`	integer	1 to 100, defaults to `20`
`status`	enum	`open`, `paid`, `partial`, `expired`, `voided`

200 OK

{
  "data": [ /* invoices */ ],
  "pagination": { "page": 1, "limit": 20, "total": 91, "totalPages": 5 }
}

Void an invoice

POST /v1/invoices/{id}/void — requires invoices:write. Marks an open invoice as voided so it can no longer be paid, and fires invoice.voided. Returns 200 with the invoice in its new state.

What a void does to the invoice’s payment attempts

A live attempt — processing, quote not yet lapsed — refuses the call outright with Invoice has a payment in progress — try again after it expires. A buyer mid-payment does not get the invoice pulled out from under them. Past that guard, the void retires every still-watchable attempt first. This is the part worth understanding: the payment indexers select attempts on status alone, so an attempt whose quote window has already lapsed but which no indexer tick has reaped yet is still being watched and its deposit address is still payable. Voiding around such an attempt would leave a live address collecting funds for an invoice that can never be paid, so they are retired as part of the call. If funds had already landed on one of those attempts, retiring it makes the invoice partial — terminal, and resolved manually by you — rather than voided. The call then fails with Only open invoices can be voided, because by the time the void would apply the invoice is no longer open. Re-read the invoice to see the partial status.

Status	Message	Cause
`400`	`Invalid request data`	`{id}` is not a well-formed short id
`404`	`Invoice not found`	Well-formed id that does not decode
`400`	`Invoice not found`	The id decodes but there is no such invoice for this key’s store
`400`	`Only open invoices can be voided`	Already `paid`, `partial`, `expired` or `voided` — including an invoice this very call just turned `partial`
`400`	`Invoice has a payment in progress — try again after it expires`	A live attempt blocks the void, or a fully-funded one is still settling

Note the status quirk in the table: on this endpoint only, a well-formed id with no matching invoice is reported as 400, not 404 — 404 is reserved for an id that passes the short-id format check but does not decode. Do not branch on the status here; branch on the message. See the two ambiguous endpoints.

Emailing an invoice

POST /v1/invoices/{id}/send mails the invoice to its own stored customerEmail. It is rate-limited at three levels and it is the one endpoint whose error body differs from the rest of the API, so it has its own page: Emailing an invoice. Every invoice payload also carries a live email object — sendCount, sendsRemaining, maxSends, lastSentAt, cooldownUntil, canSend, blockedReason — so you can read the allowance without attempting a send.

Invoice templates

GET /v1/invoice-templates — requires invoices:read. Templates are reusable presets — default items, memo and expiry — authored in the dashboard only. This read exists so your server can discover template ids instead of hard-coding them. The response is the store’s templates, newest first, unpaginated (the set is small and merchant-curated).

200 OK

[
  {
    "id": "0197f8a0-4444-7ddd-8fff-6a8b0c2d4e57",
    "name": "Monthly retainer",
    "memo": "Payable on receipt.",
    "expiresInMinutes": 10080,
    "items": [
      {
        "name": "Retainer — standard",
        "description": null,
        "quantity": 1,
        "unitAmount": "1500"
      }
    ],
    "createdAt": "2026-06-02T08:00:00.000Z"
  }
]

Pass a row’s id as templateId on POST /v1/invoices. Remember that anything you send explicitly replaces the corresponding template default wholesale.

Statuses

Status	Meaning
`open`	Payable. Buyers can start and retry payment attempts. Initial state.
`paid`	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`	`expiresAt` passed with nothing received. Terminal.
`voided`	Cancelled before payment, by you through the API or by a human in the dashboard. Terminal.

See Payment lifecycle for what happens underneath, and Webhooks for the five invoice.* events.

Get started

Charging a customer

Getting paid

Reference

Create an invoice

Request body

The `Idempotency-Key` header

Example

Errors

Retrieve an invoice

List invoices

Void an invoice

What a void does to the invoice’s payment attempts

Emailing an invoice

Invoice templates

Statuses

​Create an invoice

​Request body

​The Idempotency-Key header

​Example

​Errors

​Retrieve an invoice

​List invoices

​Void an invoice

​What a void does to the invoice’s payment attempts

​Emailing an invoice

​Invoice templates

​Statuses

Create an invoice

Request body

The `Idempotency-Key` header

Example

Errors

Retrieve an invoice

List invoices

Void an invoice

What a void does to the invoice’s payment attempts

Emailing an invoice

Invoice templates

Statuses