> ## 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.
# Update Customer
> Update an existing customer's information
## Update Customer Endpoint (2025-05-12)
Update an existing customer's `name`, `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
* `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`. The conflicting customer's `id`, `reference_customer_id`, and `email` are returned in `error_meta`.
* `email` must be a valid email address, otherwise the request fails with `invalid_email`.
* Setting `is_tax_exempt` to `true` means all future `POST /tax/calculations` for this customer return \$0 in tax owed. Setting it to `false` removes 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_exempt` to `true` is rejected with `invalid_request`.
```bash cURL (mark tax exempt) theme={null}
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
}'
```
```bash cURL (by reference ID) theme={null}
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"
}'
```
```json 200 - Success 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
}
```
```json 400 - Duplicate theme={null}
{
"error": {
"error_code": "duplicate_customer",
"error_message": "Customer already exists.",
"error_meta": {
"id": "cust_1234567890abcdef",
"reference_customer_id": "20507",
"email": "new.email@example.com"
}
}
}
```
```json 400 - Not Found theme={null}
{
"error": {
"error_code": "customer_not_found",
"error_message": "Customer with id cust_9876543210abcdef not found"
}
}
```
## OpenAPI
````yaml POST /tax/customers/{customer_id}
openapi: 3.0.1
info:
title: Numeral API
description: API for sales tax calculations - Version 2024-09-01
license:
name: MIT
version: '2024-09-01'
servers:
- url: https://api.numeralhq.com/
security:
- bearerAuth: []
paths:
/tax/customers/{customer_id}:
post:
summary: Update Customer
description: >-
Update an existing customer's information. All fields are optional, but
at least one must be provided. Only the fields you include are changed.
parameters:
- name: customer_id
in: path
required: true
schema:
type: string
description: >-
The Numeral customer ID (`cust_xxx`) or your
`reference_customer_id`. Either identifier is accepted; no `id_type`
query parameter is needed.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerUpdateRequest'
examples:
mark_tax_exempt:
summary: Mark a customer as tax exempt
value:
is_tax_exempt: true
update_contact_info:
summary: Update name and email
value:
name: New Customer Name
email: new.email@example.com
update_reference_id:
summary: Change the reference customer ID
value:
reference_customer_id: '20507'
required: true
responses:
'200':
description: The updated customer
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerResponse'
'400':
description: >-
Invalid request. Returned when no updatable field is provided
(`invalid_request`), the email is malformed (`invalid_email`), the
customer does not exist or has been deleted (`customer_not_found`),
or another customer already uses the new `email` or
`reference_customer_id` (`duplicate_customer`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
CustomerUpdateRequest:
type: object
description: >-
Request body for updating a customer. All fields are optional, but at
least one must be provided.
properties:
name:
type: string
description: The customer's name
example: New Customer Name
email:
type: string
description: The customer's email. Must be unique across your customers.
example: new.email@example.com
is_tax_exempt:
type: boolean
description: >-
If true, all `POST /tax/calculations` sold to this customer will
return $0 in tax owed.
example: true
reference_customer_id:
type: string
description: >-
The ID of the customer in your system. Must be unique across your
customers.
example: '20507'
CustomerResponse:
type: object
properties:
id:
type: string
description: The ID of the customer
example: cus_123456789
object:
type: string
description: 'The type of object: `tax.customer`'
example: tax.customer
reference_customer_id:
type: string
description: The ID of the customer in your system
example: '20506'
name:
type: string
description: The name of the created customer
example: Customer Name
email:
type: string
description: The email of the created customer
example: customer@example.com
is_tax_exempt:
type: boolean
description: >-
If true, all `POST /tax/calculations` sold to this customer will
return $0 in tax owed. The default value is `false`.
example: true
Error:
type: object
description: >-
Legacy error format used by API versions before 2026-01-01. The request
ID is returned in the `X-Request-Id` response header, not in the body.
properties:
error:
type: object
properties:
error_code:
type: string
description: >-
Machine-readable error code (e.g., `missing_field`,
`incorrect_type`, `malformed_address`, `invalid_currency_code`,
`unrecognized_field`).
example: missing_field
error_message:
type: string
description: Human-readable error message.
example: Field is required
error_meta:
type: object
description: >-
Optional details about the error, such as the offending `field`
and the `expected`/`received` types.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````