# Invoice numbers

> Number series, templates, previews and verification.

Source: /docs/guides/invoice-numbers

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

```bash
# 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.

```bash
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 }'
```