> ## Documentation Index
> Fetch the complete documentation index at: https://developers.ebioro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoicing

> Create invoices with line items and tax, paid through a payment link

## Overview

An invoice is a bill with line items, an optional tax rate, and a customer. Creating one automatically creates a payment to settle it — share that payment's link with your customer and the invoice is marked paid the moment the payment completes.

```bash theme={null}
POST /invoices
{
  "currency": "USD",
  "line_items": [
    { "description": "Consulting — June", "quantity": 2, "unit_price": 10000 }
  ],
  "tax_percentage": 21,
  "customer": {
    "customer_type": "business",
    "company_name": "Example Co B.V.",
    "email": "billing@example.com"
  },
  "notes": "Thanks for your business."
}
```

```json theme={null}
{
  "id": "c9310d0f-6338-4780-b8d2-6a125e258a4a",
  "invoice_number": "INV-2026-4",
  "status": "sent",
  "subtotal": 20000,
  "tax_percentage": 21,
  "tax_total": 4200,
  "total": 24200,
  "payment_id": "pt_EL1yKOzKdv"
}
```

Fetch the linked payment (`GET /payments/{id}`, using the `payment_id` from the invoice response) to get the shareable `shortUrl` for the customer. See [Payment Links](/concepts/payment-links).

## Amounts and tax

* All money fields are integers in the **smallest unit of the currency** (cents): `unit_price`, `subtotal`, `tax_total`, `total`.
* `subtotal` = Σ `quantity × unit_price`.
* A single **`tax_percentage`** (0–100) applies to the whole subtotal: `tax_total = subtotal × tax_percentage / 100`, and `total = subtotal + tax_total`. Per-line tax rates are not supported.
* `currency` is the pricing currency; settlement happens in USDC like every Ebioro payment.

## Invoice statuses

| Status    | Meaning                                                                               |
| --------- | ------------------------------------------------------------------------------------- |
| `draft`   | Created but its payment link could not be generated — retry by creating a new invoice |
| `sent`    | Created, payment link active, awaiting payment                                        |
| `paid`    | The linked payment completed                                                          |
| `overdue` | `due_at` passed without payment                                                       |
| `voided`  | Cancelled via `POST /invoices/{id}/cancel`                                            |

Cancelling voids the invoice and expires its payment link. A paid invoice cannot be cancelled — refund the linked payment instead.

## Customers

Attach a customer either by reference or inline:

* `customer_id` — bill an existing customer again.
* `customer` — create one inline: `customer_type` (`individual` | `business`), `name`, `company_name`, `email`, `vat_number`, `address`.

The customer appears on the invoice response and can be reused via its `id` on later invoices.

## Invoice numbering

Numbers are minted **gaplessly** per merchant: `prefix + sequence`. Configure the prefix via the [numbering settings](/api-reference/invoices/update-invoice-settings):

```bash theme={null}
POST /invoices/settings
{ "invoice_prefix": "INV-{year}-", "next_number": 100 }
```

* The `{year}` token resolves to the current year at creation time (`INV-2026-100`). The sequence is continuous — `{year}` stamps the year but does **not** reset the counter each January.
* `next_number` can only move forward, so an already-issued number is never reissued.
* You can also pass an explicit `invoice_number` when creating an invoice; the gapless counter is skipped for that invoice.

`GET /invoices/settings` returns the current prefix, the next number, and a resolved preview (`"INV-2026-5"`).