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.

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 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.For a tax-exempt customer, the calculation returns no tax: tax_amount is 0 on every line, and total_tax_amount is 0.

POST /tax/calculations

curl https://api.numeralhq.com/tax/calculations \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2026-01-01' \
  -d '{
    "customer": {
      "id": "20506",
      "address": {
        "address_line_1": "3990 N County Rd 300 E",
        "address_city": "Danville",
        "address_province": "IN",
        "address_postal_code": "46122",
        "address_country": "US",
        "address_type": "shipping"
      }
    },
    "origin_address": {
      "address_line_1": "500 Church St",
      "address_city": "Nashville",
      "address_province": "TN",
      "address_postal_code": "37219",
      "address_country": "US"
    },
    "order_details": {
      "customer_currency_code": "USD",
      "tax_included_in_amount": false,
      "automatic_tax": "auto",
      "line_items": [
        {
          "reference_line_item_id": "line_123456789",
          "product_category": "GENERAL_MERCHANDISE",
          "amount": 200,
          "quantity": 2
        }
      ]
    }
  }'

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-01-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.

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

curl https://api.numeralhq.com/tax/customers/cust_6126acaf-7379-411a-8ada-00005bac0715 \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2026-01-01' \
  -d '{ "is_tax_exempt": true }'

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-01-01'

Delete a customer

Deletes a customer. Deleted customers 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-01-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

Delete a customer

Returns

Errors