Invoice series — FiscalRail documentation

An invoice series supplies the configured series prefix. Account numbering generates numbers such as INV-00001. Customer numbering combines that prefix with the customer's invoice prefix to generate codes such as INV-ABCDEF-00001, while the invoice still belongs to the configured INV series. Customerless simplified invoices use the base sequence. Internal numbering keys and counters are intentionally not exposed or editable.

Accounts configure separate defaults for invoices, credit notes, and amendment replacements. Every account starts with an invoice default. Global-regime accounts leave the other two empty until you configure them; Spanish accounts start with three distinct defaults.

Account numbering is the default, including for Spanish accounts. The account's invoice_numbering_scope setting applies to every series. Customer numbering is opt-in. FiscalRail keeps one VERI*FACTU registration chain per account, but you should confirm that customer-specific numbering is appropriate for your business before enabling it.

Prefixes contain at most 20 uppercase letters or digits. FiscalRail normalizes input on creation and update. A prefix can be changed only before the series has issued its first invoice. Test-account prefixes always begin with the reserved TEST- marker, which FiscalRail adds automatically and counts toward the 20-character limit. A live-account prefix cannot begin with that marker.

A series can be deleted only before it has been used and only while it is not an account default. Once used, the series prefix and every issued invoice number remain immutable.

Read Invoice numbering for the complete configuration workflow, customer-prefix lifecycle, and scope-switching behavior.

The Invoice Series object

Properties

id string

Opaque identifier for an invoice series.

object string

String identifying this as an Invoice Series object. Always invoice_series.

live boolean

True when the object belongs to the live environment; false for test data.

account string

Account that owns the series.

prefix string

Base prefix used to generate human-readable invoice numbers.

default_for array of enums

Account operations that use this series when no explicit series is supplied.

created_at string

When the invoice series was created.

Invoice Series object

{
  "id": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
  "object": "invoice_series",
  "live": true,
  "account": "acct_14Vxtqg2nwvPR75TpsGH8N",
  "prefix": "INV",
  "default_for": [
    "invoice"
  ],
  "created_at": "2026-07-31T09:00:00Z"
}

Create an invoice series

POST/v1/invoice-series

Creates an invoice-series family. The account's invoice numbering scope applies to every series. The first series is automatically made the account default.

Request body

prefix string required

Series prefix. FiscalRail strips whitespace, converts it to uppercase, and prepends TEST- for test accounts.

default_for array of enums

Account operations that should use the new series by default.

Responses

201 An Invoice Series object. JSON

Example request


  
  import os

from fiscalrail import FiscalRail

client = FiscalRail(os.environ["FISCALRAIL_API_KEY"])

series = client.invoice_series.create(
    prefix="2027",
    default_for=[
        "invoice",
    ],
)

  
  curl --request POST \
  'https://api.fiscalrail.com/v1/invoice-series' \
  --header "Authorization: Bearer ak_test_..." \
  --json '{
  "prefix": "2027",
  "default_for": [
    "invoice"
  ]
}'

Example response — 201

{
  "id": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
  "object": "invoice_series",
  "live": true,
  "account": "acct_14Vxtqg2nwvPR75TpsGH8N",
  "prefix": "INV",
  "default_for": [
    "invoice"
  ],
  "created_at": "2026-07-31T09:00:00Z"
}

Retrieve an invoice series

GET/v1/invoice-series/{id}

Path parameters

id string required

The opaque ID of the invoice series.

Responses

200 An Invoice Series object. JSON

Example request

  import os

from fiscalrail import FiscalRail

client = FiscalRail(os.environ["FISCALRAIL_API_KEY"])

series = client.invoice_series.retrieve(
    "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
)

  curl --request GET \
  'https://api.fiscalrail.com/v1/invoice-series/inv_ser_14Vxtqg4QFd6rL8cUoK3sZ' \
  --header "Authorization: Bearer ak_test_..."

Example response — 200

{
  "id": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
  "object": "invoice_series",
  "live": true,
  "account": "acct_14Vxtqg2nwvPR75TpsGH8N",
  "prefix": "INV",
  "default_for": [
    "invoice"
  ],
  "created_at": "2026-07-31T09:00:00Z"
}

Update an invoice series

PATCH/v1/invoice-series/{id}

Changes the prefix or account operations that use this series by default.
Numbering scope is configured on the account and applies to every series.
The prefix can be changed only before the series has issued its first invoice.

Path parameters

id string required

The opaque ID of the invoice series.

Request body

prefix string

New prefix. FiscalRail normalizes it and preserves the required TEST- marker for test accounts. It cannot be changed after the series has issued an invoice.

default_for array of enums

Complete set of defaults assigned to this series. Omitted roles are cleared only when they currently point here.

Responses

200 The updated Invoice Series object. JSON

Example request


  
  import os

from fiscalrail import FiscalRail

client = FiscalRail(os.environ["FISCALRAIL_API_KEY"])

series = client.invoice_series.update(
    "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
    prefix="SALES",
    default_for=[
        "invoice",
    ],
)

  
  curl --request PATCH \
  'https://api.fiscalrail.com/v1/invoice-series/inv_ser_14Vxtqg4QFd6rL8cUoK3sZ' \
  --header "Authorization: Bearer ak_test_..." \
  --json '{
  "prefix": "SALES",
  "default_for": [
    "invoice"
  ]
}'

Example response — 200

{
  "id": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
  "object": "invoice_series",
  "live": true,
  "account": "acct_14Vxtqg2nwvPR75TpsGH8N",
  "prefix": "INV",
  "default_for": [
    "invoice"
  ],
  "created_at": "2026-07-31T09:00:00Z"
}

Delete an invoice series

DELETE/v1/invoice-series/{id}

Deletes an invoice series that has not been used to issue an invoice.

Path parameters

id string required

The opaque ID of the invoice series.

Responses

204 The invoice series was deleted. The response has no body.

Example request

  import os

from fiscalrail import FiscalRail

client = FiscalRail(os.environ["FISCALRAIL_API_KEY"])

client.invoice_series.delete(
    "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
)

  curl --request DELETE \
  'https://api.fiscalrail.com/v1/invoice-series/inv_ser_14Vxtqg4QFd6rL8cUoK3sZ' \
  --header "Authorization: Bearer ak_test_..."

List invoice series

GET/v1/invoice-series

Returns invoice series in reverse chronological ID order.

Query parameters

limit integer

Maximum number of resources to return. Defaults to 25.

starting_after string

Return invoice series older than this series ID. Cannot be combined with ending_before.

ending_before string

Return invoice series newer than this series ID. Cannot be combined with starting_after.

Responses

200 A list of Invoice Series objects. JSON

Example request

  import os

from fiscalrail import FiscalRail

client = FiscalRail(os.environ["FISCALRAIL_API_KEY"])

series = client.invoice_series.list(
    limit=25,
)

  curl --request GET \
  'https://api.fiscalrail.com/v1/invoice-series?limit=25' \
  --header "Authorization: Bearer ak_test_..."

Example response — 200

{
  "object": "list",
  "has_more": null,
  "data": [
    {
      "id": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
      "object": "invoice_series",
      "live": true,
      "account": "acct_14Vxtqg2nwvPR75TpsGH8N",
      "prefix": "INV",
      "default_for": [
        "invoice"
      ],
      "created_at": "2026-07-31T09:00:00Z"
    }
  ]
}