Documentation
Browse documentation

Invoice series

Manage the numbering series used when invoices are issued.
View as Markdown

An invoice series supplies the prefix and independent sequence used to generate invoice numbers such as INV-00001. Its internal counter is 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.

Prefixes contain at most 20 uppercase letters or digits. FiscalRail normalizes input on creation and update. 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. Issued invoice numbers and their series remain immutable.

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
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. 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
curl --request POST \
  'https://api.fiscalrail.com/v1/invoice-series' \
  --header "Authorization: Bearer ak_test_..."
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
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}

Makes or stops making this series the account default. Series prefixes are immutable through the API.

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.
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
curl --request PATCH \
  '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"
}

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
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
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"
    }
  ]
}