Create an invoice

curl --request POST \
  --url https://api.taberna.io/v1/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "name": "Design retainer — July",
      "quantity": 1,
      "unitAmount": "49.99",
      "description": "40 hours at the agreed rate."
    }
  ],
  "templateId": "3f1a9c2e-7b04-4d8e-9a6f-2c5b1e0d7a83",
  "currency": "usd",
  "customerName": "Acme GmbH",
  "customerEmail": "billing@acme.example",
  "memo": "Net 14. Thanks!",
  "metadata": {
    "ledgerRef": "INV-2026-1042"
  },
  "successUrl": "https://example.com/thanks",
  "cancelUrl": "https://example.com/billing",
  "expiresIn": 1440
}
'

import requests

url = "https://api.taberna.io/v1/invoices"

payload = {
    "items": [
        {
            "name": "Design retainer — July",
            "quantity": 1,
            "unitAmount": "49.99",
            "description": "40 hours at the agreed rate."
        }
    ],
    "templateId": "3f1a9c2e-7b04-4d8e-9a6f-2c5b1e0d7a83",
    "currency": "usd",
    "customerName": "Acme GmbH",
    "customerEmail": "billing@acme.example",
    "memo": "Net 14. Thanks!",
    "metadata": { "ledgerRef": "INV-2026-1042" },
    "successUrl": "https://example.com/thanks",
    "cancelUrl": "https://example.com/billing",
    "expiresIn": 1440
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    items: [
      {
        name: 'Design retainer — July',
        quantity: 1,
        unitAmount: '49.99',
        description: '40 hours at the agreed rate.'
      }
    ],
    templateId: '3f1a9c2e-7b04-4d8e-9a6f-2c5b1e0d7a83',
    currency: 'usd',
    customerName: 'Acme GmbH',
    customerEmail: 'billing@acme.example',
    memo: 'Net 14. Thanks!',
    metadata: {ledgerRef: 'INV-2026-1042'},
    successUrl: 'https://example.com/thanks',
    cancelUrl: 'https://example.com/billing',
    expiresIn: 1440
  })
};

fetch('https://api.taberna.io/v1/invoices', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.taberna.io/v1/invoices",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'items' => [
        [
                'name' => 'Design retainer — July',
                'quantity' => 1,
                'unitAmount' => '49.99',
                'description' => '40 hours at the agreed rate.'
        ]
    ],
    'templateId' => '3f1a9c2e-7b04-4d8e-9a6f-2c5b1e0d7a83',
    'currency' => 'usd',
    'customerName' => 'Acme GmbH',
    'customerEmail' => 'billing@acme.example',
    'memo' => 'Net 14. Thanks!',
    'metadata' => [
        'ledgerRef' => 'INV-2026-1042'
    ],
    'successUrl' => 'https://example.com/thanks',
    'cancelUrl' => 'https://example.com/billing',
    'expiresIn' => 1440
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.taberna.io/v1/invoices"

	payload := strings.NewReader("{\n  \"items\": [\n    {\n      \"name\": \"Design retainer — July\",\n      \"quantity\": 1,\n      \"unitAmount\": \"49.99\",\n      \"description\": \"40 hours at the agreed rate.\"\n    }\n  ],\n  \"templateId\": \"3f1a9c2e-7b04-4d8e-9a6f-2c5b1e0d7a83\",\n  \"currency\": \"usd\",\n  \"customerName\": \"Acme GmbH\",\n  \"customerEmail\": \"billing@acme.example\",\n  \"memo\": \"Net 14. Thanks!\",\n  \"metadata\": {\n    \"ledgerRef\": \"INV-2026-1042\"\n  },\n  \"successUrl\": \"https://example.com/thanks\",\n  \"cancelUrl\": \"https://example.com/billing\",\n  \"expiresIn\": 1440\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.taberna.io/v1/invoices")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"items\": [\n    {\n      \"name\": \"Design retainer — July\",\n      \"quantity\": 1,\n      \"unitAmount\": \"49.99\",\n      \"description\": \"40 hours at the agreed rate.\"\n    }\n  ],\n  \"templateId\": \"3f1a9c2e-7b04-4d8e-9a6f-2c5b1e0d7a83\",\n  \"currency\": \"usd\",\n  \"customerName\": \"Acme GmbH\",\n  \"customerEmail\": \"billing@acme.example\",\n  \"memo\": \"Net 14. Thanks!\",\n  \"metadata\": {\n    \"ledgerRef\": \"INV-2026-1042\"\n  },\n  \"successUrl\": \"https://example.com/thanks\",\n  \"cancelUrl\": \"https://example.com/billing\",\n  \"expiresIn\": 1440\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.taberna.io/v1/invoices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"items\": [\n    {\n      \"name\": \"Design retainer — July\",\n      \"quantity\": 1,\n      \"unitAmount\": \"49.99\",\n      \"description\": \"40 hours at the agreed rate.\"\n    }\n  ],\n  \"templateId\": \"3f1a9c2e-7b04-4d8e-9a6f-2c5b1e0d7a83\",\n  \"currency\": \"usd\",\n  \"customerName\": \"Acme GmbH\",\n  \"customerEmail\": \"billing@acme.example\",\n  \"memo\": \"Net 14. Thanks!\",\n  \"metadata\": {\n    \"ledgerRef\": \"INV-2026-1042\"\n  },\n  \"successUrl\": \"https://example.com/thanks\",\n  \"cancelUrl\": \"https://example.com/billing\",\n  \"expiresIn\": 1440\n}"

