Invoices

Update an invoice

Partial update: fields omitted from the body keep their stored values (invoice number, dates, client, sender, payment, currency, attachments, ...). Only invoices in draft status can be fully updated. Changing the status field moves the invoice through its lifecycle; status values are case-insensitive. The currency and the rate of an issued or paid invoice, credit note or offer are locked: a different currency or exchangeRate answers 400 CURRENCY_LOCKED (cancel and re-issue instead; before 3.14.0 a different exchangeRate was silently ignored). An unsupported currency answers 400 UNSUPPORTED_CURRENCY (with currency). A foreign-currency invoice in a fiscal year with a booked FX revaluation refuses a change of its total or date with 400 FX_REVALUATION_LIVE (re-run the revaluation after a cancel and re-issue instead).

put/invoices/{id}

Request

  • Base URL: https://api.lumabill.ch/v1
  • URL: https://api.lumabill.ch/v1/invoices/{id}
  • 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

Updated invoice

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.