# Series and numbering

When an invoice gets its number, how the format and counter resets work, default series per document type, and why a series locks once it has issued.

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](/invoices/issueCompanyInvoice) (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`](/errors/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`](/errors/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`](/errors/INVOICE_NUMBER_TOO_LONG), and a character the AEAT does not accept answers `422` [`INVOICE_NUMBER_INVALID_CHARACTERS`](/errors/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.

> **Rules that apply here:** [NUM-001 · The number is assigned when the invoice is issued](/rules/numbering#num-001) · [NUM-002 · An issued number is never reused, even when the invoice is voided](/rules/numbering#num-002)

## The format

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

| Token | Becomes | Example |
|---|---|---|
| `{CODIGO}` | The series `code` | `F` |
| `{YYYY}` | Year, 4 digits | `2026` |
| `{YY}` | Year, 2 digits | `26` |
| `{MM}` | Month, 2 digits | `09` |
| `{NUM}` | The sequential number, no padding | `7` |
| `{NUM:X}` | The number padded to X digits (1–20) | `{NUM:4}` → `0007` |

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

| Format | Number |
|---|---|
| `{CODIGO}-{YYYY}-{NUM:4}` | `F-2026-0007` |
| `{CODIGO}/{NUM:6}` | `F/000007` |
| `{YYYY}{MM}-{NUM:3}` | `202609-007` |

All format errors answer `422`: a missing `{NUM}` is [`SERIES_FORMAT_NUM_REQUIRED`](/errors/SERIES_FORMAT_NUM_REQUIRED), an unknown token such as `{FOO}` is [`SERIES_FORMAT_UNRECOGNIZED_VARS`](/errors/SERIES_FORMAT_UNRECOGNIZED_VARS), and a padding outside 1–20 is [`SERIES_FORMAT_INVALID_PADDING`](/errors/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`](/errors/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`](/errors/SERIES_FORMAT_NUMBER_TOO_LONG) or `422` [`SERIES_FORMAT_INVALID_CHARACTERS`](/errors/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`](/errors/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.

> **Rules that apply here:** [NUM-008 · An invoice number fits AEAT's length and character set](/rules/numbering#num-008)

## 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:

| `counter_reset` | Starts over | The format must contain |
|---|---|---|
| `ANNUAL` (default) | Each new year | `{YYYY}` or `{YY}` — otherwise [`SERIES_ANNUAL_REQUIRES_YEAR`](/errors/SERIES_ANNUAL_REQUIRES_YEAR) |
| `MONTHLY` | Each new month | `{MM}` and a year token — otherwise [`SERIES_MONTHLY_REQUIRES_MONTH_AND_YEAR`](/errors/SERIES_MONTHLY_REQUIRES_MONTH_AND_YEAR) |
| `NEVER` | Never | Nothing extra |

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:

| `counter_reset` | One counter for | So a new counter starts |
|---|---|---|
| `ANNUAL` | each calendar year | on the first invoice issued in a new year |
| `MONTHLY` | each calendar month | on the first invoice issued in a new month |
| `NEVER` | the whole life of the series | never |

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.

> **Rules that apply here:** [NUM-003 · Numbers are correlative within each series](/rules/numbering#num-003)

### `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:

| Issued on | Number |
|---|---|
| 24 Sep 2026 | `FAC-2026-0151` |
| 24 Sep 2026 | `FAC-2026-0152` |
| 31 Dec 2026 | `FAC-2026-0153` |
| 1 Jan 2027 | `FAC-2027-0001` |
| 2 Jan 2027 | `FAC-2027-0002` |
| 1 Jan 2028 | `FAC-2028-0001` |

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:

| You want | Do this |
|---|---|
| Continue at 151 this year, restart at 1 next year | `counter_reset: ANNUAL` with `initial_number: 151`. |
| One sequence that never restarts | `counter_reset: NEVER` with `initial_number: 151`. A year token in the format is allowed but does not restart the count. |

The series of the example above:

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

> **Rules that apply here:** [NUM-003 · Numbers are correlative within each series](/rules/numbering#num-003)

## 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`](/errors/SERIES_INCOMPATIBLE_DOC_TYPE) — and no series can be created with it or moved to it (`422` [`SERIES_UNASSIGNED_TYPE_NOT_ALLOWED`](/errors/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](/invoice-series/setCompanyDefaultSeries) on the new one; the previous default is unmarked. Sending `default_series: false` to the current default answers [`DEFAULT_CANNOT_BE_UNMARKED`](/errors/DEFAULT_CANNOT_BE_UNMARKED).
- **The default cannot be deactivated** ([`DEFAULT_CANNOT_DEACTIVATE`](/errors/DEFAULT_CANNOT_DEACTIVATE)), and an inactive series cannot become the default ([`INACTIVE_CANNOT_BE_DEFAULT`](/errors/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`](/errors/SERIES_DEFAULT_NOT_FOUND). [Get the issuing readiness of a company](/companies/getCompanyIssuingReadiness) reports it as a blocker before you try.

The quickest way to a complete set is [Ensure a default series per document type](/invoice-series/ensureCompanyDefaultSeries). 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:

```bash
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`](/invoice-series/getCompanyDefaultSeries) 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`](/errors/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`](/errors/SERIES_INACTIVE)): a draft can still be created in it, but issuing it is refused, and no number is used.

> **Rules that apply here:** [NUM-004 · Separate series may be used when there is a reason for them](/rules/numbering#num-004) · [NUM-005 · Simplified invoices are numbered in their own series](/rules/numbering#num-005) · [NUM-006 · Corrective invoices are numbered in their own series](/rules/numbering#num-006)

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

| Field | Before the first issue | After |
|---|---|---|
| `name`, `description` | Editable | Editable |
| `active`, `default_series` | Editable | Editable (subject to the default rules above) |
| `code` | Editable | [`SERIES_CODE_LOCKED_HAS_INVOICES`](/errors/SERIES_CODE_LOCKED_HAS_INVOICES) |
| `format` | Editable | [`SERIES_FORMAT_LOCKED_HAS_INVOICES`](/errors/SERIES_FORMAT_LOCKED_HAS_INVOICES) |
| `counter_reset` | Editable | [`SERIES_RESET_LOCKED_HAS_INVOICES`](/errors/SERIES_RESET_LOCKED_HAS_INVOICES) |
| `initial_number` | Editable | [`SERIES_INITIAL_NUMBER_LOCKED_HAS_INVOICES`](/errors/SERIES_INITIAL_NUMBER_LOCKED_HAS_INVOICES) |
| `document_type` | Editable | [`SERIES_DOCUMENT_TYPE_LOCKED_HAS_INVOICES`](/errors/SERIES_DOCUMENT_TYPE_LOCKED_HAS_INVOICES) — except on an `UNASSIGNED` series, which can still be given a type |

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

> **Rules that apply here:** [NUM-007 · A series cannot be renumbered once it has issued](/rules/numbering#num-007)

## Deleting a series

[Delete an invoice series](/invoice-series/deleteCompanySeries) refuses when:

| Why | `error.code` |
|---|---|
| It has invoices — drafts included | [`HAS_INVOICES_CANNOT_DELETE`](/errors/HAS_INVOICES_CANNOT_DELETE) |
| It is the default and its type has other active series | [`DEFAULT_CANNOT_DELETE`](/errors/DEFAULT_CANNOT_DELETE) |
| A payment connection uses it | [`REFERENCED_BY_PAYMENT_CONNECTION`](/errors/REFERENCED_BY_PAYMENT_CONNECTION) |
| An active or paused recurring invoice uses it | [`REFERENCED_BY_RECURRING_INVOICE`](/errors/REFERENCED_BY_RECURRING_INVOICE) |

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

<Related>

- [Invoice lifecycle](/guides/invoice-lifecycle) — draft, issue, send, pay — and what each status allows
- [Corrective invoices](/verifactu/corrective-invoices) — amending an issued invoice with its own number
- [Series reference](/invoice-series/listCompanySeries) — every series operation and field

</Related>

---

Full OpenAPI spec: https://docs.beel.es/api/openapi