Skip to main content
An invoice in Invoice AI represents a request for payment sent from your business to a client. Each invoice moves through a defined set of statuses, carries a permanent audit trail, and freezes a snapshot of both parties’ details the moment it is finalized.

​
Invoice object overview

Every invoice has a unique identifier that begins with in_ (for example, in_ABcd1234EFgh5678IJkl9012). This ID is what you use across the API to retrieve, update, finalize, or void an invoice.

​
Key fields

​
Money: all amounts are integer minor units

Every monetary amount in the API is an integer in minor units — cents for USD/EUR/GBP, paise for INR, and so on. There are no decimal points in amounts.
Do not send or display raw API amounts directly. Always divide by 100 (or the appropriate minor-unit factor for your currency) before showing them to users.

​
Status reference

An invoice can be in one of five statuses. Four are stored in the database; one is derived at read time.
overdue is derived at display time, not written to the database. This means it is always accurate — there is no nightly job that could fall behind or silently stop. An invoice that was open on Tuesday will correctly show as overdue on Wednesday without any background process.
An invoice settled after its due date shows as paid — not overdue. Once an invoice is paid, it stays paid regardless of when payment arrived.

​
Lifecycle and valid transitions

Invoices follow a strict one-way state machine. The diagram below shows every allowed transition.

​
What each transition means in practice

  • Create → draft: The invoice is created with all its line items but no number. You can edit it freely.
  • Draft → open (finalize): The invoice number is assigned from your configured sequence. Business and client details are frozen into a snapshot at this point (see Snapshots).
  • Open → paid: You record that payment has been received. The paid_at timestamp is set.
  • Open → void: You cancel the invoice and provide a reason. The void_reason and voided_at fields are set. The invoice number is kept on the record so your number sequence has no unexplained gaps.
  • Deleting: You can only delete a draft. A finalized invoice cannot be deleted — use void instead.
You cannot move an invoice backward. A finalized invoice cannot return to draft, and a paid invoice cannot be voided (use a credit note instead). These restrictions protect the integrity of your invoice sequence.

​
Invoice numbering

Invoice numbers are assigned only when you finalize an invoice. A draft has number: null until that point. The default format is:
For example: INV/25-26/0001
  • Prefix — Configured in your business settings. Can contain letters, numbers, hyphens, and slashes (e.g. INV, ACME/INV). Maximum 16 characters.
  • Financial year — Derived from your invoice date (e.g. 25-26 for the 2025–2026 financial year).
  • Sequence — A zero-padded counter that increments with each finalized invoice. You control the starting number in your settings.
Number assignment uses a database-level lock so two invoices finalized at the same time cannot receive the same number. The operation is also retry-safe: finalizing an already-finalized invoice returns its existing number rather than assigning a new one.
You can customize your prefix and starting sequence number in Settings → Numbering. Changes only affect future invoices — numbers already assigned are permanent.

​
Snapshots: frozen details

When you finalize an invoice, Invoice AI captures a snapshot of your business details and your client’s details at that exact moment. These snapshots are stored permanently with the invoice. This means:
  • If you update your business address later, old invoices still show the address that was correct when they were issued.
  • If a client changes their name or email, their prior invoices remain accurate.
  • The PDF generated from a finalized invoice always matches what the client was sent, no matter how much time has passed.
Snapshots are automatic — you don’t need to do anything. Every time you finalize an invoice, the current state of your business profile and client record is captured and locked to that invoice.

​
Tax computation

Tax on each line item is a free-form percentage (tax_rate). There is no fixed tax code lookup. You enter the rate you need — whether that is VAT, GST, sales tax, or any other levy. The server always recomputes all totals. Any subtotals, tax amounts, or grand totals you send in an API request are ignored. Invoice AI calculates them from your line items. This guarantees that a document’s tax always matches its own lines — it cannot be manipulated client-side.
Every invoice has a public_url_token. You can construct a client-facing, no-login-required link with this token. The link lets your client view and download the invoice without needing an Invoice AI account. The token is assigned when the invoice is created and does not change when you finalize, pay, or void the invoice.

​
Line items

Each line item on an invoice has its own ID prefixed with ii_. Line items record: A line item can be catalog-linked (referencing a price_… ID from your product catalog) or ad-hoc (all values entered directly on the invoice). Both types appear identically in the finalized invoice.