# Invoices

An invoice is a booked accounting document: sending allocates its number and
posts it to the books. Reads require the `invoices-read` scope and writes
`invoices-write` — one scope pair covers invoices and
[credit notes](/guides/billing-documents/credit-notes). The shared line model,
list/get/PDF reads, and send channels are in
[Billing documents](/guides/billing-documents/overview); this page covers what is
specific to invoices.

## Lifecycle

| Phase | What happens |
|---|---|
| **Create** | `POST /v1/invoices` returns a draft. The draft has no number yet (`number` is `null`). |
| **Send** | `POST /v1/invoices/{id}/send` books the document, allocates the invoice number, and delivers it over the chosen channel. |
| **Download** | `GET /v1/invoices/{id}/pdf` streams the rendered PDF at any point. Before send, pass `?draft=true` for a watermarked preview. |
| **Track** | `GET /v1/invoices/{id}/delivery-status` returns the aggregate send summary plus a per-attempt log. |

## Create an invoice

`POST /v1/invoices` returns the draft as `PublicInvoice`. `customerId` is
required, and the document must carry at least one product line (see
[Document lines](/guides/billing-documents/overview#document-lines)). A billable
line sends a `priceId` and a `quantity`; you may override `unitPrice` (it defaults
to the price's current amount in the document currency). `totalPrice`
(= `quantity * unitPrice`) and VAT (`vatRate` / `vatAmount`, derived from the
product and the customer's VAT zone) are computed server-side — do not send them.
The invoice `number` stays `null` until the document is sent.

```bash
curl -X POST 'https://api.ledgerbee.com/api/v1/invoices' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "customerId": "0197a943-2325-7829-b835-b6c71a293065",
    "date": "2026-01-15",
    "currency": "DKK",
    "paymentTerms": 30,
    "lines": [
      {
        "priceId": "0197a943-2325-7829-b835-b6c71a293099",
        "quantity": 2
      }
    ]
  }'
```

## Status values

Invoice `status` is one of `draft`, `scheduled`, `sending`, `sent`, `paid`,
`partially_paid`, `cancelled`, `uncollectible`, `credited`.

## Send

`POST /v1/invoices/{id}/send` books the document, allocates its number, and
delivers it over the `deliveryType` channel (`Email`, `Sproom`, or `Manual` — see
[Sending](/guides/billing-documents/overview#sending)).

```bash
curl -X POST 'https://api.ledgerbee.com/api/v1/invoices/0197a943-2325-7829-b835-b6c71a293066/send' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "deliveryType": "Email", "overrideEmail": "billing@acme.example" }'
```

`overrideEmail` and `overrideEanNumber` apply to the single send unless
`updateCustomerRecord` is `true`, which persists them onto the customer record.
`documentTemplateId` overrides the PDF template for this send. The response
carries `success`, `deliveryType`, and `sproomDocumentId` (the id of the document
created on the Sproom network, for a `Sproom` send).

## Delivery status

`GET /v1/invoices/{id}/delivery-status` returns a `summary` (send count, last
channel, last recipient, last send time) and a chronological `entries` log of
every attempt with its `status` (`success` / `failed`), `deliveryType`, recipient,
`sentAt`, and `errorCode` on failure.

A `Sproom` send rejected by the network does not fail the request synchronously;
it records a `failed` delivery entry with its `errorCode`. Poll `delivery-status`
after a `Sproom` send to confirm the outcome.

## Webhook events

Subscription-driven invoices (those the billing engine sends) emit the
`billing.invoice_sent` topic. Invoices you create and send directly over this API
are booked the same way but are not subscription events.
[Webhooks](/guides/webhooks) covers endpoint setup, the signed-envelope format,
and the full topic list.