Invoice 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 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

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:

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:

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.

See Idempotency, Accounts, Customers, and Invoices for the complete API contract.