curl -X POST https://api.numeralhq.com/tax/customers/cust_6126acaf-7379-411a-8ada-00005bac0715 \
-H "Authorization: Bearer sk_test_xxx" \
-H "X-API-Version: 2025-05-12" \
-H "Content-Type: application/json" \
-d '{
"is_tax_exempt": true
}'
curl -X POST https://api.numeralhq.com/tax/customers/20506 \
-H "Authorization: Bearer sk_test_xxx" \
-H "X-API-Version: 2025-05-12" \
-H "Content-Type: application/json" \
-d '{
"name": "New Customer Name",
"email": "new.email@example.com"
}'
{
"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
}
{
"error": {
"error_code": "duplicate_customer",
"error_message": "Customer already exists.",
"error_meta": {
"id": "cust_1234567890abcdef",
"reference_customer_id": "20507",
"email": "new.email@example.com"
}
}
}
{
"error": {
"error_code": "customer_not_found",
"error_message": "Customer with id cust_9876543210abcdef not found"
}
}
Customers
Update Customer
Update an existing customer’s information
POST
/
tax
/
customers
/
{customer_id}
curl -X POST https://api.numeralhq.com/tax/customers/cust_6126acaf-7379-411a-8ada-00005bac0715 \
-H "Authorization: Bearer sk_test_xxx" \
-H "X-API-Version: 2025-05-12" \
-H "Content-Type: application/json" \
-d '{
"is_tax_exempt": true
}'
curl -X POST https://api.numeralhq.com/tax/customers/20506 \
-H "Authorization: Bearer sk_test_xxx" \
-H "X-API-Version: 2025-05-12" \
-H "Content-Type: application/json" \
-d '{
"name": "New Customer Name",
"email": "new.email@example.com"
}'
{
"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
}
{
"error": {
"error_code": "duplicate_customer",
"error_message": "Customer already exists.",
"error_meta": {
"id": "cust_1234567890abcdef",
"reference_customer_id": "20507",
"email": "new.email@example.com"
}
}
}
{
"error": {
"error_code": "customer_not_found",
"error_message": "Customer with id cust_9876543210abcdef not found"
}
}
Update Customer Endpoint (2025-05-12)
Update an existing customer’sname, email, is_tax_exempt status, or reference_customer_id. All fields are optional, but at least one must be provided. Only the fields you include are changed; everything else is left as is.
Remember to include the
X-API-Version: 2025-05-12 header in your request to use this API version.The
customer_id path parameter accepts either the Numeral customer ID (cust_xxx) or your own reference_customer_id. No id_type query parameter is needed.Behavior
emailandreference_customer_idmust be unique across your customers. If another customer already uses the new value, the request fails withduplicate_customer. The conflicting customer’sid,reference_customer_id, andemailare returned inerror_meta.emailmust be a valid email address, otherwise the request fails withinvalid_email.- Setting
is_tax_exempttotruemeans all futurePOST /tax/calculationsfor this customer return $0 in tax owed. Setting it tofalseremoves the exemption. - If every provided value matches what is already stored, nothing is written and the current customer is returned with a
200. - Deleted customers cannot be updated. The request fails with
customer_not_found. - If the customer’s buyer record has been deleted in Numeral’s Exemption Certificate Manager, setting
is_tax_exempttotrueis rejected withinvalid_request.
curl -X POST https://api.numeralhq.com/tax/customers/cust_6126acaf-7379-411a-8ada-00005bac0715 \
-H "Authorization: Bearer sk_test_xxx" \
-H "X-API-Version: 2025-05-12" \
-H "Content-Type: application/json" \
-d '{
"is_tax_exempt": true
}'
curl -X POST https://api.numeralhq.com/tax/customers/20506 \
-H "Authorization: Bearer sk_test_xxx" \
-H "X-API-Version: 2025-05-12" \
-H "Content-Type: application/json" \
-d '{
"name": "New Customer Name",
"email": "new.email@example.com"
}'
{
"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
}
{
"error": {
"error_code": "duplicate_customer",
"error_message": "Customer already exists.",
"error_meta": {
"id": "cust_1234567890abcdef",
"reference_customer_id": "20507",
"email": "new.email@example.com"
}
}
}
{
"error": {
"error_code": "customer_not_found",
"error_message": "Customer with id cust_9876543210abcdef not found"
}
}
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
The Numeral customer ID (cust_xxx) or your reference_customer_id. Either identifier is accepted; no id_type query parameter is needed.
Body
application/json
Request body for updating a customer. All fields are optional, but at least one must be provided.
The customer's name
Example:
"New Customer Name"
The customer's email. Must be unique across your customers.
Example:
"new.email@example.com"
If true, all POST /tax/calculations sold to this customer will return $0 in tax owed.
Example:
true
The ID of the customer in your system. Must be unique across your customers.
Example:
"20507"
Response
The updated customer
The ID of the customer
Example:
"cus_123456789"
The type of object: tax.customer
Example:
"tax.customer"
The ID of the customer in your system
Example:
"20506"
The name of the created customer
Example:
"Customer Name"
The email of the created customer
Example:
"customer@example.com"
If true, all POST /tax/calculations sold to this customer will return $0 in tax owed. The default value is false.
Example:
true