Skip to main content
Every invoice moves through a defined set of statuses from the moment you create it to the moment it’s settled or cancelled. Understanding the lifecycle helps you keep your records accurate and prevents unintended changes to invoices you’ve already sent.

​
Status overview

​
Draft

When you create a new invoice, it starts in draft status. A draft has no invoice number yet and can be edited freely — client details, line items, amounts, due date, and notes are all changeable.
Use the draft stage to build and review your invoice before committing it. Once you finalize, certain fields are frozen permanently.

​
Finalize

Finalizing an invoice does two things:
  1. Assigns a sequential invoice number in the format PREFIX/FY/SEQUENCE — for example, INV/25-26/0001. The prefix and financial year are derived from your settings; the sequence number increments automatically.
  2. Moves the invoice to open status, making it ready to send to your client.
In the UI: Open the invoice and click Finalize. Via the API:
The Idempotency-Key header is required when finalizing via the API. It prevents duplicate invoice numbers if your request is retried after a timeout. Use a fresh UUID for each distinct finalize operation; reuse the same key to safely retry the same operation.

​
Frozen snapshots

At the moment of finalization, Invoice AI takes a snapshot of your business details and the client’s details. These snapshots are stored permanently on the invoice — they will not change even if you later update your profile, address, tax ID, or the client’s information. This means the invoice you sent always reflects exactly what was agreed at the time, which is important for compliance and audit purposes.

​
Mark as paid

Once you’ve received payment, mark the invoice as paid to close it out. In the UI: Open the open invoice and click Mark as paid. Via the API:
Like finalize, the pay endpoint requires an Idempotency-Key to prevent the invoice from being double-marked as paid on a network retry.

​
Overdue

An open invoice becomes overdue automatically once its due date has passed. There is nothing to configure or trigger — Invoice AI computes overdue status from the due date at display time. Because overdue is derived rather than stored, it stays accurate without any scheduled jobs or manual updates. The invoice remains in open status internally; overdue is a display-layer label.

​
Void

Voiding cancels an invoice permanently. You can optionally provide a reason, which is stored on the invoice record for your reference. In the API response, the stored reason is returned in the void_reason field. In the UI: Open the invoice and click Void, then enter an optional reason. Via the API:
The voided invoice object returned by the API includes a void_reason field containing the reason you supplied (or null if none was given).
Voiding is irreversible. A voided invoice cannot be re-opened, edited, or paid. If you need to bill for the same work again, create a new invoice.

​
Allowed transitions

Not every status change is valid. The table below shows which transitions Invoice AI permits:

​
API idempotency reference

Both finalize and pay are non-idempotent by default — retrying them without a key could assign a second invoice number or double-record a payment. The Idempotency-Key header makes these operations safe to retry:
  • Use a UUID v4 generated once per logical operation.
  • If the first request succeeds, repeating it with the same key returns the original response without side effects.
  • If the first request times out or errors, retry with the same key to pick up where you left off.
The void endpoint does not require an idempotency key because voiding is naturally idempotent — voiding an already-voided invoice is a no-op.