Invoice events

Overview

Invoices emit standard policy events at each significant transition. Subscribe to these the same way you subscribe to any other policy event, for example to send a notification with the invoice PDF attached, or to reconcile against an external system.

Event	Fires when	Payload
`invoice_created`	The invoice is finalised and moves to `pending`.	`invoice_id`, `invoice_type`, `reference`
`invoice_sent`	A payment is created for the invoice and it moves to `sent`.	`invoice_id`
`invoice_paid`	The linked payment succeeds and the invoice moves to `paid`.	`invoice_id`, `payment_id`
`invoice_voided`	The invoice is cancelled and moves to `void`.	`invoice_id`, `reason` (optional)
`invoice_refunded`	A credit note reverses the invoice and it moves to `refunded`.	`invoice_id`, `refund_invoice_id`

📘
Events carry references, not documents
Event payloads are deliberately small. They carry the invoice ID and a few key fields, never the line items or the PDF. In particular, invoice_created does not carry document_file_id, because the PDF is rendered asynchronously after the event fires. A consumer that needs the document or the fu

When each event fires

invoice_created is your signal that a new, finalised invoice exists. Use it to start a "new invoice" notification flow. Re-fetch the invoice shortly after if you need the rendered PDF, since document_file_id is populated once rendering completes.
invoice_sent indicates the daily payment routine has created a collection payment for the invoice.
invoice_paid confirms the collection succeeded. The payment_id ties the invoice to the successful payment.
invoice_voided indicates the invoice was cancelled before payment. A reason may accompany it.
invoice_refunded fires on the original invoice when a credit note is raised against it. refund_invoice_id points to the credit note. See Credit notes and refunds .

Idempotency

Invoice transitions are idempotent where redelivery is possible. Linking the same payment to an already-sent invoice does not re-fire invoice_sent, and a redelivered payment-success notification will not move an already-paid invoice or re-fire invoice_paid. Build your consumers to tolerate at-least-once delivery regardless.