> For the complete documentation index, see [llms.txt](https://docs.getsphere.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.getsphere.com/features/integrations/api/transaction-api/customers.md).

# Customers

Create, update and retrieve the customers used to calculate tax and generate invoices.

Customers represent the individuals or organizations on your taxable transactions. A customer record stores billing and shipping addresses, tax identification numbers and exemption status, and is referenced as `customer_id` on a transaction.

## Create or update a customer

> Creates a customer, or merges into the existing one with the same external\_id. Only the fields you send change; an address you send replaces the stored one in full.

```json
{"openapi":"3.1.0","info":{"title":"Sphere API","version":"1.0.0"},"servers":[{"url":"https://api.getsphere.com/v1"},{"url":"https://server.getsphere.com/tax_api/v1"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"CreateCustomerRequest":{"additionalProperties":false,"description":"Body for POST /v1/customers. external_id is the natural idempotency key —\nre-posting updates the existing customer (merge; an address replaces whole).","properties":{"external_id":{"maxLength":255,"minLength":1,"title":"External Id","type":"string"},"name":{"anyOf":[{"maxLength":1024,"type":"string"},{"type":"null"}],"default":null,"title":"Name"},"email":{"anyOf":[{"maxLength":255,"type":"string"},{"type":"null"}],"default":null,"title":"Email"},"billing_address":{"anyOf":[{"$ref":"#/components/schemas/AddressRequest"},{"type":"null"}],"default":null},"shipping_address":{"anyOf":[{"$ref":"#/components/schemas/AddressRequest"},{"type":"null"}],"default":null},"tax_ids":{"anyOf":[{"items":{"$ref":"#/components/schemas/CustomerTaxIdRequest"},"type":"array"},{"type":"null"}],"default":null,"title":"Tax Ids"},"tax_exempt":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Tax Exempt"}},"required":["external_id"],"title":"CreateCustomerRequest","type":"object"},"AddressRequest":{"additionalProperties":false,"description":"A postal address (billing or shipping).","properties":{"address1":{"anyOf":[{"maxLength":1024,"type":"string"},{"type":"null"}],"default":null,"title":"Address1"},"address2":{"anyOf":[{"maxLength":1024,"type":"string"},{"type":"null"}],"default":null,"title":"Address2"},"city":{"anyOf":[{"maxLength":255,"type":"string"},{"type":"null"}],"default":null,"title":"City"},"state":{"anyOf":[{"maxLength":255,"type":"string"},{"type":"null"}],"default":null,"title":"State"},"postal_code":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"title":"Postal Code"},"country":{"anyOf":[{"maxLength":255,"type":"string"},{"type":"null"}],"default":null,"title":"Country"}},"title":"AddressRequest","type":"object"},"CustomerTaxIdRequest":{"additionalProperties":false,"description":"A tax identifier on a customer (e.g. a VAT number).","properties":{"tax_id":{"maxLength":255,"minLength":1,"title":"Tax Id","type":"string"},"country":{"anyOf":[{"maxLength":255,"type":"string"},{"type":"null"}],"default":null,"title":"Country"},"secondary_id":{"anyOf":[{"maxLength":255,"type":"string"},{"type":"null"}],"default":null,"description":"Egypt only: the UIN, validated together with the TRN in tax_id. Ignored for every other country. Send other registrations, such as a Québec QST alongside a GST number, as separate tax_ids entries.","title":"Secondary Id"}},"required":["tax_id"],"title":"CustomerTaxIdRequest","type":"object"},"CustomerResponse":{"description":"A customer.","properties":{"external_id":{"title":"External Id","type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Name"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Email"},"billing_address":{"anyOf":[{"$ref":"#/components/schemas/AddressResponse"},{"type":"null"}],"default":null},"shipping_address":{"anyOf":[{"$ref":"#/components/schemas/AddressResponse"},{"type":"null"}],"default":null},"tax_ids":{"items":{"$ref":"#/components/schemas/CustomerTaxIdResponse"},"title":"Tax Ids","type":"array"},"tax_exempt":{"title":"Tax Exempt","type":"boolean"},"created_at":{"format":"date-time","title":"Created At","type":"string"}},"required":["external_id","tax_exempt","created_at"],"title":"CustomerResponse","type":"object"},"AddressResponse":{"description":"A postal address.","properties":{"address1":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Address1"},"address2":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Address2"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"City"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"State"},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Postal Code"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Country"}},"title":"AddressResponse","type":"object"},"CustomerTaxIdResponse":{"description":"A customer tax identifier.","properties":{"tax_id":{"title":"Tax Id","type":"string"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Country"},"secondary_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Secondary Id"}},"required":["tax_id"],"title":"CustomerTaxIdResponse","type":"object"}}},"paths":{"/customers":{"post":{"operationId":"customers_create","description":"Creates a customer, or merges into the existing one with the same external_id. Only the fields you send change; an address you send replaces the stored one in full.","summary":"Create or update a customer","tags":["Customers"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomerRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/CreateCustomerRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/CreateCustomerRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerResponse"}}},"description":""},"400":{"description":"Validation error, keyed by the failing field."},"403":{"description":"Missing, invalid, or inactive API key, or a key not provisioned for the Transaction API."},"429":{"description":"Rate limit exceeded. Carries Retry-After and RateLimit-* headers."}}}}}}
```

## GET /customers/{external\_id}

> Retrieve a customer

```json
{"openapi":"3.1.0","info":{"title":"Sphere API","version":"1.0.0"},"servers":[{"url":"https://api.getsphere.com/v1"},{"url":"https://server.getsphere.com/tax_api/v1"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"CustomerResponse":{"description":"A customer.","properties":{"external_id":{"title":"External Id","type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Name"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Email"},"billing_address":{"anyOf":[{"$ref":"#/components/schemas/AddressResponse"},{"type":"null"}],"default":null},"shipping_address":{"anyOf":[{"$ref":"#/components/schemas/AddressResponse"},{"type":"null"}],"default":null},"tax_ids":{"items":{"$ref":"#/components/schemas/CustomerTaxIdResponse"},"title":"Tax Ids","type":"array"},"tax_exempt":{"title":"Tax Exempt","type":"boolean"},"created_at":{"format":"date-time","title":"Created At","type":"string"}},"required":["external_id","tax_exempt","created_at"],"title":"CustomerResponse","type":"object"},"AddressResponse":{"description":"A postal address.","properties":{"address1":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Address1"},"address2":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Address2"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"City"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"State"},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Postal Code"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Country"}},"title":"AddressResponse","type":"object"},"CustomerTaxIdResponse":{"description":"A customer tax identifier.","properties":{"tax_id":{"title":"Tax Id","type":"string"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Country"},"secondary_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Secondary Id"}},"required":["tax_id"],"title":"CustomerTaxIdResponse","type":"object"}}},"paths":{"/customers/{external_id}":{"get":{"operationId":"customers_retrieve","summary":"Retrieve a customer","parameters":[{"in":"path","name":"external_id","schema":{"type":"string"},"description":"The external_id you assigned to the record.","required":true}],"tags":["Customers"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerResponse"}}},"description":""},"403":{"description":"Missing, invalid, or inactive API key, or a key not provisioned for the Transaction API."},"404":{"description":"No record with that external_id."},"429":{"description":"Rate limit exceeded. Carries Retry-After and RateLimit-* headers."}}}}}}
```