Invoice lifecycle
An invoice has three views of its state. The document status says whether it can still be edited. The submission state says how far the authority has taken it. simpleStatus folds both into one word for display. All three come back on every invoice read.
Document status
| Status | Meaning | What you can do |
|---|---|---|
draft | Being prepared; totals are computed as you edit | Edit, delete, finalise, or submit with finalise=true |
finalised | Frozen; the supplier details and totals will not change | Submit, send to the buyer, download, record payments, cancel |
cancellation_pending | A closing credit note is on its way to the authority | Wait |
cancelled | Voided | Nothing; the credit note is its record |
Two moves go backwards. Reopen (POST /i/v1/invoices/{id}/reopen) returns a finalised invoice to draft after the authority rejected it, so you can correct and resubmit. Revise (POST /i/v1/invoices/{id}/revise) returns a finalised invoice that was never reported and never paid to draft.
Only drafts can be deleted.
Submission state
Submitting creates a submission that climbs a ladder. It never climbs down.
| State | Meaning |
|---|---|
queued | Accepted and signed; waiting to be handed to the authority |
handed_off | The authority has the document and has acknowledged it |
registered | The authority has registered it and issued its reference number. This is the milestone that uses credits |
transmitted | The authority has sent it on to the buyer’s access point |
delivered | The buyer’s access point has confirmed receipt |
Three states sit off the ladder:
| State | Meaning | What you can do |
|---|---|---|
rejected | The authority refused the content; the reasons come back on the invoice | Reopen, correct, submit again |
parked | The run stopped for a reason that is not the content: the authority was unavailable, the connection was not ready, the number clashed, or the buyer could not be reached | Retry with POST /i/v1/invoices/{id}/retry; for a number clash, POST /i/v1/invoices/{id}/renumber |
withdrawn | Voided before hand-off, or replaced by a renumbered run | Nothing |
A submission that is already registered is never demoted. If the authority later reports a problem with it, the invoice keeps its registration and the problem is recorded against it.
Resubmitting after a rejection is a new submission, and uses credits again.
simpleStatus
| Value | When |
|---|---|
draft | Document is a draft |
issued | Finalised, not yet registered by the authority |
reported | Registered by the authority |
delivered | Confirmed by the buyer’s access point |
part_paid | A partial payment is recorded |
paid | Paid in full |
cancelled | Voided |
reportedToNrs is the same fact as reported or later, as a boolean, for callers who only need to know whether the authority has it.
Payments
Record what the buyer paid with PATCH /i/v1/invoices/{id}/payment-status: unpaid, partially_paid, paid or payment_failed, with an amount and a reference. Registered invoices have their payment status reported to the authority as well.
Credit and debit notes
Cancelling a finalised invoice (POST /i/v1/invoices/{id}/cancel) issues the closing credit note; it is the only way an invoice becomes cancelled. A partial credit note (POST /i/v1/invoices/{id}/credit-notes) or a debit note (POST /i/v1/invoices/{id}/debit-notes) changes what is owed without cancelling the original. invoiceType on create accepts standard only.
Issuing without reporting
POST /i/v1/invoices/{id}/issue finalises an invoice and issues it to the buyer without submitting it to the authority. Use it where reporting is not required for the document, and submit later if it becomes so.
Watching the lifecycle
Poll GET /i/v1/invoices/{id}/status, or subscribe to the submission events through webhooks: one event per rung of the ladder, plus rejected, parked, resumed and withdrawn. The authority’s own status can be asked for directly with POST /i/v1/invoices/{id}/query-status, which uses credits; the automatic checks behind the ladder do not.