Documentation
Browse documentation

Accounts

Inspect the account and invoicing configuration available to an API key.
View as Markdown

An account owns its customers, invoice series, API keys and invoices. Every account is isolated in either the live or test environment; resources cannot be shared between environments.

The account exposes the invoice, credit-note, and amendment series used when an operation omits an explicit series under default_series. It also controls invoice numbering for every series through invoice_numbering_scope.

default_payment_instructions is an ordered array of Payment Instruction IDs. When invoice issuance omits payment_terms.options, FiscalRail snapshots those instructions onto the invoice in that order. Set the array to [] to disable account defaults.

The live boolean identifies whether the account contains live or test data. Updating default_series replaces all three defaults atomically, so the object must include invoice, credit_note, and amendment. Use null for an optional default that is not configured.

account numbering uses one sequence per configured series. customer numbering appends the customer's invoice prefix to generated codes and keeps an independent sequence for each series and customer; customerless invoices continue on the base sequence. This changes future numbering only and applies to every series in the account.

An account API key has access to exactly one account, so the list endpoint currently returns one item. The collection shape leaves room for credentials that can access multiple accounts in the future.

The Account object

Properties
id string
Opaque identifier for an account.
object string
String identifying this as an Account object. Always account.
live boolean
True when the object belongs to the live environment; false for test data.
name string
Legal or trading name used when issuing invoices.
tax_id object
The account's current fiscal identifier and verification state.
Show child propertiesHide child properties
id string
Opaque identifier for a Tax ID.
object string
String identifying this as a Tax ID object. Always tax_id.
live boolean
True when the object belongs to the live environment; false for test data.
country string
ISO 3166-1 alpha-2 country associated with the tax ID. It must be compatible with the selected tax ID type.
type enum
FiscalRail's normalized fiscal identifier type.
Possible values
es_nif A Spanish NIF, including DNI and NIE identifiers for individuals and NIF identifiers for legal entities.
eu_vat A VAT identifier issued by an EU member state and checked for intra-EU registration.
local A domestic fiscal identifier that FiscalRail validates locally without querying a registry.
value string
The normalized fiscal identifier value.
owner object
The account or customer that owns the Tax ID.
Show child propertiesHide child properties
type enum
The kind of resource that owns the Tax ID.
Possible values
account The FiscalRail account whose legal entity uses this Tax ID.
customer The customer associated with this Tax ID.
id string
Account or customer ID, according to type.
verification object or null
The latest registry verification, or null when verification is unavailable.
Show child propertiesHide child properties
status enum
The current state of the latest registry-verification attempt.
Possible values
pending The registry check is queued, running or waiting to be retried.
completed The registry returned a result; inspect valid for the outcome.
failed FiscalRail could not complete the registry query; this is not evidence that the Tax ID is invalid.
valid boolean or null
The registry result, or null while pending or when verification failed.
completed_at string or null
When the verification attempt completed or failed, or null while it is pending.
email string or null
Contact email, or null when none was supplied.
phone string or null
Contact phone number, or null when none was supplied.
address object
Current business address.
Show child propertiesHide child properties
line_1 string
Primary street address.
line_2 string or null
Additional address information, or null when not supplied.
city string
City or locality.
postal_code string
Postal or ZIP code.
state string or null
State, province, or region, or null when not applicable.
country string
ISO 3166-1 alpha-2 country code.
tax_regime string
Tax regime key selected for this account.
timezone string
IANA timezone used to determine the account's local date.
invoice_locale enum
Default language used when rendering invoices.
Possible values
en English.
es Spanish.
invoice_numbering_scope enum
Account uses one sequence per configured series. Customer appends the customer's invoice prefix to generated codes and maintains an independent sequence for each series and customer; customerless invoices use the base sequence. Defaults to account.
Possible values
account
customer
default_series object
Series used by each invoice operation when no explicit series is supplied.
Show child propertiesHide child properties
invoice string
Series used when invoice issuance omits series.
credit_note object or null
Series used for credit notes created by amendments, or null if none is configured.
amendment object or null
Series used for replacement invoices created by amendments, or null if none is configured.
default_payment_instructions array of strings
Ordered payment instructions used when invoice issuance omits payment_terms.options. The first instruction is preferred.
created_at string
When the account was created.
updated_at string
When the account was last updated.
Account object 
{
  "id": "acct_14Vxtqg2nwvPR75TpsGH8N",
  "object": "account",
  "live": true,
  "name": "Example supplier",
  "tax_id": {
    "id": "tax_id_14Vxtqg2nwvPR75TpsGH8N",
    "object": "tax_id",
    "live": true,
    "country": "ES",
    "type": "es_nif",
    "value": "B02850360",
    "owner": {
      "type": "account",
      "id": "acct_14Vxtqg2nwvPR75TpsGH8N"
    },
    "verification": {
      "status": "completed",
      "valid": true,
      "completed_at": "2026-08-09T10:24:00Z"
    }
  },
  "email": "billing@example.com",
  "phone": "+34910000000",
  "address": {
    "line_1": "Gran Via 1",
    "line_2": null,
    "city": "Madrid",
    "postal_code": "28013",
    "state": "Madrid",
    "country": "ES"
  },
  "tax_regime": "es",
  "timezone": "Europe/Madrid",
  "invoice_locale": "es",
  "invoice_numbering_scope": "account",
  "default_series": {
    "invoice": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
    "credit_note": "inv_ser_14Vxtqj7HFs2pM9cXwL6eR",
    "amendment": "inv_ser_14Vxtqk8JGt3qN2dYxM7fS"
  },
  "default_payment_instructions": [
    "pay_ins_14Vxtqm9KHu4rP3eZyN8gT"
  ],
  "created_at": "2026-07-31T09:00:00Z",
  "updated_at": "2026-07-31T09:00:00Z"
}

