Invoice numbers

Number series, templates, previews and verification.

View as Markdown Open in Claude Open in ChatGPT

Every organization has one number series per document kind: invoice, credit_note, debit_note, proforma, quote, order_confirmation, reminder and customer (default C-{n}). The app also keeps an item series (default IT-{n}) for item numbers; both the customer and item series are edited in the app under Settings → Outgoing invoices → Document Numbering. Numbers are allocated inside the database under a row lock, so two integrations creating invoices at the same time never get the same number.

Templates

A template is text with tokens:

Token	Meaning
`{n}`	The counter, zero-padded to `padLength` digits (required)
`{YYYY}`, `{YY}`	Year of the issue date
`{MM}`, `{DD}`	Month and day

Examples: INV-{n} → INV-0042; {YYYY}/{MM}/{n} → 2026/09/0042; CN-{YY}-{n} → CN-26-0007. resetYearly: true restarts the counter at 1 when the year changes. faktoora-style templates ending in -id or /id (for example YYYY/MM/id) are accepted and converted.

Routes

# Preview without allocating
curl "$BASE/invoices/next-number?series=invoice" -H "X-API-KEY: $KEY"
# → { "invoiceNumber": "INV-0043", "series": "invoice", "template": "INV-{n}", "counter": 43, "padLength": 4 }

# Is a number free?
curl "$BASE/invoices/verify-number?value=INV-0043" -H "X-API-KEY: $KEY"
# → { "available": true, "invoiceNumber": "INV-0043", "series": "invoice" }

# Read and change series settings (scopes settings:read / settings:write)
curl "$BASE/settings/invoice-number-template" -H "X-API-KEY: $KEY"
curl -X PUT "$BASE/settings/invoice-number-template" -H "X-API-KEY: $KEY" -H "Content-Type: application/json" \
  -d '{ "series": "invoice", "template": "INV-{YYYY}-{n}", "padLength": 5, "resetYearly": true }'

Behaviour on create

No invoiceNumber in the payload: the next number of the series is allocated at insert time.
invoiceNumber supplied: it must be unused (verify-number semantics); after the insert the series counter moves past it when the number matches the template.
Numbers are allocated even for test documents and drafts, so gaps can appear when a draft is deleted. UAE VAT rules require sequential numbering of issued tax invoices; keep drafts out of the invoice series by creating quotes or proformas first when the document may not be issued.

Manual numbers in the app

The organization option allowManualNumbers (default false) controls whether people may type a document number in the Alya Books editor. When it is false, the number field is read-only and every new invoice, credit or debit note, proforma, quote and other document takes the next number of its series, in order. It does not restrict integrations: an invoiceNumber supplied through the API or an import is accepted either way, as long as it is unused. Customer numbers are not affected.

curl "$BASE/settings/options" -H "X-API-KEY: $KEY"
# → { ..., "reserveNumbersInDrafts": true, "allowManualNumbers": false, ... }
curl -X PATCH "$BASE/settings/options" -H "X-API-KEY: $KEY" -H "Content-Type: application/json" \
  -d '{ "allowManualNumbers": true }'