# Customers

Create and manage the customers associated with ordinary invoices.

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`

Type: `string`

Opaque identifier for the customer.

#### `object`

Type: `string`

String identifying this as a Customer object. Always `customer`.

#### `live`

Type: `boolean`

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

#### `name`

Type: `string`

The customer's legal or trading name.

#### `tax_id`

Type: `object`

The customer's current fiscal identifier and verification state.

##### `tax_id.id`

Type: `string`

Opaque identifier for a Tax ID.

##### `tax_id.object`

Type: `string`

String identifying this as a Tax ID object. Always `tax_id`.

##### `tax_id.live`

Type: `boolean`

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

##### `tax_id.country`

Type: `string`

ISO 3166-1 alpha-2 country associated with the tax ID. It must be compatible with the selected tax ID type.

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

##### `tax_id.value`

Type: `string`

The normalized fiscal identifier value.

##### `tax_id.owner`

Type: `object`

The account or customer that owns the Tax ID.

###### `tax_id.owner.type`

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.

###### `tax_id.owner.id`

Type: `string`

Account or customer ID, according to `type`.


##### `tax_id.verification`

Type: `object or null`

The latest registry verification, or null when verification is unavailable.

###### `tax_id.verification.status`

Type: `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.

###### `tax_id.verification.valid`

Type: `boolean or null`

The registry result, or null while pending or when verification failed.

###### `tax_id.verification.completed_at`

Type: `string or null`

When the verification attempt completed or failed, or null while it is pending.



#### `email`

Type: `string or null`

The customer's billing email, or null when none was supplied.

#### `phone`

Type: `string or null`

The customer's phone number, or null when none was supplied.

#### `address`

Type: `object or null`

The customer's current billing address, or null when none was supplied.

##### `address.line_1`

Type: `string`

Primary street address.

##### `address.line_2`

Type: `string or null`

Additional address information, or null when not supplied.

##### `address.city`

Type: `string`

City or locality.

##### `address.postal_code`

Type: `string`

Postal or ZIP code.

##### `address.state`

Type: `string or null`

State, province, or region, or null when not applicable.

##### `address.country`

Type: `string`

ISO 3166-1 alpha-2 country code.


#### `created_at`

Type: `string`

When the customer was created, in ISO 8601 format.

#### `updated_at`

Type: `string`

When the customer was last updated, in ISO 8601 format.


### Example

```json
{
  "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`

Type: `string` — required

The customer's legal or trading name.

#### `tax_id`

Type: `object` — required

The customer's fiscal identifier.

##### `tax_id.country`

Type: `string` — required

ISO 3166-1 alpha-2 country associated with the tax ID.

##### `tax_id.type`

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.

##### `tax_id.value`

Type: `string` — required

The fiscal identifier value.


#### `email`

Type: `string or null`

The customer's billing email.

#### `phone`

Type: `string or null`

The customer's phone number.

#### `address`

Type: `object or null`

The customer's billing address. Omit it or use null when it is not yet known.

##### `address.line_1`

Type: `string` — required

Primary street address.

##### `address.line_2`

Type: `string or null`

Additional address information.

##### `address.city`

Type: `string` — required

City or locality.

##### `address.postal_code`

Type: `string` — required

Postal or ZIP code.

##### `address.state`

Type: `string or null`

State, province, or region.

##### `address.country`

Type: `string` — required

ISO 3166-1 alpha-2 country code.



### Responses

- `201` — [A Customer object.](#the-customer-object) Formats: JSON.

### Example request

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

```json
{
  "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`

Type: `string` — required

The opaque ID of the customer.


### Responses

- `200` — [A Customer object.](#the-customer-object) Formats: JSON.

### Example request

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

### Example response — 200

```json
{
  "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`

Type: `string` — required

The opaque ID of the customer.


### Request body

#### `name`

Type: `string or null`

A new legal or trading name. Null values are rejected.

#### `tax_id`

Type: `object`

A replacement fiscal identifier.

##### `tax_id.country`

Type: `string` — required

ISO 3166-1 alpha-2 country associated with the tax ID.

##### `tax_id.type`

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.

##### `tax_id.value`

Type: `string` — required

The fiscal identifier value.


#### `email`

Type: `string or null`

A new billing email, or null to clear it.

#### `phone`

Type: `string or null`

A new phone number, or null to clear it.

#### `address`

Type: `object or null`

Address fields to update; omitted fields remain unchanged. Use null to clear the address.

##### `address.line_1`

Type: `string or null`

A new primary street address. Null values are rejected.

##### `address.line_2`

Type: `string or null`

New additional address information, or null to clear it.

##### `address.city`

Type: `string or null`

A new city or locality. Null values are rejected.

##### `address.postal_code`

Type: `string or null`

A new postal or ZIP code. Null values are rejected.

##### `address.state`

Type: `string or null`

A new state, province, or region, or null to clear it.

##### `address.country`

Type: `string or null`

A new ISO 3166-1 alpha-2 country code. Null values are rejected.



### Responses

- `200` — [A Customer object.](#the-customer-object) Formats: JSON.

### Example request

```bash
curl --request PATCH \
  'https://api.fiscalrail.com/v1/customers/cus_14Vxtqg6oXpAY5WdWoq4wW' \
  --header "Authorization: Bearer ak_test_..." \
  --json '{
  "address": {
    "city": "Barcelona"
  }
}'
```

### Example response — 200

```json
{
  "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`

Type: `string` — required

The opaque ID of the customer.


### Responses

- `204` — The customer was deleted. The response has no body.

### Example request

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

Type: `string`

Substring to search for in customer ID, name, tax ID, or email. `%` and `_` are treated literally.

#### `country`

Type: `string`

Exact country filter. The supplied value is uppercased.

#### `limit`

Type: `integer`

Maximum number of resources to return. Defaults to `25`.

#### `starting_after`

Type: `string`

Return customers older than this customer ID. Cannot be combined with `ending_before`.

#### `ending_before`

Type: `string`

Return customers newer than this customer ID. Cannot be combined with `starting_after`.


### Responses

- `200` — [A list of Customer objects.](#the-customer-object) Formats: JSON.

### Example request

```bash
curl --request GET \
  'https://api.fiscalrail.com/v1/customers?q=Acme&country=ES&limit=25' \
  --header "Authorization: Bearer ak_test_..."
```

### Example response — 200

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