Retrieve an account

GET/v1/accounts/{id}

Returns an account accessible to the API key and its current invoicing configuration.

Path parameters
id string required
The opaque ID of the account.
Responses

200 An Account object. JSON

Example request
import os

from fiscalrail import FiscalRail

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

account = client.accounts.retrieve(
    "acct_14Vxtqg2nwvPR75TpsGH8N",
)
Example response — 200 
{
  "id": "acct_14Vxtqg2nwvPR75TpsGH8N",
  "object": "account",
  "live": true,
  "name": "Example supplier",
  "tax_id": {
    "id": "tax_id_14Vxtqg2nwvPR75TpsGH8N",
    "object": "tax_id",
    "live": true,
    "country": "ES",
    "type": "es_nif",
    "value": "B02850360",
    "owner": {
      "type": "account",
      "id": "acct_14Vxtqg2nwvPR75TpsGH8N"
    },
    "verification": {
      "status": "completed",
      "valid": true,
      "completed_at": "2026-08-09T10:24:00Z"
    }
  },
  "email": "billing@example.com",
  "phone": "+34910000000",
  "address": {
    "line_1": "Gran Via 1",
    "line_2": null,
    "city": "Madrid",
    "postal_code": "28013",
    "state": "Madrid",
    "country": "ES"
  },
  "tax_regime": "es",
  "timezone": "Europe/Madrid",
  "invoice_locale": "es",
  "invoice_numbering_scope": "account",
  "default_series": {
    "invoice": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
    "credit_note": "inv_ser_14Vxtqj7HFs2pM9cXwL6eR",
    "amendment": "inv_ser_14Vxtqk8JGt3qN2dYxM7fS"
  },
  "default_payment_instructions": [
    "pay_ins_14Vxtqm9KHu4rP3eZyN8gT"
  ],
  "created_at": "2026-07-31T09:00:00Z",
  "updated_at": "2026-07-31T09:00:00Z"
}

Update account invoicing settings

PATCH/v1/accounts/{id}

Updates invoice numbering or atomically replaces account invoicing defaults.

Path parameters
id string required
The opaque ID of the account.
Request body
invoice_numbering_scope enum
Account uses one sequence per configured series. Customer appends the customer's invoice prefix to generated codes and maintains an independent sequence for each series and customer; customerless invoices use the base sequence. Defaults to account.
Possible values
account
customer
default_series object
Complete replacement for the account's three default series assignments.
Show child propertiesHide child properties
invoice string required
Series used when invoice issuance omits series.
credit_note object or null required
Series used for credit notes created by amendments, or null if none is configured.
amendment object or null required
Series used for replacement invoices created by amendments, or null if none is configured.
default_payment_instructions array of strings
Complete ordered replacement for the account's default payment instructions. Every instruction must belong to the account.
Responses

