Edit numbering series
Update a series with PUT /v1/series/{series} and the MCP tool update_series, under the same fiscal guards as the web app.
4 October 2026
A numbering series can now be edited through the API and MCP. The new operation is
PUT /v1/series/{series} (scope
series:write) and the MCP tool is update_series, with the same contract.
It is a partial update: only the fields you send change.
| Field | Meaning |
|---|---|
name | Name of the series (1–100 characters). |
code | Prefix of the series (1–10 characters: letters, numbers, - and _). |
counter_reset | never, annual or monthly. monthly requires the {MM} token in the mask. The change is prospective. |
year_reset | Deprecated boolean alias of counter_reset; counter_reset wins when both arrive. |
number_format | Numbering mask, for example {code}-{YYYY}-{000}. |
initial_number | Number the counter starts from (1 or more). |
invoice_kind | Purpose of an invoice series: complete, simplified, corrective or simplified_corrective. |
document_type cannot be sent. The call answers 200 with the updated
Series resource, 404
series_not_found when the series is not yours, and 422 when a guard rejects the
change. Nothing is changed in that case.
Fiscal guards
Each guard is a 422 business_rule_violation with its own subcode:
subcode | Rule |
|---|---|
series_code_immutable_with_documents | code can only change while the series has no documents. |
series_format_immutable_with_documents | number_format can only change until the first document is issued. |
series_locked_by_verifactu | Once the AEAT has accepted a record of one of its invoices, code, number_format and initial_number are locked. |
series_initial_number_creates_gap | initial_number cannot open a gap after documents of the current year. |
series_invoice_kind_locked | invoice_kind is fixed with the first invoice of the series. |
series_default_kind_change | The default series of a purpose cannot change purpose. |
A code already used by another series of the same document type returns 422
with param: code. An invalid initial number (invalid_series_number) or purpose
(series_invoice_kind_invalid) answers parameter_invalid_value, and
counter_reset: monthly with a mask that has no {MM} token answers
monthly_requires_month_segmented_format. The code
series_format_immutable_with_documents is new in the
error catalog.
Webhooks and the rest of the series operations
- Changing only
counter_resetalso emits the webhookseries.updated. PATCHandDELETEon/v1/series/{series}keep answering405series_immutable; the response now carriesAllow: GET, PUT. A series is never deleted: archive it withPOST /v1/series/{series}/archive.- The description of the archive operation states its rejections as
422business_rule_violation:cannot_archive_last_default_seriesandseries_already_archived. - The descriptions of the series resource and of the create operation state which fields can be edited afterwards and until when.
New endpoints1
| Endpoint | Description |
|---|---|
PUT/v1/series/{series} | Update a series |
Updated endpoints3
| Endpoint | Description |
|---|---|
POST/v1/series | Create a series |
GET/v1/series/{series} | Retrieve a series |
POST/v1/series/{series}/archive | Archive a series |