Invoice lifecycle

Track Sales Invoices API status changes through different stages: from draft creation to payment, cancellation and e-invoice delivery.

Invoice states

Status	Category	Description
`draft`	Initial	Invoice created but not yet sent. Editable.
`issued`	Active	Invoice sent to recipient. Payment link payments are possible.
`overdue`	Active	Past the due date with no full payment received.
`payment-reversed`	Active	Paid, but payment was reversed (e..g., chargeback or dispute). Payable again.
`pending-payment`	In progress	A recurring payment using a mandate has been created and is being processed asynchronously.
`issuing`	In progress	E-invoices only. The invoice is being submitted to the e-invoicing network (e.g., Peppol).
`paid`	Settled	Invoice fully paid.
`cancelled`	Final	Invoice cancelled via a full credit note. No further transitions possible.
`failed`	Final	E-invoices only. Peppol delivery failed.

State machine

flowchart LR
    draft([draft])
    issued([issued])
    overdue([overdue])
    pr([payment-reversed])
    pending([pending-payment])
    paid([paid])
    cancelled([cancelled])
    issuing([issuing - e-invoice only])
    failed([failed - e-invoice only])

    draft -->|issue / send| issued

    issued -->|payment| paid
    issued -->|submit mandate| pending
    issued -->|overdue cron| overdue
    issued -->|full credit note| cancelled

    overdue -->|payment| paid
    overdue -->|submit mandate| pending
    overdue -->|full credit note| cancelled
    overdue -->|overdue cron| overdue

    pr -->|payment| paid
    pr -->|submit mandate| pending
    pr -->|full credit note| cancelled
    pr -->|overdue cron| overdue

    pending -->|webhook paid| paid
    pending -->|webhook failed / rejected| issued

    paid -->|mark as unpaid| pr

State transitions reference

Trigger	Transition
Create or update with `status: "issued"`	`draft → issued`
Create with `status: "paid"` and `paymentDetails`	`draft → issued → paid`
Mark as paid manually with `source: "manual"`	`issued / overdue / payment-reversed → paid`
Payment via payment link	`issued / overdue / payment-reversed → paid`
Submit `customerId` and `mandateId`	`issued / overdue / payment-reversed → pending-payment`
Recurring payment paid	`pending-payment → paid`
Recurring payment failed or cancelled	`pending-payment → issued`
Overdue cron runs daily	`issued / payment-reversed → overdue`
Mark as unpaid	`paid → payment-reversed`
Full credit note	`issued / overdue / payment-reversed → cancelled`

Cancelling an invoice

Once an invoice is issued, it becomes a legally binding document and cannot be deleted. You can cancel it in two ways:

Using API: update the invoice status directly to cancelled using PATCH /v2/sales-invoices/{id} with status: "cancelled".
In the Web App: use one of the options under the More menu:
- Cancel invoice — cancels the invoice immediately (same as the API).
- Add credit note — creates a credit note against the invoice. A full credit note also sets the invoice to cancelled. A partial credit note reduces the outstanding amount without cancelling the invoice, so the invoice remains active.

📘
Partial credit notes are only available in the Web App, not the API.

E-invoice state flow

E-invoices have an additional delivery sub-state that temporarily overrides the status field in the API response while Peppol submission is in progress.

issue invoice ──▶ issued
                     │
              e-invoice submission starts
                     │
              status: "issuing"
              eInvoiceStatus: "issuing"
                     │
              ┌──────┴────────┐
          success           failure
              │                 │
        status: "issued"   status: "failed"
        eInvoiceStatus:    eInvoiceStatus: "failed"
          "issued"                 │
                           retry (automatic or manual)
                                   │
                           status: "issuing" (loops back)

Key behaviors:

isEInvoice can be set on creation and updated while the invoice is in draft. It cannot be changed after the invoice is issued.
The response includes both status and eInvoiceStatus fields for e-invoices. Use eInvoiceStatus to track Peppol delivery independently of the payment state.
failed is currently not retriable.
Cancellation of an issued e-invoice is blocked while status = issuing. Wait for delivery to complete first.
Cancelling an issued e-invoice creates a credit note that also goes through the issuing → issued flow in Peppol network.
If emailDetails is also provided on an e-invoice, a standard PDF email is sent to the recipient in addition to the Peppol delivery.

Deleting a draft

A draft invoice can be permanently deleted using DELETE /v2/sales-invoices/{id}. Deletion is only possible while the invoice is in the draft status. Once issued, use a credit note to cancel it instead.