# Invoices

Create, book and send invoices. Credit notes and offers are created in Numina and can be read here.

## Endpoints

- [List invoices](https://developers.numina.app/api/invoices/list-invoices.md): `GET /v1/invoices`
- [Create invoice](https://developers.numina.app/api/invoices/create-invoice.md): `POST /v1/invoices`
- [Get invoice](https://developers.numina.app/api/invoices/get-invoice.md): `GET /v1/invoices/{id}`
- [Delete draft invoice](https://developers.numina.app/api/invoices/delete-draft-invoice.md): `DELETE /v1/invoices/{id}`
- [Download invoice PDF](https://developers.numina.app/api/invoices/download-invoice-pdf.md): `GET /v1/invoices/{id}/pdf`
- [Book draft invoice](https://developers.numina.app/api/invoices/book-draft-invoice.md): `POST /v1/invoices/{id}/book`
- [Credit invoice](https://developers.numina.app/api/invoices/credit-invoice.md): `POST /v1/invoices/{id}/credit-notes`
- [Send invoice by email](https://developers.numina.app/api/invoices/send-invoice-by-email.md): `POST /v1/invoices/{id}/send`

## The invoice object

- `id` (string (uuid), required): Invoice ID
- `invoice_number` (integer, required, nullable): Invoice number (assigned when booked)
- `type` (string, required): Invoice type. Create a credit note with POST /v1/invoices/{id}/credit-notes; offers are created in Numina. One of: `invoice`, `creditNote`, `offer`.
- `credited_invoice_id` (string (uuid), required, nullable): On a credit note, the invoice it credits
- `status` (string, required): `draft`: not booked. `sent`: booked, whether or not it was delivered (see `delivery_status`). `closed`: fully settled. `paid`: settled, only on invoices migrated from Billy. `cancelled`: a booked credit note, which does not mean it was voided; a credit note can also show `closed` when its balance is zero. An offer is `draft`, `sent`, `accepted` or `declined`. To find settled invoices, use `closed` and `paid`, or `outstanding_balance`. One of: `draft`, `sent`, `closed`, `paid`, `cancelled`, `accepted`, `declined`.
- `issue_date` (string, required): Issue date
- `due_date` (string, required, nullable): Payment due date
- `contact_id` (string (uuid), required, nullable): Contact ID
- `contact_name` (string, required, nullable): Contact name (snapshot at invoice creation)
- `currency` (string, required, nullable): Currency code
- `subtotal` (number, required): Subtotal (excl. VAT)
- `vat` (number, required): VAT amount
- `vat_rate` (number, required, nullable): VAT rate percentage; null when the invoice contains mixed VAT treatments
- `total` (number, required): Total amount (incl. VAT)
- `has_mixed_vat` (boolean, required)
- `outstanding_balance` (number, required, nullable): Outstanding balance in DKK (not invoice currency; 0 when settled). Only populated for booked invoices.
- `outstanding_balance_currency` (string, required): One of: `DKK`.
- `currency_rate` (number, required): Invoice currency to DKK: amount × rate = DKK. On a draft, the rate you sent; once booked, the rate Numina used (see `currency_rate` on POST /v1/invoices).
- `delivery_status` (string, required): Channel handoff state. 'sent' means provider acceptance, not confirmed delivery to the recipient. One of: `sent`, `failed`, `pending`, `not_requested`.
- `email_delivery_status` (string, required, nullable)
- `email_sent_at` (string, required, nullable)
- `e_invoice_sent_at` (string, required, nullable)
- `is_overdue` (boolean, required): Whether the invoice is past its due date and still owed (see `payment_state`)
- `payment_state` (string, required, nullable): Whether a booked invoice is owed. 'covered_by_unmatched_payments': the customer's balance is covered by payments booked without an invoice match, so the invoice is not owed although `outstanding_balance` stays positive; the customer's balance is the truth. 'exchange_difference': the remainder is a currency difference, not unpaid money. Null for drafts, offers, credit notes and cancelled invoices. One of: `open`, `paid`, `covered_by_unmatched_payments`, `exchange_difference`, `null`.
- `unmatched_payments_note` (string, optional): Set only when payment_state is 'covered_by_unmatched_payments'.
- `items` (array of objects, required): Invoice line items
  - `unit` (string, required): Unit: unit, hour, day, kilometer, week, or month
  - `vat_account_id` (string, required, nullable)
  - `vat_code` (string, required, nullable): VAT code on this line, null for no VAT
  - `sales_account_number` (integer, required, nullable): Sales account this line is booked to
  - `vat_rate` (number, required): VAT percentage for this line
  - `id` (string, required): Line item ID
  - `description` (string, required): Line item description
  - `quantity` (number, required): Quantity
  - `unit_price` (number, required): Unit price (excl. VAT)
- `memo` (string, required, nullable): Note displayed on the invoice
- `payment_details` (object, required, nullable): The bank account the invoice asks the customer to pay into, as copied when it was created. Null when it names none; such an invoice cannot be booked.
  - `bank_name` (string, required, nullable)
  - `scheme` (string, required, nullable): What `clearing_code` and `account_number` are: a Danish registration number, a UK sort code or a US ACH routing number. Null when there is only an IBAN. One of: `dk-registration-number`, `gb-sort-code`, `ach`, `null`.
  - `clearing_code` (string, required, nullable): Registration number, sort code or ACH routing number
  - `account_number` (string, required, nullable)
  - `iban` (string, required, nullable)
  - `swift_bic` (string, required, nullable)
- `created_at` (string, required, nullable): Creation timestamp (ISO 8601, UTC)

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "invoice_number": 1001,
  "type": "invoice",
  "credited_invoice_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "sent",
  "issue_date": "2026-01-15",
  "due_date": "2026-02-15",
  "contact_id": "550e8400-e29b-41d4-a716-446655440001",
  "contact_name": "Acme ApS",
  "currency": "DKK",
  "subtotal": 10000,
  "vat": 2500,
  "vat_rate": 25,
  "total": 12500,
  "has_mixed_vat": false,
  "outstanding_balance": 12500,
  "outstanding_balance_currency": "DKK",
  "currency_rate": 0,
  "delivery_status": "sent",
  "email_delivery_status": "string",
  "email_sent_at": "string",
  "e_invoice_sent_at": "string",
  "is_overdue": false,
  "payment_state": "open",
  "unmatched_payments_note": "string",
  "items": [
    {
      "unit": "string",
      "vat_account_id": "string",
      "vat_code": "string",
      "sales_account_number": 0,
      "vat_rate": 0,
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "description": "Consulting services",
      "quantity": 10,
      "unit_price": 1000
    }
  ],
  "memo": "Project Q1 delivery",
  "payment_details": {
    "bank_name": "Danske Bank",
    "scheme": "dk-registration-number",
    "clearing_code": "3409",
    "account_number": "0012345678",
    "iban": "DK5030000012345678",
    "swift_bic": "DABADKKK"
  },
  "created_at": "2026-01-15T10:30:00Z"
}
```