response = http.request(request)
puts response.read_body

{
  "id": "7Kq2mVn8pRt3XwYz5Bd4L",
  "number": 1042,
  "status": "open",
  "url": "https://taberna.io/invoice/7Kq2mVn8pRt3XwYz5Bd4L",
  "items": [
    {
      "name": "Design retainer — July",
      "description": "<string>",
      "quantity": 1,
      "unitAmount": "49.99",
      "amount": "49.99"
    }
  ],
  "totalAmount": "49.99",
  "currency": "usd",
  "customerName": "Acme GmbH",
  "customerEmail": "billing@acme.example",
  "memo": "Net 14. Thanks!",
  "metadata": {
    "ledgerRef": "INV-2026-1042"
  },
  "successUrl": "https://example.com/thanks",
  "cancelUrl": "https://example.com/billing",
  "createdVia": "api",
  "expiresAt": "2026-07-29T14:30:00.000Z",
  "paidAt": "2026-07-29T14:30:00.000Z",
  "voidedAt": "2026-07-29T14:30:00.000Z",
  "createdAt": "2026-07-29T14:30:00.000Z",
  "email": {
    "sendCount": 1,
    "sendsRemaining": 2,
    "maxSends": 3,
    "lastSentAt": "2026-07-29T14:30:00.000Z",
    "cooldownUntil": "2026-07-29T14:30:00.000Z",
    "canSend": true,
    "blockedReason": "Cooldown in effect"
  }
}

{
  "error": "Order not found"
}

{
  "error": "Order not found"
}

{
  "error": "Order not found"
}

POST

invoices

Create an invoice

curl --request POST \
  --url https://api.taberna.io/v1/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "name": "Design retainer — July",
      "quantity": 1,
      "unitAmount": "49.99",
      "description": "40 hours at the agreed rate."
    }
  ],
  "templateId": "3f1a9c2e-7b04-4d8e-9a6f-2c5b1e0d7a83",
  "currency": "usd",
  "customerName": "Acme GmbH",
  "customerEmail": "billing@acme.example",
  "memo": "Net 14. Thanks!",
  "metadata": {
    "ledgerRef": "INV-2026-1042"
  },
  "successUrl": "https://example.com/thanks",
  "cancelUrl": "https://example.com/billing",
  "expiresIn": 1440
}
'

import requests

url = "https://api.taberna.io/v1/invoices"

payload = {
    "items": [
        {
            "name": "Design retainer — July",
            "quantity": 1,
            "unitAmount": "49.99",
            "description": "40 hours at the agreed rate."
        }
    ],
    "templateId": "3f1a9c2e-7b04-4d8e-9a6f-2c5b1e0d7a83",
    "currency": "usd",
    "customerName": "Acme GmbH",
    "customerEmail": "billing@acme.example",
    "memo": "Net 14. Thanks!",
    "metadata": { "ledgerRef": "INV-2026-1042" },
    "successUrl": "https://example.com/thanks",
    "cancelUrl": "https://example.com/billing",
    "expiresIn": 1440
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    items: [
      {
        name: 'Design retainer — July',
        quantity: 1,
        unitAmount: '49.99',
        description: '40 hours at the agreed rate.'
      }
    ],
    templateId: '3f1a9c2e-7b04-4d8e-9a6f-2c5b1e0d7a83',
    currency: 'usd',
    customerName: 'Acme GmbH',
    customerEmail: 'billing@acme.example',
    memo: 'Net 14. Thanks!',
    metadata: {ledgerRef: 'INV-2026-1042'},
    successUrl: 'https://example.com/thanks',
    cancelUrl: 'https://example.com/billing',
    expiresIn: 1440
  })
};

