# Invoices

How invoices work in Southbill, how customers pay them, and the roadmap for the invoice API.

# Invoices

Invoices in Southbill are **created in the merchant dashboard** (`/dashboard/invoices/new`). Each invoice generates a public payment link that anyone with the link can pay — no API key needed on the customer side.

> A public REST API for `create / list / send invoice` is on the roadmap. Today you can automate invoice payments through **Checkout Sessions** and use the dashboard for invoicing.

## Anatomy

| Field | Description |
|---|---|
| `number` | Auto-generated `SPK-INV-YYYY-NNNN`. |
| `currency` | ISO code — **locked to the currency of any product line-item** you add. |
| `line_items` | Free-form or imported from your **Products** catalog. Product-sourced items are locked to Southbill values (price, quantity, VAT, currency). |
| `total_amount` | Sum incl. VAT. Minimum **2.50** in invoice currency (below that, PSP + Southbill fees can't be covered). |
| `status` | `draft` → `open` → `paid` / `void` / `uncollectible`. |
| `public_token` | Random token used in the customer-facing URL. |

## Customer payment flow

1. Merchant creates the invoice and clicks **Send** — status becomes `open`, `public_token` is minted.
2. Customer opens `https://payments.southbill.com/i/{public_token}` (link is emailed automatically).
3. Opening the link starts a southbill-hosted payment for the invoice, which:
   - creates the payment against the merchant's Southbill account,
   - resolves enabled payment methods for the invoice currency (Klarna, iDEAL, Bancontact, etc. are filtered per currency),
   - applies the merchant's Southbill fees via the shared fee engine.
4. On success the invoice is marked `paid`, a receipt is emailed and a `invoice.paid` webhook is delivered to your endpoints.

## Adding products to an invoice

In the **New invoice** page, click **Add from products** → pick a product. Southbill will:

- copy `name`, `description`, `image`, `price`, `currency`, `VAT` from your catalog;
- **lock** those fields (marked *"From product · locked to Southbill values"*);
- lock the invoice currency to the product currency;
- disable recurring products (recurring billing runs through the Subscriptions API, `POST /v1/subscriptions`).

## Webhooks

Configure your endpoints in **Dashboard → Developers → Webhooks**.

| Event | When |
|---|---|
| `invoice.finalized` | Invoice moves from `draft` to `open` (send). |
| `invoice.paid` | Customer paid successfully. |
| `invoice.payment_failed` | Payment attempt failed. |
| `invoice.voided` | Merchant voided an open invoice. |

Payload includes `id`, `number`, `amount_due`, `amount_paid`, `currency`, `customer_email`, `customer_name`, `line_items[]`, `metadata`.

## Fees & minimums

All fees are calculated in EUR (see **Fees, currency & minimum amounts**). Minimum invoice total is **2.50** in the invoice currency.