# Invoice series

Manage the numbering series used when invoices are issued.

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](/en/invoice-numbering) for the complete configuration workflow, customer-prefix lifecycle, and scope-switching behavior.

## 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`

Base 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 family. The account's invoice numbering scope applies to every 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 requests

#### Python

```python
import os

from fiscalrail import FiscalRail

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

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

#### cURL

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

### 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 requests

#### Python

```python
import os

from fiscalrail import FiscalRail

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

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

#### cURL

```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}`

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`

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. It cannot be changed after the series has issued an invoice.

#### `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 requests

#### Python

```python
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

```bash
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

```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 requests

#### Python

```python
import os

from fiscalrail import FiscalRail

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

client.invoice_series.delete(
    "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
)
```

#### cURL

```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 requests

#### Python

```python
import os

from fiscalrail import FiscalRail

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

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

#### cURL

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