Series and numbering

The RD 1619/2012 requires invoice numbering to be correlative within each series (article 6.1.a). In BeeL. each sequence is a series: a code, a number format and a counter. This page covers when numbers are consumed, how they are built, and the rules that keep a sequence without gaps.

The number is assigned when you issue

A draft has no number. invoice_number stays empty until Issue an invoice (or options.issue_directly: true at creation) takes the next one from the series. Two consequences:

• Deleting a draft leaves no gap. It never consumed a number.
• A rejected issue consumes nothing. The invoice is validated, and the company's readiness and quota are checked, before a number is taken. If any of that fails — or another request is issuing the same invoice at the same moment (409 CONCURRENT_MODIFICATION) — the counter is untouched.

Once assigned, a number is never reused: a voided invoice keeps its number, and so does every corrective.

Two more checks run at issue time, and neither consumes a number:

• The number must be unique in the company. If the number the series would assign is already used by another invoice of the same company, in this series or another one, the issue answers 400 SERIES_NUMBER_COLLISION and nothing is issued. Retrying gives the same result: the series needs review, so contact support.
• The number must fit the AEAT. More than 60 characters characters answers 422 INVOICE_NUMBER_TOO_LONG, and a character the AEAT does not accept answers 422 INVOICE_NUMBER_INVALID_CHARACTERS. Issue it with another series, or fix the series while it has no issued invoices.

Sandbox and production number independently, so testing never consumes production numbers.

The format

format is a template. It must contain {NUM} or {NUM:X}, and it only accepts these uppercase tokens:

The date tokens come from the invoice's issue date. Besides the tokens, a format may contain uppercase letters, digits, -, _ and /.

All format errors answer 422: a missing {NUM} is SERIES_FORMAT_NUM_REQUIRED, an unknown token such as {FOO} is SERIES_FORMAT_UNRECOGNIZED_VARS, and a padding outside 1–20 is SERIES_FORMAT_INVALID_PADDING. Lowercase letters anywhere in the format — a token like {num} or a literal like fac- — and any other character outside the set above answer VALIDATION_ERROR with error.details.format.

The number must fit the AEAT

The generated number is the invoice number sent to the AEAT, which accepts at most 60 characters printable ASCII characters and none of ", ', <, >, =. The series is checked when you create or edit it, taking its longest possible number — the counter counts as at least 9 digits, since {NUM:X} is a minimum width and the number keeps growing past it. A format that breaks the rule answers 422 SERIES_FORMAT_NUMBER_TOO_LONG or 422 SERIES_FORMAT_INVALID_CHARACTERS.

Two series cannot print the same number

An invoice number must be unique per issuer, so a series whose code and format could print a number that another series of the company can also print — in the same environment, active or not — is refused with 409 SERIES_FORMAT_OVERLAPS, naming the other series. It applies when you create a series and when you change its code, format or document_type. Two series with {YYYY}-{NUM:4} would both issue 2026-0001: put {CODIGO}, or a literal of its own, in every format. Proforma series are not compared.

Counter reset and initial number

counter_reset decides when the counter starts over. It defaults to ANNUAL, and the format must be able to tell the periods apart, or the same number would print twice:

So a format with no year token, such as {CODIGO}/{NUM:6}, has to be sent with counter_reset: NEVER.

How the counter works

A series keeps one counter per period, and the period is taken from the invoice's issue date — which is always the day it is issued, in Madrid time:

The first counter of the series starts at initial_number (1–999999, default 1); every later counter starts at 1. Each following invoice of a period takes the next number. Nothing happens at midnight on 31 December: the new counter simply starts with the first invoice issued in January. next_number on the series is the number an invoice issued today would take.

initial_number applies to the first period only

initial_number is where the series starts: it applies to the first period in which the series issues an invoice, and every later period starts at 1. A series created with counter_reset: ANNUAL and initial_number: 151 numbers like this:

The same holds for the other policies:

• MONTHLY, initial_number: 151, format {CODIGO}-{YYYY}{MM}-{NUM:3}: FAC-202609-151, FAC-202609-152, then FAC-202610-001 on 1 October and FAC-202611-001 on 1 November.
• NEVER, initial_number: 151, format {CODIGO}/{NUM:6}: FAC/000151, FAC/000152, FAC/000153… There is a single period, so it keeps counting across years.

Continuing a sequence from another system

