The invoice lifecycle
The states an invoice moves through, from draft to paid.
An invoice moves through a set of states from the moment it is created to the moment it is settled. The state tells you whether it is still being put together, waiting for payment, paid, or closed some other way.
The states
| State | What it means |
|---|---|
| Draft | A manual invoice still being composed. Not owed yet, and can still be edited. |
| Open | Finalized and waiting for payment. |
| Past due | Open but its due date has passed without full payment. |
| Paid | Settled in full. Final. |
| Voided | Cancelled before payment. It no longer counts. Final. |
| Written off | Given up as uncollectable. Final. |
Where invoices start
Most invoices are created by the billing engine, for a renewal or a new subscription, and they start life open, already waiting for payment. Draft is for invoices you compose by hand: you build the lines first, then finalize it, and finalizing is what moves it to open.
When an invoice is due
An invoice's due date decides when it tips into past due, which is what starts dunning. The due date is the day it was issued plus the customer's net terms.
Net terms is the number of days a customer has to pay. A customer on net 30 has thirty days from issue before an invoice is past due. Set it to zero and the invoice is due the day it is issued. You set net terms on the customer, and a single subscription can carry its own net terms that override the customer's for that subscription's invoices.
So the same setting shapes both the due date the customer sees and the moment the past-due clock and dunning begin.
Paid, or closed another way
An open invoice has four ways out:
- Paid: the customer pays it in full.
- Past due: the due date passes unpaid. It is still owed and can still be paid; the move to past due is what dunning watches to start chasing it.
- Voided: you cancel it before payment, for example because it was wrong. Voiding leaves a record but the invoice no longer counts toward what the customer owes.
- Written off: you accept it will not be paid and close it. It stays on the books as written off.
Paid, voided, and written off are final. An invoice never moves out of them; corrections after that point are made with credit notes and refunds, not by reopening the invoice.
Partially paid is not a state
An invoice that has received some but not all of its money is still open. "Partially paid" is worked out from the amounts (some paid, some still owed), not a separate state. So a half-paid invoice sits in open, and it still accepts the rest of the payment.
In the API
Invoices have endpoints for each move: POST /v1/invoices/{id}/finalize to open a draft, /pay to record payment, /void to cancel one, and /write-off to close it as uncollectable. You can also list and fetch invoices. See the API reference. When an invoice goes past due, dunning takes over the recovery.
Edge cases
- Only open and past due invoices can take a payment. A draft is not owed yet; a paid, voided, or written-off invoice is already closed.
- Re-paying a paid invoice is rejected. Paid is final, so there is nothing to pay.
- Tax is fixed when the invoice is generated. It is worked out once, at creation, and finalizing does not recalculate it. If a tax rate was missing and the invoice went out untaxed, the fix is to void it and create a new one, not to edit the old.