CompanySeries

Update an invoice series

Updates only the fields present in the body, leaving every other field of the series as it is.

  • Clearing a field: a field sent as null is cleared, which only description supports.
  • Numbering fields: code, format, counter_reset and initial_number are rejected once the series has issued invoices (numbering_locked is true).
  • Unique numbers per issuer: changing code, format or document_type so that the series could print a number another series of the company can also print is rejected with 409 SERIES_FORMAT_OVERLAPS.
  • default_series: it cannot be used to clear the default. Sending false for the series that currently is the default answers DEFAULT_CANNOT_BE_UNMARKED, because it would leave the document type with active series and no default, and issuing without an explicit series_id would then fail with SERIES_DEFAULT_NOT_FOUND. Hand the default over with PUT /v1/companies/{company_id}/series/{series_id}/default on the new series, which unmarks the previous one. Sending false for a series that is not the default is a no-op.
patch/v1/companies/{company_id}/series/{series_id}

Request

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

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. Cannot be cleared.

codestring

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

descriptionstring nullable

Series description. Send null to clear it.

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. Only while the series has no issued invoices. 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.