Documentation
Browse documentation

Customers

Create and manage the customers associated with ordinary invoices.
View as Markdown

Customers hold the current identity and contact details of the people and businesses you invoice. Issued invoices keep their own immutable customer snapshot, so later customer updates do not rewrite invoice history.

An address is optional while creating or maintaining a customer. If supplied, it must be complete. Global accounts may issue invoices to customers without an address; Spanish accounts require the customer's address when issuing an ordinary invoice.

The Customer object

Properties
id string
Opaque identifier for the customer.
object string
String identifying this as a Customer object. Always customer.
live boolean
True when the object belongs to the live environment; false for test data.
name string
The customer's legal or trading name.
tax_id object
The customer'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
The customer's billing email, or null when none was supplied.
phone string or null
The customer's phone number, or null when none was supplied.
address object or null
The customer's current billing address, or null when none was supplied.
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.
created_at string
When the customer was created, in ISO 8601 format.
updated_at string
When the customer was last updated, in ISO 8601 format.
Customer object 
{
  "id": "cus_14Vxtqg6oXpAY5WdWoq4wW",
  "object": "customer",
  "live": true,
  "name": "Acme SL",
  "tax_id": {
    "id": "tax_id_14Vxtqg6oXpAY5WdWoq4wW",
    "object": "tax_id",
    "live": true,
    "country": "ES",
    "type": "es_nif",
    "value": "B87654323",
    "owner": {
      "type": "customer",
      "id": "cus_14Vxtqg6oXpAY5WdWoq4wW"
    },
    "verification": null
  },
  "email": "billing@example.com",
  "phone": "+34910000000",
  "address": {
    "line_1": "Gran Via 1",
    "line_2": null,
    "city": "Madrid",
    "postal_code": "28013",
    "state": "Madrid",
    "country": "ES"
  },
  "created_at": "2026-07-31T09:30:00Z",
  "updated_at": "2026-07-31T09:30:00Z"
}

Create a customer

POST/v1/customers

Creates a customer from its current legal identity, tax ID, and contact details.

Request body
name string required
The customer's legal or trading name.
tax_id object required
The customer's fiscal identifier.
Show child propertiesHide child properties
country string required
ISO 3166-1 alpha-2 country associated with the tax ID.
type enum required
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 required
The fiscal identifier value.
email string or null
The customer's billing email.
phone string or null
The customer's phone number.
address object or null
The customer's billing address. Omit it or use null when it is not yet known.
Show child propertiesHide child properties
line_1 string required
Primary street address.
line_2 string or null
Additional address information.
city string required
City or locality.
postal_code string required
Postal or ZIP code.
state string or null
State, province, or region.
country string required
ISO 3166-1 alpha-2 country code.
Responses

201 A Customer object. JSON

Example request
curl --request POST \
  'https://api.fiscalrail.com/v1/customers' \
  --header "Authorization: Bearer ak_test_..." \
  --json '{
  "name": "Acme SL",
  "tax_id": {
    "country": "ES",
    "type": "es_nif",
    "value": "B87654323"
  },
  "email": "billing@example.com",
  "phone": "+34910000000",
  "address": {
    "line_1": "Gran Via 1",
    "city": "Madrid",
    "postal_code": "28013",
    "state": "Madrid",
    "country": "ES"
  }
}'
Example response — 201 
{
  "id": "cus_14Vxtqg6oXpAY5WdWoq4wW",
  "object": "customer",
  "live": true,
  "name": "Acme SL",
  "tax_id": {
    "id": "tax_id_14Vxtqg6oXpAY5WdWoq4wW",
    "object": "tax_id",
    "live": true,
    "country": "ES",
    "type": "es_nif",
    "value": "B87654323",
    "owner": {
      "type": "customer",
      "id": "cus_14Vxtqg6oXpAY5WdWoq4wW"
    },
    "verification": null
  },
  "email": "billing@example.com",
  "phone": "+34910000000",
  "address": {
    "line_1": "Gran Via 1",
    "line_2": null,
    "city": "Madrid",
    "postal_code": "28013",
    "state": "Madrid",
    "country": "ES"
  },
  "created_at": "2026-07-31T09:30:00Z",
  "updated_at": "2026-07-31T09:30:00Z"
}

Retrieve a customer

GET/v1/customers/{id}

Returns a customer by its opaque ID, including its current tax ID and contact details.

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

200 A Customer object. JSON

Example request
curl --request GET \
  'https://api.fiscalrail.com/v1/customers/cus_14Vxtqg6oXpAY5WdWoq4wW' \
  --header "Authorization: Bearer ak_test_..."
