Customers

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 as customer.id.is_tax_exempt exempts a customer from everything. For exemptions backed by a certificate, see exemption certificates.

Where customers fit

Setup
└─ POST /tax/customers       send: email (+ is_tax_exempt)  → customer id
Checkout
└─ POST /tax/calculations    send: customer.id

Endpoints

Create a customerPOST/tax/customers Update a customerPOST/tax/customers/:id Retrieve a customerGET/tax/customers/:id List all customersGET/tax/customers Delete a customerDELETE/tax/customers/:id

The Customer object

Attributes

string

The ID of the customer, cust_….

string, value is "tax.customer"

String representing the object’s type.

string

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

string

The customer’s name.

string

The customer’s email. Unique across your customers.

boolean

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

The Customer object

{
  "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.

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.

To locate the customer by IP address instead of a street address, see IP-based tax resolution.

POST /tax/calculations

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
        }
      ]
    }
  }'

Exempt customer row

{
  "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.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

string

required

The customer’s email.

string

The customer’s name.

string

Your ID for the customer.

boolean

default:"false"

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

Returns

A Customer object.

POST /tax/customers

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"
  }'

Response

{
  "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.

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

string

required

The customer’s id or your reference_customer_id. No id_type needed.

string

The customer’s name.

string

The customer’s email.

boolean

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

string

Your ID for the customer.

Returns

The updated Customer object.

POST /tax/customers/:id

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"
  }'

Response

{
  "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.

string

required

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

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.

GET /tax/customers/:id

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.

string

The last_customer_id from the previous page.

Returns

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

GET /tax/customers

curl https://api.numeralhq.com/tax/customers \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2026-11-01'

Response

{
  "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.

string

required

The customer’s id.

Returns

The deleted object type and when it was deleted.

DELETE /tax/customers/:id

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'

Response

{
  "object": "tax.customer",
  "deleted_at": 1721782604
}

Errors

Errors return code, type, and message. Handle them by type. Full list in Error Codes.

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.

{
  "code": 400,
  "type": "DUPLICATE_CUSTOMER",
  "message": "Customer already exists."
}

{
  "code": 400,
  "type": "CUSTOMER_NOT_FOUND",
  "message": "Customer with id cust_9876543210abcdef not found"
}

Getting Started

API Reference

The Customer object

Attributes

Use a customer in a calculation

Create a customer

Parameters

Returns

Update a customer

Parameters

Returns

Retrieve a customer

Returns

List all customers

Returns

Delete a customer

Returns

Errors

​The Customer object

​Attributes

​Use a customer in a calculation

​Create a customer

​Parameters

​Returns

​Update a customer

​Parameters

​Returns

​Retrieve a customer

​Returns

​List all customers

​Returns

​Delete a customer

​Returns

​Errors

The Customer object

Attributes

Use a customer in a calculation

Create a customer

Parameters

Returns

Update a customer

Parameters

Returns

Retrieve a customer

Returns

List all customers

Returns

Delete a customer

Returns

Errors