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. The shared line model, list/get/PDF reads, and send channels are in Billing documents; this page covers what is specific to invoices.

Lifecycle

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). 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.

Code
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).

Code
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 covers endpoint setup, the signed-envelope format, and the full topic list.