Update a customer
Update a customer in the resolved organization. Only the fields you send are applied. Sending any address field resets addressStatus to UNVERIFIED; the new address is validated the next time the customer is processed, not during this call. taxRegistrations upserts each entry on its (countryCode, taxType) pair and leaves unlisted registrations alone; it cannot remove one.
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.
Path parameters
The unique identifier of the customer.
Body
Customer name. Omit to leave unchanged; send a value to replace; send null to clear.
Registered or legal business name. Omit to leave unchanged; send a value to replace; send null to clear.
Contact email address. Omit to leave unchanged; send a value to replace; send null to clear.
Contact phone number. Omit to leave unchanged; send a value to replace; send null to clear.
First line of the street address. Omit to leave unchanged; send a value to replace; send null to clear.
Second line of the street address. Omit to leave unchanged; send a value to replace; send null to clear.
City or locality. Omit to leave unchanged; send a value to replace; send null to clear.
County or district. Omit to leave unchanged; send a value to replace; send null to clear.
State or province code. Omit to leave unchanged; send a code to replace; send null to clear.
Postal or ZIP code. Omit to leave unchanged; send a value to replace; send null to clear.
Country code, ISO 3166-1 alpha-2. Omit to leave unchanged; send a code to replace; send null to clear.
Tax registrations to upsert, each keyed by (countryCode, taxType). Registrations you do not list are left unchanged, and omitting the field touches none. This field cannot remove a registration.
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.
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.