Example response — 200 
{
  "id": "cus_14Vxtqg6oXpAY5WdWoq4wW",
  "object": "customer",
  "live": true,
  "name": "Acme SL",
  "tax_id": {
    "id": "tax_id_14Vxtqg6oXpAY5WdWoq4wW",
    "object": "tax_id",
    "live": true,
    "country": "ES",
    "type": "es_nif",
    "value": "B87654323",
    "owner": {
      "type": "customer",
      "id": "cus_14Vxtqg6oXpAY5WdWoq4wW"
    },
    "verification": null
  },
  "email": "billing@example.com",
  "phone": "+34910000000",
  "address": {
    "line_1": "Gran Via 1",
    "line_2": null,
    "city": "Madrid",
    "postal_code": "28013",
    "state": "Madrid",
    "country": "ES"
  },
  "created_at": "2026-07-31T09:30:00Z",
  "updated_at": "2026-07-31T09:30:00Z"
}

Update a customer

PATCH/v1/customers/{id}

Partially updates the supplied fields. Omitted top-level and address
fields are left unchanged.

Path parameters
id string required
The opaque ID of the customer.
Request body
name string or null
A new legal or trading name. Null values are rejected.
tax_id object
A replacement fiscal identifier.
Show child propertiesHide child properties
country string required
ISO 3166-1 alpha-2 country associated with the tax ID.
type enum required
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 required
The fiscal identifier value.
email string or null
A new billing email, or null to clear it.
phone string or null
A new phone number, or null to clear it.
address object or null
Address fields to update; omitted fields remain unchanged. Use null to clear the address.
Show child propertiesHide child properties
line_1 string or null
A new primary street address. Null values are rejected.
line_2 string or null
New additional address information, or null to clear it.
city string or null
A new city or locality. Null values are rejected.
postal_code string or null
A new postal or ZIP code. Null values are rejected.
state string or null
A new state, province, or region, or null to clear it.
country string or null
A new ISO 3166-1 alpha-2 country code. Null values are rejected.
Responses

200 A Customer object. JSON

Example request
curl --request PATCH \
  'https://api.fiscalrail.com/v1/customers/cus_14Vxtqg6oXpAY5WdWoq4wW' \
  --header "Authorization: Bearer ak_test_..." \
  --json '{
  "address": {
    "city": "Barcelona"
  }
}'
Example response — 200 
{
  "id": "cus_14Vxtqg6oXpAY5WdWoq4wW",
  "object": "customer",
  "live": true,
  "name": "Acme SL",
  "tax_id": {
    "id": "tax_id_14Vxtqg6oXpAY5WdWoq4wW",
    "object": "tax_id",
    "live": true,
    "country": "ES",
    "type": "es_nif",
    "value": "B87654323",
    "owner": {
      "type": "customer",
      "id": "cus_14Vxtqg6oXpAY5WdWoq4wW"
    },
    "verification": null
  },
  "email": "billing@example.com",
  "phone": "+34910000000",
  "address": {
    "line_1": "Gran Via 1",
    "line_2": null,
    "city": "Madrid",
    "postal_code": "28013",
    "state": "Madrid",
    "country": "ES"
  },
  "created_at": "2026-07-31T09:30:00Z",
  "updated_at": "2026-07-31T09:30:00Z"
}

Delete a customer

DELETE/v1/customers/{id}

Deletes a customer that has not been used by an invoice. A customer
referenced by an invoice cannot be deleted.

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

204 The customer was deleted. The response has no body.

Example request
curl --request DELETE \
  'https://api.fiscalrail.com/v1/customers/cus_14Vxtqg6oXpAY5WdWoq4wW' \
  --header "Authorization: Bearer ak_test_..."

List customers

GET/v1/customers

Returns the account's customers in reverse chronological ID order.
Use only one cursor parameter at a time. starting_after moves toward
older customers; ending_before moves toward newer customers.

Query parameters
q string
Substring to search for in customer ID, name, tax ID, or email. % and _ are treated literally.
country string
Exact country filter. The supplied value is uppercased.
limit integer
Maximum number of resources to return. Defaults to 25.
starting_after string
Return customers older than this customer ID. Cannot be combined with ending_before.
ending_before string
Return customers newer than this customer ID. Cannot be combined with starting_after.
Responses

200 A list of Customer objects. JSON

Example request
curl --request GET \
  'https://api.fiscalrail.com/v1/customers?q=Acme&country=ES&limit=25' \
  --header "Authorization: Bearer ak_test_..."
Example response — 200 
{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "id": "cus_14Vxtqg6oXpAY5WdWoq4wW",
      "object": "customer",
      "live": true,
      "name": "Acme SL",
      "tax_id": {
        "id": "tax_id_14Vxtqg6oXpAY5WdWoq4wW",
        "object": "tax_id",
        "live": true,
        "country": "ES",
        "type": "es_nif",
        "value": "B87654323",
        "owner": {
          "type": "customer",
          "id": "cus_14Vxtqg6oXpAY5WdWoq4wW"
        },
        "verification": null
      },
      "email": "billing@example.com",
      "phone": "+34910000000",
      "address": {
        "line_1": "Gran Via 1",
        "line_2": null,
        "city": "Madrid",
        "postal_code": "28013",
        "state": "Madrid",
        "country": "ES"
      },
      "created_at": "2026-07-31T09:30:00Z",
      "updated_at": "2026-07-31T09:30:00Z"
    }
  ]
}