Create a customer
Create a customer in the resolved organization. Idempotent on externalId and source, and additionally on connectionId when you send one: sending the same values again returns the existing customer unchanged and responds 200 instead of creating a duplicate. The customer is not updated by this call; use PATCH /customers/{customerId} to update. Omitting connectionId matches an existing customer with that externalId and source whatever its connection. If the match is a customer you previously deleted, it is restored (not duplicated) so its transactions and exemptions stay attached to it. A new customer is always ACTIVE; delete one with DELETE.
Authorization
Headers
Release date, as YYYY-MM-DD. Defaults to 2026-07-21.
Target organization id (Organization-Id selector).
Target connection id; resolves to its organization.
Platform entity id; resolves to a connection's organization.
Optional source to disambiguate an Entity-Id.
Body
Your stable identifier for the customer, and the key creating is idempotent on. Sending one that already exists for the same source and connection returns that customer unchanged with 200 instead of creating a second one; use PATCH to update it.
Customer name.
Registered or legal business name, when it differs from name.
Contact email address.
Contact phone number.
Connection to attribute the customer to. Must belong to the resolved organization. Part of the idempotency key.
Human-facing identifier from the source system, shown in place of externalId when the source has both.
Origin system of the customer (e.g. API, SHOPIFY). Defaults to OTHER. Must be a supported public source; unsupported values are rejected.
ACUMATICAAIRWALLEXAMAZONAPIAPPLE_APP_STOREBESTBUYBIGCOMMERCEBILL_COMBUNNYCAMPFIRECHARGEBEECHECKOUTCHAMPDEELDUALENTRYEBAYECWIDETSYFACEBOOKFAIREFRESHBOOKSGOOGLE_APP_STOREGOOGLE_EXPRESSGROUPONGUSTOHYPERLINEINSTAGRAMINTUIT_ENTERPRISE_SUITEKICKSTARTERKILL_BILLMACYSMAGENTOMAXIOMERCADO_LIBREMICROSOFT_DYNAMICS_365MODALYSTNETSUITENEWEGGNOCNOCNORDSTROMODOOOPENMETERORBORDWAYOTHERPAYPALPINTERESTPLENTYONEQUICKBOOKSRECURLYRILLETRIPPLINGSAGE-INTACCTSALESFORCESHOPIFYSHOPLINESHOPWARESQUARESPACESTRIPETARGETTIKTOKVERTEX_O_SERIESWALMARTWAYFAIRWISHWIXWOOCOMMERCEXEROZENSKARZOHOZUORATax registrations to record for the customer, each keyed by (countryCode, taxType). Repeating a pair in one request is rejected.
First line of the street address. An empty string when none was supplied.
Second line of the street address. An empty string when none was supplied.
City or locality. An empty string when none was supplied.
County or district. An empty string when none was supplied.
State or province code, or null when none is on record.
Postal or ZIP code. An empty string when none was supplied.
Country code (ISO 3166-1 alpha-2), or null when none is on record.
Response
Kintsugi's unique identifier for the customer.
Organization the customer belongs to. Send it as the Organization-Id header to scope a write to this customer's organization.
Your stable identifier for the customer. null when the source system supplied none.
Human-facing identifier from the source system. null when the source has only externalId.
Customer name.
Registered or legal business name.
Contact email address.
Contact phone number.
Customer status. Reads never return archived customers, so this is always ACTIVE.
ACTIVEARCHIVEDHow far address validation got for this customer. UNVERIFIED until validation has run; BLANK when there is no address to validate.
UNVERIFIEDINVALIDPARTIALLY_VERIFIEDVERIFIEDUNVERIFIABLEBLANKBusiness registration number, or null when Kintsugi has not captured one for this customer.
Origin system of the customer (e.g. API, SHOPIFY). Any origin outside the published values is reported as OTHER.
ACUMATICAAIRWALLEXAMAZONAPIAPPLE_APP_STOREBESTBUYBIGCOMMERCEBILL_COMBUNNYCAMPFIRECHARGEBEECHECKOUTCHAMPDEELDUALENTRYEBAYECWIDETSYFACEBOOKFAIREFRESHBOOKSGOOGLE_APP_STOREGOOGLE_EXPRESSGROUPONGUSTOHYPERLINEINSTAGRAMINTUIT_ENTERPRISE_SUITEKICKSTARTERKILL_BILLMACYSMAGENTOMAXIOMERCADO_LIBREMICROSOFT_DYNAMICS_365MODALYSTNETSUITENEWEGGNOCNOCNORDSTROMODOOOPENMETERORBORDWAYOTHERPAYPALPINTERESTPLENTYONEQUICKBOOKSRECURLYRILLETRIPPLINGSAGE-INTACCTSALESFORCESHOPIFYSHOPLINESHOPWARESQUARESPACESTRIPETARGETTIKTOKVERTEX_O_SERIESWALMARTWAYFAIRWISHWIXWOOCOMMERCEXEROZENSKARZOHOZUORAConnection that produced the customer. null when the customer was not produced by a connection (e.g. created through this API).
First line of the street address. An empty string when none was supplied.
Second line of the street address. An empty string when none was supplied.
City or locality. An empty string when none was supplied.
County or district. An empty string when none was supplied.
State or province code.
Postal or ZIP code. An empty string when none was supplied.
Country code, ISO 3166-1 alpha-2.
The customer's tax registrations. An empty list when there are none.
An existing customer matched on externalId, source and connectionId. It was returned unchanged (revived first if it had been deleted); no new customer was created.
Successful Response
The request was invalid.
Authentication failed or was missing.
The credential is not permitted for this request.
The requested resource was not found.
The request conflicts with existing state.
The request failed validation.