If your last invoice this year was 2026-0150, create the series with initial_number: 151 and the next invoice is …-2026-0151. initial_number cannot be changed once the series has issued, so pick the reset that matches how your numbering should look next year:

The series of the example above:

curl -X POST https://app.beel.es/api/v1/companies/{company_id}/series \
  -H "Authorization: Bearer $BEEL_API_KEY" \
  -H "Idempotency-Key: series-fac-2026" \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "STANDARD",
    "name": "Main series",
    "code": "FAC",
    "format": "{CODIGO}-{YYYY}-{NUM:4}",
    "counter_reset": "ANNUAL",
    "initial_number": 151
  }'

Default series per document type

Each series belongs to one document_type — STANDARD, SIMPLIFIED, CORRECTIVE or PROFORMA — and only numbers documents of its type. document_type is required when you create a series. Standard, simplified and corrective invoices each need a series of their own (RD 1619/2012, arts. 6.1.a and 7.1.a). UNASSIGNED is a legacy value of series created before types existed: such a series numbers no type — picking it answers 422 SERIES_INCOMPATIBLE_DOC_TYPE — and no series can be created with it or moved to it (422 SERIES_UNASSIGNED_TYPE_NOT_ALLOWED). The live ones were given the type they numbered most; to keep using one that is still UNASSIGNED, give it a type. Listing series with document_type returns only the series of that type, the only ones that can number it.

Every document type with active series has exactly one default, used whenever you create or issue a document without series_id:

• The first series of a type becomes its default, even if you send default_series: false.
• Hand the default over with Mark a series as default on the new one; the previous default is unmarked. Sending default_series: false to the current default answers DEFAULT_CANNOT_BE_UNMARKED.
• The default cannot be deactivated (DEFAULT_CANNOT_DEACTIVATE), and an inactive series cannot become the default (INACTIVE_CANNOT_BE_DEFAULT).
• Simplified and corrective defaults are created on first use. A simplified invoice or a corrective sent without series_id, when the company has no default of that type, gets one created on the spot (code S or R, or the next free one) and is numbered in it.
• No standard default, no issue. A standard invoice without series_id and no default STANDARD series answers 422 SERIES_DEFAULT_NOT_FOUND. Get the issuing readiness of a company reports it as a blocker before you try.

The quickest way to a complete set is Ensure a default series per document type. For each of STANDARD, SIMPLIFIED and CORRECTIVE that has no default it creates one — codes F, S and R, format {CODIGO}-{YYYY}-{NUM:4} — and it keeps the defaults you already have. It is safe to repeat:

curl -X PUT https://app.beel.es/api/v1/companies/{company_id}/series/defaults \
  -H "Authorization: Bearer $BEEL_API_KEY"

If one of those codes already belongs to another series, that type is left out of the response and keeps no default.

Correctives and proformas

• Corrective invoices are numbered in the company's default CORRECTIVE series when you omit series_id — never in the series of the invoice they correct, which is a standard or simplified one and cannot hold a corrective. If the company has none, it is created on first use (code R, or the next free one); GET …/series/defaults shows which types already have one. Send series_id to pick a specific corrective series. If your other system numbers credit notes in a sequence of their own (REC-…), create a CORRECTIVE series for it and make it the default.
• Proformas use a PROFORMA series, which is non-fiscal: the first proforma you create gets a default one (numbers PRO-…) if you have none. A proforma can never be numbered in a fiscal series, nor an invoice in a proforma series.

A series that does not match the document's type is refused with 422 SERIES_INCOMPATIBLE_DOC_TYPE when you pick it, when a draft or a recurring invoice template changes its type or series, and, as a last check, when the document is issued. An inactive series cannot issue (400 SERIES_INACTIVE): a draft can still be created in it, but issuing it is refused, and no number is used.

A series locks once it has issued

The moment a series issues its first invoice, the fields that build numbers are frozen for good and the series reports numbering_locked: true. Drafts do not lock it — they have no number.

The five refusals answer 400. If a change and an issue race each other, the change may also be refused with SERIES_NUMBERING_FROZEN: same meaning. To number differently from now on, create a new series and make it the default.

Deleting a series

Delete an invoice series refuses when:

Issued invoices can never be deleted, so a series that has issued can never be deleted either: deactivate it instead. Deleting a draft-only series works once its drafts are gone.

A code is never released. It keeps identifying the invoices already issued under it, so creating a series with the code of an existing or deleted one answers 409 SERIES_CODE_DUPLICATED.

Related