Documentation
Browse documentation

Tax regimes

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

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 or Spain tax regime guide.

The Tax Regime object

Properties
id 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 string
String identifying this as a Tax Regime object. Always tax_regime.
live boolean
True when the object belongs to the live environment; false for test data.
taxes array of objects
Structured taxes supported by the regime. Empty when the regime accepts custom taxes.
Show child propertiesHide child properties
tax string
Stable tax identifier supplied as taxes[].tax during invoice issuance.
name string
Human-readable tax name.
effect 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.
rules array of objects
Rate and treatment versions supported for this tax.
Show child propertiesHide child properties
rule string
Stable rule identifier supplied as taxes[].rule during invoice issuance.
description string
Human-readable description used on invoices.
treatment 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.
rate string or null
Percentage including %, or null when a percentage does not apply.
authority_code string or null
Corresponding tax-authority code when one applies.
legal_reference string or null
Source provision supporting this rule when recorded.
effective_from string
First date on which this rule version applies.
effective_until string or null
Last date on which this rule version applies, or null when open-ended.
Tax Regime object 
{
  "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 string required
Tax regime key, such as es.
Responses

200 A Tax Regime object. JSON

Example request
curl --request GET \
  'https://api.fiscalrail.com/v1/tax-regimes/example' \
  --header "Authorization: Bearer ak_test_..."
Example response — 200 
{
  "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. JSON

Example request
curl --request GET \
  'https://api.fiscalrail.com/v1/tax-regimes' \
  --header "Authorization: Bearer ak_test_..."
Example response — 200 
{
  "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
            }
          ]
        }
      ]
    }
  ]
}