fetch('https://api.taberna.io/v1/invoices', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.taberna.io/v1/invoices",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'items' => [
        [
                'name' => 'Design retainer — July',
                'quantity' => 1,
                'unitAmount' => '49.99',
                'description' => '40 hours at the agreed rate.'
        ]
    ],
    'templateId' => '3f1a9c2e-7b04-4d8e-9a6f-2c5b1e0d7a83',
    'currency' => 'usd',
    'customerName' => 'Acme GmbH',
    'customerEmail' => 'billing@acme.example',
    'memo' => 'Net 14. Thanks!',
    'metadata' => [
        'ledgerRef' => 'INV-2026-1042'
    ],
    'successUrl' => 'https://example.com/thanks',
    'cancelUrl' => 'https://example.com/billing',
    'expiresIn' => 1440
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.taberna.io/v1/invoices"

	payload := strings.NewReader("{\n  \"items\": [\n    {\n      \"name\": \"Design retainer — July\",\n      \"quantity\": 1,\n      \"unitAmount\": \"49.99\",\n      \"description\": \"40 hours at the agreed rate.\"\n    }\n  ],\n  \"templateId\": \"3f1a9c2e-7b04-4d8e-9a6f-2c5b1e0d7a83\",\n  \"currency\": \"usd\",\n  \"customerName\": \"Acme GmbH\",\n  \"customerEmail\": \"billing@acme.example\",\n  \"memo\": \"Net 14. Thanks!\",\n  \"metadata\": {\n    \"ledgerRef\": \"INV-2026-1042\"\n  },\n  \"successUrl\": \"https://example.com/thanks\",\n  \"cancelUrl\": \"https://example.com/billing\",\n  \"expiresIn\": 1440\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.taberna.io/v1/invoices")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"items\": [\n    {\n      \"name\": \"Design retainer — July\",\n      \"quantity\": 1,\n      \"unitAmount\": \"49.99\",\n      \"description\": \"40 hours at the agreed rate.\"\n    }\n  ],\n  \"templateId\": \"3f1a9c2e-7b04-4d8e-9a6f-2c5b1e0d7a83\",\n  \"currency\": \"usd\",\n  \"customerName\": \"Acme GmbH\",\n  \"customerEmail\": \"billing@acme.example\",\n  \"memo\": \"Net 14. Thanks!\",\n  \"metadata\": {\n    \"ledgerRef\": \"INV-2026-1042\"\n  },\n  \"successUrl\": \"https://example.com/thanks\",\n  \"cancelUrl\": \"https://example.com/billing\",\n  \"expiresIn\": 1440\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.taberna.io/v1/invoices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"items\": [\n    {\n      \"name\": \"Design retainer — July\",\n      \"quantity\": 1,\n      \"unitAmount\": \"49.99\",\n      \"description\": \"40 hours at the agreed rate.\"\n    }\n  ],\n  \"templateId\": \"3f1a9c2e-7b04-4d8e-9a6f-2c5b1e0d7a83\",\n  \"currency\": \"usd\",\n  \"customerName\": \"Acme GmbH\",\n  \"customerEmail\": \"billing@acme.example\",\n  \"memo\": \"Net 14. Thanks!\",\n  \"metadata\": {\n    \"ledgerRef\": \"INV-2026-1042\"\n  },\n  \"successUrl\": \"https://example.com/thanks\",\n  \"cancelUrl\": \"https://example.com/billing\",\n  \"expiresIn\": 1440\n}"

response = http.request(request)
puts response.read_body

{
  "id": "7Kq2mVn8pRt3XwYz5Bd4L",
  "number": 1042,
  "status": "open",
  "url": "https://taberna.io/invoice/7Kq2mVn8pRt3XwYz5Bd4L",
  "items": [
    {
      "name": "Design retainer — July",
      "description": "<string>",
      "quantity": 1,
      "unitAmount": "49.99",
      "amount": "49.99"
    }
  ],
  "totalAmount": "49.99",
  "currency": "usd",
  "customerName": "Acme GmbH",
  "customerEmail": "billing@acme.example",
  "memo": "Net 14. Thanks!",
  "metadata": {
    "ledgerRef": "INV-2026-1042"
  },
  "successUrl": "https://example.com/thanks",
  "cancelUrl": "https://example.com/billing",
  "createdVia": "api",
  "expiresAt": "2026-07-29T14:30:00.000Z",
  "paidAt": "2026-07-29T14:30:00.000Z",
  "voidedAt": "2026-07-29T14:30:00.000Z",
  "createdAt": "2026-07-29T14:30:00.000Z",
  "email": {
    "sendCount": 1,
    "sendsRemaining": 2,
    "maxSends": 3,
    "lastSentAt": "2026-07-29T14:30:00.000Z",
    "cooldownUntil": "2026-07-29T14:30:00.000Z",
    "canSend": true,
    "blockedReason": "Cooldown in effect"
  }
}

{
  "error": "Order not found"
}

{
  "error": "Order not found"
}

{
  "error": "Order not found"
}

Authorizations

Authorization

string

header

required

