# Invoice series Manage the numbering series used when invoices are issued. 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` Type: `string` Opaque identifier for an invoice series. #### `object` Type: `string` String identifying this as an Invoice Series object. Always `invoice_series`. #### `live` Type: `boolean` True when the object belongs to the live environment; false for test data. #### `account` Type: `string` Account that owns the series. #### `prefix` Type: `string` Prefix used to generate human-readable invoice numbers. #### `default_for` Type: `array of enums` Account operations that use this series when no explicit series is supplied. #### `created_at` Type: `string` When the invoice series was created. ### Example ```json { "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` Type: `string` — required Series prefix. FiscalRail strips whitespace, converts it to uppercase, and prepends `TEST-` for test accounts. #### `default_for` Type: `array of enums` Account operations that should use the new series by default. ### Responses - `201` — [An Invoice Series object.](#the-invoice-series-object) Formats: JSON. ### Example request ```bash curl --request POST \ 'https://api.fiscalrail.com/v1/invoice-series' \ --header "Authorization: Bearer ak_test_..." ``` ### Example response — 201 ```json { "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` Type: `string` — required The opaque ID of the invoice series. ### Responses - `200` — [An Invoice Series object.](#the-invoice-series-object) Formats: JSON. ### Example request ```bash curl --request GET \ 'https://api.fiscalrail.com/v1/invoice-series/inv_ser_14Vxtqg4QFd6rL8cUoK3sZ' \ --header "Authorization: Bearer ak_test_..." ``` ### Example response — 200 ```json { "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` Type: `string` — required The opaque ID of the invoice series. ### Request body #### `prefix` Type: `string` New prefix. FiscalRail normalizes it and preserves the required `TEST-` marker for test accounts. #### `default_for` Type: `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.](#the-invoice-series-object) Formats: JSON. ### Example request ```bash curl --request PATCH \ 'https://api.fiscalrail.com/v1/invoice-series/inv_ser_14Vxtqg4QFd6rL8cUoK3sZ' \ --header "Authorization: Bearer ak_test_..." ``` ### Example response — 200 ```json { "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` Type: `string` — required The opaque ID of the invoice series. ### Responses - `204` — The invoice series was deleted. The response has no body. ### Example request ```bash 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` Type: `integer` Maximum number of resources to return. Defaults to `25`. #### `starting_after` Type: `string` Return invoice series older than this series ID. Cannot be combined with `ending_before`. #### `ending_before` Type: `string` Return invoice series newer than this series ID. Cannot be combined with `starting_after`. ### Responses - `200` — [A list of Invoice Series objects.](#the-invoice-series-object) Formats: JSON. ### Example request ```bash curl --request GET \ 'https://api.fiscalrail.com/v1/invoice-series?limit=25' \ --header "Authorization: Bearer ak_test_..." ``` ### Example response — 200 ```json { "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" } ] } ```