InvoiceSeries

Update invoice series

Deprecated. The canonical form has a single update verb, PATCH /v1/companies/{company_id}/series/{series_id}. The same body produces the same result there — this route already merges field by field, leaving absent fields untouched — with one difference: an explicit description: null, which this route ignores, clears the description under PATCH.

Updates an existing invoice series with the body you send; absent fields keep their value.

  • Numbering fields: code, format, counter_reset and initial_number are rejected once the series has issued invoices (numbering_locked is true). name, description, active, default_series and document_type can always be changed.
  • active: a default series cannot be deactivated — set another one as default first.
  • default_series: sending false on the series that currently is the default is rejected with DEFAULT_CANNOT_BE_UNMARKED. Promote another series with PUT /v1/companies/{company_id}/series/{series_id}/default, which unmarks the previous one for you. An inactive series cannot be marked as default.

Retires on 9 December 2026. See the migration guide for what moved where and what changes when you switch.

put/v1/configuration/series/{series_id}

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/configuration/series/{series_id}
  • Auth: HTTP bearer

Path parameters

series_idstring uuid required

Universally Unique Identifier (UUID v4)

Example:550e8400-e29b-41d4-a716-446655440000

Series ID

Request body

document_type'UNASSIGNED' | 'STANDARD' | 'SIMPLIFIED' | 'CORRECTIVE' | 'SIMPLIFIED_CORRECTIVE' | 'PROFORMA'

Document type associated with a series. Values mirror InvoiceType, so the series a document needs is named exactly like the document:

  • UNASSIGNED: Legacy value of series created before types existed. A series numbers only documents of its own type, so an UNASSIGNED series numbers none (422 SERIES_INCOMPATIBLE_DOC_TYPE); give it a type to keep using it. 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.
  • STANDARD: Standard invoice
  • SIMPLIFIED: Simplified invoice
  • CORRECTIVE: Corrects or cancels a previous standard invoice (R1–R4)
  • SIMPLIFIED_CORRECTIVE: Corrects a simplified invoice (R5). Spanish law requires R5 to be numbered apart from R1–R4, so they have a series type of their own
  • PROFORMA: Proforma (commercial document, non-fiscal numbering)
namestring

Descriptive name of the series

codestring

Alphanumeric series code (used in {CODIGO} variable). Allows uppercase letters, numbers, hyphens and underscores.

descriptionstring nullable

Optional series description

formatstring

Format template with available variables (UPPERCASE ONLY):

  • {CODIGO}: Series code (e.g., "FAC")
  • {YYYY}: Year with 4 digits (e.g., "2025")
  • {YY}: Year with 2 digits (e.g., "25")
  • {MM}: Month with 2 digits (e.g., "01")
  • {NUM}: Sequential number without padding (e.g., "1")
  • {NUM:X}: Sequential number with padding (e.g., {NUM:4} → "0001")

REQUIRED: Must contain at least {NUM} or {NUM:X} IMPORTANT: Only uppercase (rejects {yy}, {mm}, {codigo}, etc.)

Valid examples:

  • "{CODIGO}-{YYYY}-{NUM:4}" → "FAC-2025-0001"
  • "{CODIGO}/{NUM:6}" → "FAC/000001"
  • "{YYYY}{MM}-{NUM:3}" → "202501-001"

The generated number is the invoice number sent to the AEAT, which accepts at most 60 printable ASCII characters and none of ", ', <, >, =. A format whose longest possible number breaks that rule is rejected with 422 SERIES_FORMAT_NUMBER_TOO_LONG or SERIES_FORMAT_INVALID_CHARACTERS. The counter counts as at least 9 digits, with or without padding: {NUM:X} is a minimum width, not a maximum.

counter_reset'NEVER' | 'ANNUAL' | 'MONTHLY'

Counter reset policy:

  • NEVER: Counter never resets (continuous numbering)
  • ANNUAL: Counter resets yearly
  • MONTHLY: Counter resets monthly
initial_numberinteger

Initial number for this series counter. Useful for adjusting numbering before the series issues its first invoice. For example, if you want the next invoice to be 2025-0054, set initial_number=54. It applies only to the first period in which the series issues an invoice: with counter_reset: ANNUAL or MONTHLY, every later year or month starts at 1. With NEVER there is a single period, so numbering simply continues from it.

activeboolean

Whether the series is active.

Restriction: A default series cannot be deactivated (another must be set as default first).

default_seriesboolean

Whether this is the default series.

Restriction: An inactive series cannot be marked as default.

Example request

{
  "name": "Main Series",
  "code": "FAC",
  "description": "Series for standard invoices",
  "format": "{CODIGO}-{YYYY}-{NUM:4}",
  "initial_number": 54
}

Response

Series updated successfully

successboolean required

Example response

{
  "success": true,
  "data": {
    "name": "Main Series",
    "code": "FAC",
    "description": "Series for standard invoices",
    "format": "{CODIGO}-{YYYY}-{NUM:4}",
    "initial_number": 1
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.