A store API key, sent as Authorization: Bearer <key>.

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.

Headers

Idempotency-Key

string

Optional replay guard, 1–255 characters. Retrying a create with a key already used by this store returns the original resource instead of making a second one.

Required string length: 1 - 255

Body

application/json

items

object[]

The billed lines, 1–100 of them. Required unless templateId is given; sending both replaces the template's lines wholesale rather than merging.

Required array length: 1 - 100 elements

Show child attributes

templateId

string<uuid>

A saved invoice template to build from — its items, memo and expiry are copied unless this request sets its own. Formatted as a UUID, e.g. 3f1a9c2e-7b04-4d8e-9a6f-2c5b1e0d7a83.

Example:

"3f1a9c2e-7b04-4d8e-9a6f-2c5b1e0d7a83"

currency

enum<string>

The fiat currency every amount on this resource is priced in. Crypto is quoted against it at payment time. Defaults to usd when omitted.

Available options:

usd,

eur

Example:

"usd"

customerName

string

Who the invoice is addressed to. Shown on the payment page.

Maximum string length: 255

Example:

"Acme GmbH"

customerEmail

string<email>

The address the send endpoint will email. Creating an invoice never sends anything; without this, the invoice can never be emailed at all.

Example:

"billing@acme.example"

memo

string

Free-text note shown to the customer on the payment page.

Maximum string length: 5000

Example:

"Net 14. Thanks!"

metadata

object

Arbitrary JSON to carry your own reference. Stored verbatim, returned on reads and on webhooks, and never shown to the customer.

Show child attributes

Example:

{ "ledgerRef": "INV-2026-1042" }

successUrl

string<uri>

Where the payment page sends the customer once the invoice is paid. http/https only, up to 2048 characters.

Maximum string length: 2048

Example:

"https://example.com/thanks"

cancelUrl

string<uri>

Where the payment page sends the customer if they back out. http/https only, up to 2048 characters.

Maximum string length: 2048

Example:

"https://example.com/billing"

expiresIn

integer

How long the invoice stays payable, in minutes (10–129600). Falls back to the templateId template's own expiry, and to 1440 when there is none.

Required range: 10 <= x <= 129600

Example:

1440

Response

The invoice. A replayed Idempotency-Key returns the original invoice with this same status.

An invoice as the merchant API reports it.

string

required

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

integer

required

Human-facing invoice number, counting up per store from 1. Distinct from id, which is what the API and the payment link use.

Required range: -9007199254740991 <= x <= 9007199254740991

Example:

1042

status

enum<string>

required

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.

Available options:

open,

paid,

partial,

expired,

voided

Example:

"open"

url

string

required

The hosted payment page for this invoice — what a customer opens to pay it.

Example:

"https://taberna.io/invoice/7Kq2mVn8pRt3XwYz5Bd4L"

items

object[]

required

The billed lines, in the order they were entered.

Show child attributes

totalAmount

string

required

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

enum<string>

required

The fiat currency every amount on this resource is priced in. Crypto is quoted against it at payment time.

Available options:

usd,

eur

Example:

"usd"

customerName

string | null

required

Who the invoice is addressed to, shown on the payment page. Null when unset.

Example:

"Acme GmbH"

customerEmail

string | null

required

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

string | null

required

Free-text note shown to the customer on the payment page. Null when unset.

Example:

"Net 14. Thanks!"

metadata

object | null

required

The arbitrary JSON object you attached at creation, returned untouched. Merchant-only: it never reaches the customer's payment page.

Show child attributes

Example:

{ "ledgerRef": "INV-2026-1042" }

successUrl

string | null

required

Where the payment page sends the customer once the invoice is paid. Null when none was set.

Example:

"https://example.com/thanks"

cancelUrl

string | null

required

Where the payment page sends the customer if they back out. Null when none was set.

Example:

"https://example.com/billing"

createdVia

enum<string>

required

Where the invoice came from. api — this API. dashboard — a human created it in the Taberna dashboard.

Available options:

api,

dashboard

Example:

"api"

expiresAt

string<date-time>

required

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

string<date-time> | null

required

When the invoice was settled in full. Null until it is. UTC timestamp in ISO 8601, e.g. 2026-07-29T14:30:00.000Z.

Example:

"2026-07-29T14:30:00.000Z"

voidedAt

string<date-time> | null

required

When the merchant voided the invoice. Null unless voided. UTC timestamp in ISO 8601, e.g. 2026-07-29T14:30:00.000Z.

Example:

"2026-07-29T14:30:00.000Z"

createdAt

string<date-time>

required

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"

object

required

The invoice's remaining email allowance.

Show child attributes

Orders

Invoices

Invoice Templates

Products

Store

Webhook Deliveries

Checkout

Create an invoice

Authorizations

Headers

Body

Response