> ## Documentation Index
> Fetch the complete documentation index at: https://docs.numeral.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customers

> Store your buyers and mark them tax exempt

A customer is one of your buyers. Create one to keep track of repeat purchases, or to mark a buyer as tax exempt. Exempt buyers are often wholesalers, religious groups, or educational institutions. Pass the customer on a [calculation](https://docs.numeral.com/v2026-11-01/objects/calculations.md) as `customer.id`.

`is_tax_exempt` exempts a customer from everything. For exemptions backed by a certificate, see [exemption certificates](https://docs.numeral.com/v2026-11-01/objects/exemption-certificates.md).

```text Where customers fit theme={null}
Setup
└─ POST /tax/customers       send: email (+ is_tax_exempt)  → customer id
Checkout
└─ POST /tax/calculations    send: customer.id
```

Endpoints
[Create a customerPOST/tax/customers](#create-a-customer)
[Update a customerPOST/tax/customers/:id](#update-a-customer)
[Retrieve a customerGET/tax/customers/:id](#retrieve-a-customer)
[List all customersGET/tax/customers](#list-all-customers)
[Delete a customerDELETE/tax/customers/:id](#delete-a-customer)

## The Customer object

### Attributes

**id** `string`

The ID of the customer, `cust_…`.

**object** `string, value is "tax.customer"`

String representing the object's type.

**reference\_customer\_id** `string`

Your ID for the customer. Unique across your customers. You can use it instead of `id` to refer to the customer.

**name** `string`

The customer's name.

**email** `string`

The customer's email. Unique across your customers.

**is\_tax\_exempt** `boolean`

If `true`, every calculation for this customer returns 0 tax. Defaults to `false`.

```json The Customer object theme={null}
{
  "id": "cust_6126acaf-7379-411a-8ada-00005bac0715",
  "object": "tax.customer",
  "reference_customer_id": "20506",
  "name": "Customer Name",
  "email": "customer@example.com",
  "is_tax_exempt": true
}
```

## Use a customer in a calculation

Send the customer's `id` or your `reference_customer_id` as `customer.id` on a [calculation](https://docs.numeral.com/v2026-11-01/objects/calculations.md#create-a-calculation).

* The customer must already exist. Otherwise the calculation returns `CUSTOMER_NOT_FOUND` (404), unless you also send `default_customer_type`.
* For a tax-exempt customer, every row in `tax_jurisdictions` has 0 tax and `note: "no_collection_exempt_customer"`. See [Notes](https://docs.numeral.com/v2026-11-01/objects/calculations.md#notes).

To locate the customer by IP address instead of a street address, see [IP-based tax resolution](https://docs.numeral.com/v2026-11-01/objects/calculations.md#ip-based-tax-resolution).

```bash POST /tax/calculations theme={null}
curl https://api.numeralhq.com/tax/calculations \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2026-11-01' \
  -d '{
    "customer": {
      "id": "20506",
      "address": {
        "address_line_1": "233 S Wacker Dr",
        "address_city": "Chicago",
        "address_province": "IL",
        "address_postal_code": "60606",
        "address_country": "US",
        "address_type": "shipping"
      }
    },
    "origin_address": {
      "address_line_1": "3990 N County Rd 300 E",
      "address_city": "Danville",
      "address_province": "IN",
      "address_postal_code": "46122",
      "address_country": "US"
    },
    "order_details": {
      "customer_currency_code": "USD",
      "tax_included_in_amount": false,
      "automatic_tax": "auto",
      "line_items": [
        {
          "reference_line_item_id": "widget",
          "product_category": "GENERAL_MERCHANDISE",
          "amount": 5000,
          "quantity": 2
        }
      ]
    }
  }'
```

```json Exempt customer row theme={null}
{
  "tax_rate": 0,
  "tax_due_decimal": 0,
  "fee_amount": 0,
  "rate_type": "Sales Tax",
  "tax_authority_name": "State Tax",
  "tax_authority_type": "",
  "tax_type": "SALES",
  "note": "no_collection_exempt_customer"
}
```

## Create a customer

Creates a customer. Only `email` is required. [Try it in the API reference](https://docs.numeral.com/api-reference/v2026-11-01/endpoint/customers).

The response has a Numeral `id`. If you sent a `reference_customer_id`, you can use either one to refer to the customer later.

### Parameters

**email** `string` *required*

The customer's email.

**name** `string`

The customer's name.

**reference\_customer\_id** `string`

Your ID for the customer.

**is\_tax\_exempt** `boolean` (default: false)

If `true`, every calculation for this customer returns 0 tax.

### Returns

A [Customer object](#the-customer-object).

```bash POST /tax/customers theme={null}
curl https://api.numeralhq.com/tax/customers \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2026-11-01' \
  -d '{
    "name": "Customer Name",
    "email": "customer@example.com",
    "is_tax_exempt": true,
    "reference_customer_id": "20506"
  }'
```

```json Response theme={null}
{
  "id": "cust_6126acaf-7379-411a-8ada-00005bac0715",
  "object": "tax.customer",
  "reference_customer_id": "20506",
  "name": "Customer Name",
  "email": "customer@example.com",
  "is_tax_exempt": true
}
```

## Update a customer

Updates a customer's `name`, `email`, `is_tax_exempt`, or `reference_customer_id`. Send at least one. Fields you leave out stay as they are. [Try it in the API reference](https://docs.numeral.com/api-reference/v2026-11-01/endpoint/update_customer).

* `email` and `reference_customer_id` must be unique across your customers. If another customer already uses the new value, the request fails with `DUPLICATE_CUSTOMER`.
* `email` must be a valid email address, or the request fails with `INVALID_EMAIL`.
* Setting `is_tax_exempt` to `true` makes every future calculation for this customer return 0 tax. Setting it to `false` removes the exemption.
* If every value you send matches what's stored, nothing changes and the current customer is returned with a `200`.
* Deleted customers can't be updated. The request fails with `CUSTOMER_NOT_FOUND`.
* If the customer's buyer record was deleted in Numeral's Exemption Certificate Manager, setting `is_tax_exempt` to `true` fails with `INVALID_REQUEST`.

### Parameters

**customer\_id** `string` *required*

The customer's `id` or your `reference_customer_id`. No `id_type` needed.

**name** `string`

The customer's name.

**email** `string`

The customer's email.

**is\_tax\_exempt** `boolean`

`true` to exempt the customer from tax, `false` to remove the exemption.

**reference\_customer\_id** `string`

Your ID for the customer.

### Returns

The updated [Customer object](#the-customer-object).

```bash POST /tax/customers/:id theme={null}
curl https://api.numeralhq.com/tax/customers/20506 \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2026-11-01' \
  -d '{
    "name": "New Customer Name",
    "email": "new.email@example.com"
  }'
```

```json Response theme={null}
{
  "id": "cust_6126acaf-7379-411a-8ada-00005bac0715",
  "object": "tax.customer",
  "reference_customer_id": "20506",
  "name": "New Customer Name",
  "email": "new.email@example.com",
  "is_tax_exempt": true
}
```

## Retrieve a customer

Returns a customer by its `id` or your `reference_customer_id`. [Try it in the API reference](https://docs.numeral.com/api-reference/v2026-11-01/endpoint/get_customer).

**customer\_id** `string` *required*

The customer's `id`, or your `reference_customer_id` with `id_type=reference_customer_id`.

**id\_type** `enum` (default: id)

`id` to look up by the Numeral customer ID. `reference_customer_id` to look up by your own ID.

### Returns

A [Customer object](#the-customer-object).

```bash GET /tax/customers/:id theme={null}
curl 'https://api.numeralhq.com/tax/customers/20506?id_type=reference_customer_id' \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2026-11-01'
```

## List all customers

Returns your customers, one page at a time. Deleted customers aren't included. [Try it in the API reference](https://docs.numeral.com/api-reference/v2026-11-01/endpoint/list_customers).

**cursor** `string`

The `last_customer_id` from the previous page.

### Returns

An object with a `customers` array of [Customer objects](#the-customer-object), `has_more` (whether there are more to fetch), and `last_customer_id` (the cursor for the next page).

```bash GET /tax/customers theme={null}
curl https://api.numeralhq.com/tax/customers \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2026-11-01'
```

```json Response theme={null}
{
  "customers": [
    {
      "id": "cust_6126acaf-7379-411a-8ada-00005bac0715",
      "object": "tax.customer",
      "reference_customer_id": "20506",
      "name": "Customer Name",
      "email": "customer@example.com",
      "is_tax_exempt": false
    },
    {
      "id": "cust_9876543210abcdef",
      "object": "tax.customer",
      "reference_customer_id": "20507",
      "name": "Tax Exempt Customer",
      "email": "exempt@example.com",
      "is_tax_exempt": true
    }
  ],
  "has_more": true,
  "last_customer_id": "cust_9876543210abcdef"
}
```

## Delete a customer

Deletes a customer. Deleted customers don't appear in lists and can't be updated. [Try it in the API reference](https://docs.numeral.com/api-reference/v2026-11-01/endpoint/delete_customer).

**customer\_id** `string` *required*

The customer's `id`.

### Returns

The deleted object type and when it was deleted.

```bash DELETE /tax/customers/:id theme={null}
curl -X DELETE https://api.numeralhq.com/tax/customers/cust_6126acaf-7379-411a-8ada-00005bac0715 \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2026-11-01'
```

```json Response theme={null}
{
  "object": "tax.customer",
  "deleted_at": 1721782604
}
```

## Errors

Errors return `code`, `type`, and `message`. Handle them by `type`. Full list in [Error Codes](https://docs.numeral.com/api-reference/v2026-11-01/error-codes.md).

| HTTP | `type` | When |
| - | - | - |
| 400 | `MISSING_FIELD` | A required field is missing, e.g. `email` on create. |
| 400 | `INCORRECT_TYPE` | A field has the wrong type. |
| 400 | `INVALID_EMAIL` | `email` isn't a valid email address. |
| 400 | `INVALID_REQUEST` | An update sent no field to change, or set `is_tax_exempt` to `true` for a customer whose buyer record was deleted in Exemption Certificate Manager. |
| 400 | `DUPLICATE_CUSTOMER` | Another customer already uses this `reference_customer_id`, or on update, this `email`. |
| 400 | `CUSTOMER_NOT_FOUND` | An update targeted a customer that doesn't exist or was deleted. |

```json DUPLICATE_CUSTOMER theme={null}
{
  "code": 400,
  "type": "DUPLICATE_CUSTOMER",
  "message": "Customer already exists."
}
```

```json CUSTOMER_NOT_FOUND theme={null}
{
  "code": 400,
  "type": "CUSTOMER_NOT_FOUND",
  "message": "Customer with id cust_9876543210abcdef not found"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.