Invoices

Create an invoice

post/invoices

Request

  • Base URL: https://api.lumabill.ch/v1
  • URL: https://api.lumabill.ch/v1/invoices
  • Auth: HTTP bearer

Request body

invoice_numberstring nullable

Explicit number (imports, own numbering schemes), stored as given also on a draft; 409 DUPLICATE_INVOICE_NUMBER when another document of the same type in the profile already uses it. If omitted, a draft stays unnumbered and the next number from the profile prefix + counter (e.g. IV-010) is assigned when the document is issued (status leaves draft, or it is emailed). null clears the number of a never-issued draft; an issued document keeps its number.

client_idstring uuid

UUID of an existing client. The API fetches the client data and snapshots it on the invoice. Returns 404 if not found.

status'draft' | 'sent'
issue_datestring date

Defaults to today if omitted.

due_datestring date

Defaults to issue_date + profile payment deadline days (default 30) if omitted.

currency'CHF' | 'EUR' | 'USD' | 'GBP' | 'JPY' | 'CAD' | 'AUD' | 'SEK' | 'NOK' | 'DKK' | 'HUF'

ISO 4217 code of a currency the API converts (ESTV/BAZG rates). The same list applies to every currency field of the API.

exchangeRatenumber double nullable

Foreign-currency invoice only: CHF per 1 unit of currency, stored as a manual rate (MWSTV 45 Abs. 3bis). Omit to use the ESTV/BAZG rate of the invoice date. Taken while the invoice is a draft or by the write that issues it; an issued invoice keeps its rate. Issuing a foreign-currency invoice without any rate (e.g. dated in a Monatsmittel month that has not started) is refused with 400 FX_RATE_UNAVAILABLE; when ESTV/BAZG cannot be reached and no rate is cached the write answers 400 FX_RATE_SOURCE_UNAVAILABLE (retry later, it is not a missing rate); 400 INVALID_EXCHANGE_RATE when not a positive number, 400 EXCHANGE_RATE_IMPLAUSIBLE when outside 0.5x to 2x of the ESTV/BAZG rate of the date (0.0001 to 100 without one; the body carries officialRate, min, max). null is the same as omitting it (unlike the expense and revenue update, it does not drop a stored manual rate).

notesstring nullable
payment_termsstring nullable

Example request

{
  "invoice_number": "INV-2025-0042",
  "client_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "draft",
  "issue_date": "2025-05-01",
  "due_date": "2025-05-31",
  "currency": "CHF",
  "exchangeRate": 0.9412,
  "lines": [
    {
      "description": "Web development - May 2025",
      "quantity": 8,
      "price": 150,
      "vat_rate": 8.1
    }
  ],
  "notes": "Payment within 30 days.",
  "payment_terms": "30 days net"
}

Response

Invoice created

idstring uuid required
invoice_numberstring nullable required

null while the document is an unnumbered draft. Numbers are assigned when the document is first issued (leaves draft) and never removed afterwards.

client_idstring uuid required
status'draft' | 'sent' | 'paid' | 'overdue' required
issue_datestring date required
due_datestring date required
totalnumber double required

Total invoice amount including VAT

currency'CHF' | 'EUR' | 'USD' | 'GBP' | 'JPY' | 'CAD' | 'AUD' | 'SEK' | 'NOK' | 'DKK' | 'HUF' required

ISO 4217 code of a currency the API converts (ESTV/BAZG rates). The same list applies to every currency field of the API.

notesstring nullable
payment_termsstring nullable
created_atstring date-time required

Example response

{
  "id": "a1b2c3d4-1234-5678-abcd-ef0123456789",
  "invoice_number": "INV-2025-0042",
  "client_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "sent",
  "issue_date": "2025-05-01",
  "due_date": "2025-05-31",
  "total": 1296,
  "currency": "CHF",
  "lines": [
    {
      "description": "Web development - May 2025",
      "quantity": 8,
      "price": 150,
      "vat_rate": 8.1
    }
  ],
  "notes": "Payment within 30 days. Thank you for your business.",
  "payment_terms": "30 days net",
  "created_at": "2025-04-30T08:00:00Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.