# Tax regimes

Discover the tax identifiers, rules and effective dates supported by FiscalRail.

Tax regimes describe the invoicing rules and structured taxes available to an account. The account's `tax_regime` identifies which catalog applies when FiscalRail resolves invoice-line tax references.

For structured regimes such as Spain, send `tax` and `rule` when issuing an invoice. FiscalRail resolves the percentage, description, authority metadata, `effect` and `treatment` effective on the invoice date. The catalog includes every effective-dated version so integrations do not need to hard-code current rates.

`effect` controls the arithmetic: `added` increases the invoice total and `withheld` reduces the amount payable. `treatment` describes the fiscal result: `taxable`, `exempt`, `reverse_charge` or `not_subject`. Only taxable treatments calculate a tax amount.

The `global` regime has an empty tax catalog because it accepts custom tax definitions at invoice issuance. Tax-regime data describes capabilities supported by FiscalRail and is not tax or legal advice.

For workflow context and the exact supported catalog, read the [Global tax regime](/en/docs/tax-regimes/global) or [Spain tax regime](/en/docs/tax-regimes/spain) guide.

## The Tax Regime object

### Properties

#### `id`

Type: `enum`

Stable tax regime key.

Possible values:

- `global` — Flexible global regime whose custom taxes are supplied when issuing an invoice.
- `es` — Spanish regime with FiscalRail-defined IVA and IRPF rules.

#### `object`

Type: `string`

String identifying this as a Tax Regime object. Always `tax_regime`.

#### `live`

Type: `boolean`

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

#### `taxes`

Type: `array of objects`

Structured taxes supported by the regime. Empty when the regime accepts custom taxes.

##### `taxes.tax`

Type: `string`

Stable tax identifier supplied as `taxes[].tax` during invoice issuance.

##### `taxes.name`

Type: `string`

Human-readable tax name.

##### `taxes.effect`

Type: `enum`

How the tax affects invoice totals.

Possible values:

- `added` — The tax amount is added to the invoice total.
- `withheld` — The tax amount is withheld from the amount payable to the supplier.

##### `taxes.rules`

Type: `array of objects`

Rate and treatment versions supported for this tax.

###### `taxes.rules.rule`

Type: `string`

Stable rule identifier supplied as `taxes[].rule` during invoice issuance.

###### `taxes.rules.description`

Type: `string`

Human-readable description used on invoices.

###### `taxes.rules.treatment`

Type: `enum`

Legal treatment applied by the rule.

Possible values:

- `taxable` — Tax applies to the taxable base at the stated rate.
- `exempt` — The taxable operation is exempt from the tax.
- `reverse_charge` — The recipient accounts for the tax.
- `not_subject` — The operation is outside the scope of the tax.

###### `taxes.rules.rate`

Type: `string or null`

Percentage including `%`, or null when a percentage does not apply.

###### `taxes.rules.authority_code`

Type: `string or null`

Corresponding tax-authority code when one applies.

###### `taxes.rules.legal_reference`

Type: `string or null`

Source provision supporting this rule when recorded.

###### `taxes.rules.effective_from`

Type: `string`

First date on which this rule version applies.

###### `taxes.rules.effective_until`

Type: `string or null`

Last date on which this rule version applies, or null when open-ended.




### Example

```json
{
  "id": "es",
  "object": "tax_regime",
  "live": true,
  "taxes": [
    {
      "tax": "vat",
      "name": "IVA",
      "effect": "added",
      "rules": [
        {
          "rule": "general",
          "description": "IVA 21%",
          "treatment": "taxable",
          "rate": "21%",
          "authority_code": null,
          "legal_reference": "Ley 37/1992, artículo 90",
          "effective_from": "2012-09-01",
          "effective_until": null
        }
      ]
    }
  ]
}
```

## Retrieve a tax regime

`GET /v1/tax-regimes/{id}`

Returns the regime's supported tax definitions and every effective-dated rule version.

### Path parameters

#### `id`

Type: `string` — required

Tax regime key, such as `es`.


### Responses

- `200` — [A Tax Regime object.](#the-tax-regime-object) Formats: JSON.

### Example request

```bash
curl --request GET \
  'https://api.fiscalrail.com/v1/tax-regimes/example' \
  --header "Authorization: Bearer ak_test_..."
```

### Example response — 200

```json
{
  "id": "es",
  "object": "tax_regime",
  "live": true,
  "taxes": [
    {
      "tax": "vat",
      "name": "IVA",
      "effect": "added",
      "rules": [
        {
          "rule": "general",
          "description": "IVA 21%",
          "treatment": "taxable",
          "rate": "21%",
          "authority_code": null,
          "legal_reference": "Ley 37/1992, artículo 90",
          "effective_from": "2012-09-01",
          "effective_until": null
        }
      ]
    }
  ]
}
```

## List tax regimes

`GET /v1/tax-regimes`

Returns every tax regime currently supported by FiscalRail and its structured tax catalog.

### Responses

- `200` — [A list of Tax Regime objects.](#the-tax-regime-object) Formats: JSON.

### Example request

```bash
curl --request GET \
  'https://api.fiscalrail.com/v1/tax-regimes' \
  --header "Authorization: Bearer ak_test_..."
```

### Example response — 200

```json
{
  "object": "list",
  "has_more": null,
  "data": [
    {
      "id": "es",
      "object": "tax_regime",
      "live": true,
      "taxes": [
        {
          "tax": "vat",
          "name": "IVA",
          "effect": "added",
          "rules": [
            {
              "rule": "general",
              "description": "IVA 21%",
              "treatment": "taxable",
              "rate": "21%",
              "authority_code": null,
              "legal_reference": "Ley 37/1992, artículo 90",
              "effective_from": "2012-09-01",
              "effective_until": null
            }
          ]
        }
      ]
    }
  ]
}
```