200 The updated Account object. JSON

Example request
import os

from fiscalrail import FiscalRail

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

account = client.accounts.update(
    "acct_14Vxtqg2nwvPR75TpsGH8N",
    invoice_numbering_scope="customer",
    default_series={
        "invoice": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
        "credit_note": "inv_ser_14Vxtqj7HFs2pM9cXwL6eR",
        "amendment": "inv_ser_14Vxtqk8JGt3qN2dYxM7fS",
    },
    default_payment_instructions=[
        "pay_ins_14Vxtqm9KHu4rP3eZyN8gT",
    ],
)
Example response — 200 
{
  "id": "acct_14Vxtqg2nwvPR75TpsGH8N",
  "object": "account",
  "live": true,
  "name": "Example supplier",
  "tax_id": {
    "id": "tax_id_14Vxtqg2nwvPR75TpsGH8N",
    "object": "tax_id",
    "live": true,
    "country": "ES",
    "type": "es_nif",
    "value": "B02850360",
    "owner": {
      "type": "account",
      "id": "acct_14Vxtqg2nwvPR75TpsGH8N"
    },
    "verification": {
      "status": "completed",
      "valid": true,
      "completed_at": "2026-08-09T10:24:00Z"
    }
  },
  "email": "billing@example.com",
  "phone": "+34910000000",
  "address": {
    "line_1": "Gran Via 1",
    "line_2": null,
    "city": "Madrid",
    "postal_code": "28013",
    "state": "Madrid",
    "country": "ES"
  },
  "tax_regime": "es",
  "timezone": "Europe/Madrid",
  "invoice_locale": "es",
  "invoice_numbering_scope": "account",
  "default_series": {
    "invoice": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
    "credit_note": "inv_ser_14Vxtqj7HFs2pM9cXwL6eR",
    "amendment": "inv_ser_14Vxtqk8JGt3qN2dYxM7fS"
  },
  "default_payment_instructions": [
    "pay_ins_14Vxtqm9KHu4rP3eZyN8gT"
  ],
  "created_at": "2026-07-31T09:00:00Z",
  "updated_at": "2026-07-31T09:00:00Z"
}

List accounts

GET/v1/accounts

Returns the accounts accessible to the API key. Account keys currently return exactly one account.

Responses

200 A list of Account objects. JSON

Example request
import os

from fiscalrail import FiscalRail

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

accounts = client.accounts.list()
Example response — 200 
{
  "object": "list",
  "has_more": null,
  "data": [
    {
      "id": "acct_14Vxtqg2nwvPR75TpsGH8N",
      "object": "account",
      "live": true,
      "name": "Example supplier",
      "tax_id": {
        "id": "tax_id_14Vxtqg2nwvPR75TpsGH8N",
        "object": "tax_id",
        "live": true,
        "country": "ES",
        "type": "es_nif",
        "value": "B02850360",
        "owner": {
          "type": "account",
          "id": "acct_14Vxtqg2nwvPR75TpsGH8N"
        },
        "verification": {
          "status": "completed",
          "valid": true,
          "completed_at": "2026-08-09T10:24:00Z"
        }
      },
      "email": "billing@example.com",
      "phone": "+34910000000",
      "address": {
        "line_1": "Gran Via 1",
        "line_2": null,
        "city": "Madrid",
        "postal_code": "28013",
        "state": "Madrid",
        "country": "ES"
      },
      "tax_regime": "es",
      "timezone": "Europe/Madrid",
      "invoice_locale": "es",
      "invoice_numbering_scope": "account",
      "default_series": {
        "invoice": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
        "credit_note": "inv_ser_14Vxtqj7HFs2pM9cXwL6eR",
        "amendment": "inv_ser_14Vxtqk8JGt3qN2dYxM7fS"
      },
      "default_payment_instructions": [
        "pay_ins_14Vxtqm9KHu4rP3eZyN8gT"
      ],
      "created_at": "2026-07-31T09:00:00Z",
      "updated_at": "2026-07-31T09:00:00Z"
    }
  ]
}