# Invoice numbering

Understand when FiscalRail assigns invoice numbers and choose account or customer numbering.

## When numbering happens

FiscalRail assigns the final invoice code when an invoice is successfully issued. Your integration may select an invoice series; otherwise, FiscalRail uses the account default for that operation.

You can rely on FiscalRail to:

- assign numbers correlatively within each series;
- prevent concurrent requests from receiving the same code;
- leave rejected or rolled-back issuance attempts unnumbered; and
- keep every issued invoice code immutable.

The assigned `code` is returned on the invoice. Store that value instead of predicting the next number in your application. When retrying an uncertain issuance request, send the exact payload with the same `Idempotency-Key` so FiscalRail returns the original invoice rather than issuing another one.

## Invoice series

Every invoice belongs to an invoice series. A series provides the prefix in codes such as `INV-00001` or `CN-00001` and lets you keep different kinds of fiscal documents separately numbered.

Your account defines default series for ordinary invoices, credit notes, and amendment replacements. Issuance uses the applicable default unless you send another series ID in `series`.

Series prefixes contain at most 20 uppercase letters or digits. They become immutable after their first invoice, and a used series cannot be deleted. Test accounts add the reserved `TEST-` marker automatically.

See [Invoice series](/en/api/invoice-series) to create series and assign account defaults.

## Account and customer numbering

The account's `invoice_numbering_scope` determines whether each series is numbered across the whole account or separately for each customer. `account` is the default. `customer` prevents one customer from learning how many invoices you have issued to everyone else.

### Compare the two modes

| Document | Account numbering | Customer numbering |
| --- | --- | --- |
| Customer A's first invoice | `INV-00001` | `INV-A-00001` |
| Customer A's second invoice | `INV-00002` | `INV-A-00002` |
| Customer B's first invoice | `INV-00003` | `INV-B-00001` |
| Customer A's third invoice | `INV-00004` | `INV-A-00003` |
| Credit note for customer A | `CN-00001` | `CN-A-00001` |
| Customer B's second invoice | `INV-00005` | `INV-B-00002` |
| Credit note for customer B | `CN-00002` | `CN-B-00001` |
| Customerless invoice | `INV-00006` | `INV-00001` |

With customer numbering, FiscalRail combines the selected series prefix with the customer's `invoice_prefix`. Every customer already has a generated six-letter prefix, so enabling the mode requires no migration. You may provide a custom prefix when creating a customer or update it before issuing that customer's first invoice. It then becomes immutable.

Customerless invoices continue to use account numbering. The selected scope applies consistently to every configured series.

### The issuance API does not change

You continue to identify the customer and, optionally, the series exactly as before:

```bash
curl https://api.fiscalrail.com/v1/invoices \
  --request POST \
  --header "Authorization: Bearer $FISCALRAIL_API_KEY" \
  --header "Idempotency-Key: 2f294ef2-9a60-4c7e-a573-5e18fa8348e2" \
  --header "Content-Type: application/json" \
  --data '{
    "customer": "cus_...",
    "lines": [{
      "description": "Consulting",
      "quantity": "2",
      "unit_price": "75.00",
      "taxes": [{"tax": "vat", "rule": "general"}]
    }]
  }'
```

FiscalRail chooses the correct code and returns it on the issued invoice. You do not create a separate `InvoiceSeries` resource for every customer or change any invoice parameters.

### Enable customer numbering

In the Dashboard, open **Settings → Series**, choose **Separate sequence per customer** under **Numbering**, and save.

Or update the account through the API:

```bash
curl https://api.fiscalrail.com/v1/accounts/$ACCOUNT_ID \
  --request PATCH \
  --header "Authorization: Bearer $FISCALRAIL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"invoice_numbering_scope":"customer"}'
```

The change affects future invoices only. Switching back to `account` resumes the previous account numbering; re-enabling `customer` resumes each customer's previous numbering. Issued codes never change.

### Tax-regime implications

Some tax regimes regulate when separate invoice series may be used. FiscalRail preserves its numbering, immutability, and fiscal-record guarantees in both modes, but the reason for choosing separate customer series forms part of your invoicing policy.

Consult the guide for your account's tax regime before enabling customer numbering. For Spanish accounts, see [Invoice numbering under the Spain tax regime](/en/tax-regimes/spain#invoice-numbering).

See [Idempotency](/en/api/idempotency), [Accounts](/en/api/accounts), [Customers](/en/api/customers), and [Invoices](/en/api/invoices) for the complete API contract.