Partially update a customer

PATCH /accounting/customers/{id}

Group: Accounting › Customers · Operation ID: updateCustomer

Writes only the fields the request body carries. Everything omitted is left exactly as it was, so a caller never has to read the customer first in order to change one field. The response is empty; read the updated record with GET accounting/customers/:id.

Omission and clearing are two different requests on the nullable fields (partnerType, invoiceEmail, mainEmail, segment, exemptionNumber): pass the key with a null value to clear it, or leave it out entirely to keep the current value. A cleared field is simply absent from the next read, the same as a customer that never had one set. name, customerType, businessType, taxExempt and defaultCurrency have no equivalent clear — they are required on the underlying record.

entityId is not part of this request: the owning legal entity is fixed at creation and cannot move — create a new customer under the right entity instead. Changing name and/or customerType is still checked against the (name, entityId, customerType) uniqueness the customer directory enforces; a collision fails with DUPLICATE_CUSTOMER.

customerType 'endCustomer' is rejected with END_CUSTOMER_NOT_SUPPORTED for the same reason CustomerCreateEndpointV1 rejects it — no field in this API's contract can carry the required partner link.

Addresses can be written two ways, and the request may use one or the other, not both. addresses replaces the whole set: send the complete list you want stored, or an empty array to remove them all — every address is recreated, so the addressIds change. createAddresses, updateAddresses and deleteAddresses instead edit the set in place, leaving anything they do not name untouched and keeping its addressId; updateAddresses and deleteAddresses identify an address by the addressId the read endpoints return, and fail with ADDRESS_NOT_FOUND when it is not on this customer. A deleted address is only detached from the customer — the record survives, since an invoice may still point at it. Each type keeps exactly one default throughout. externalIdentifiers follow the full create/update/delete split: createExternalIdentifiers adds a fieldName not already present, updateExternalIdentifiers rewrites one that is, and deleteExternalIdentifiers removes by fieldName; referencing a fieldName in the wrong bucket fails with EXTERNAL_IDENTIFIER_NOT_FOUND or DUPLICATE_EXTERNAL_IDENTIFIER.

An unknown id fails with NOT_FOUND. The call runs in a transaction, so a failure leaves the customer untouched.

Open in the interactive reference

Parameters

Name In Type Required Description
Api-Version header "v1" yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.
Idempotency-Key header string no An opaque caller-chosen string (1-255 characters) that makes this request safe to retry. Repeating the same key with an identical request body replays the original response instead of re-executing - but only once that original request succeeded; a failed attempt re-executes on retry. Repeating the key with a different body is answered with 422. A key still in flight is answered with 409 - as is a key whose original request was interrupted before it finished, for a few minutes afterwards, until that attempt is presumed dead. A completed response stays replayable for 24 hours. The key is scoped to the caller, not to the action: reusing it for a different action is answered with 409 or 422 rather than treated independently. On read actions this header is ignored. On write actions that cannot offer the guarantee it is answered with 400 IDEMPOTENCY_NOT_SUPPORTED rather than silently ignored.
id path string yes Platform id (a UUID) of the customer to update; bound from the :id path segment.

Request body

Required, application/json: updateCustomerInput.

Field Type Required Description
name string no New customer display name. Omit to leave unchanged.
customerType string no New customer type. One of 'default', 'partner', 'endCustomer' (the last rejected — see END_CUSTOMER_NOT_SUPPORTED). Cannot be changed once the customer appears on a sales order. Omit to leave unchanged.
partnerType string or null no New partner type, relevant when customerType is 'partner'. One of 'reseller', 'thirdPartyPayer'. Omit to leave unchanged; pass null to clear.
businessType string no New business type. One of 'company', 'individual'. Omit to leave unchanged.
invoiceEmail string or null no New invoice email. Omit to leave unchanged; pass null to clear.
mainEmail string or null no New main contact email. Omit to leave unchanged; pass null to clear.
taxExempt boolean no New tax-exempt flag. Omit to leave unchanged. Setting this to false also clears exemptionNumber.
defaultCurrency string no New default currency, as a 3-letter ISO 4217 code. Omit to leave unchanged. Cannot be cleared — every customer carries a currency.
segment string or null no New market segment. One of 'SMB', 'MidMarket', 'Enterprise'. Ignored when the customer's effective businessType is 'individual'. Omit to leave unchanged; pass null to clear.
exemptionNumber string or null no New tax-exemption certificate number. Only storable while the customer is tax exempt: supplying one when taxExempt is, or becomes, false fails with EXEMPTION_NUMBER_REQUIRES_TAX_EXEMPT. Omit to leave unchanged; pass null to clear.
paymentTermCode string no Payment-term code applied to this customer's invoices. Fails with UNKNOWN_REFERENCE when no such payment term exists.
parentId string no Customer UUID of this customer's parent in the business-partner hierarchy. Fails with UNKNOWN_REFERENCE when no such customer exists.
partnerId string no Customer UUID of the partner this customer buys through. Fails with UNKNOWN_REFERENCE when no such customer exists.
salesChannel string or null no Channel the customer was won through. A SalesChannel member. Omit to leave unchanged; pass null to clear.
additionalContactEmail string or null no Further contact addresses, beyond the invoice and main contacts. Omit to leave unchanged; pass null to clear.
mainContactName string or null no Name of the customer's main contact person. Omit to leave unchanged; pass null to clear.
preferredLanguage string or null no Language the customer prefers correspondence in. A PreferredLanguage member. Omit to leave unchanged; pass null to clear.
crmCustomerId string or null no The customer's identifier in the CRM system it was sourced from. Omit to leave unchanged; pass null to clear.
businessIdentificationNumber string or null no Government-issued business registration number. Omit to leave unchanged; pass null to clear.
invoiceConsolidation string or null no How invoices are consolidated for this customer. An InvoiceConsolidation member. Omit to leave unchanged; pass null to clear.
invoiceDeliveryMode string or null no How invoices reach the customer. An InvoiceDeliveryMode member. Omit to leave unchanged; pass null to clear.
isExemptFromCreditCardFee boolean no Whether the customer is exempt from credit-card surcharges.
billableTravelExpenseInvoiceDetail string no Whether billable travel and expense items appear itemised or consolidated. An InvoiceDetail member.
status string no Lifecycle status of the customer record. A CustomerStatus member.
taxExemptCode string or null no Code behind the tax exemption. Omit to leave unchanged; pass null to clear.
taxRegistrations array of object no Tax registrations to record for this customer. Upserted by (country, type): an entry matching an existing registration updates it, anything else is added; registrations left out are untouched.
taxRegistrations[].country string yes ISO 3166-1 country code the registration applies in.
taxRegistrations[].taxNumber string yes Official tax identification number issued by the tax authority.
taxRegistrations[].type string yes Kind of tax identification number. One of 'tax', 'salesTax', 'VAT', 'GST', 'EIN', 'TIN'.
taxRegistrations[].effectiveDate string (date) no Date the registration becomes valid for tax calculations (YYYY-MM-DD).
taxRegistrations[].isActive boolean no Whether the registration is used for tax calculations. Defaults to true.
payment object no Payment-provider link for this customer. externalPaymentMethodId requires an externalCustomerId, either in the same request or already stored.
payment.provider string no Payment provider name, e.g. 'Stripe'. Required when any other payment field is supplied.
payment.externalCustomerId string no The customer's identifier in the payment provider's system, e.g. a Stripe customer id.
payment.externalPaymentMethodId string no The customer's default payment-method identifier in the provider's system, e.g. a Stripe payment method id.
addresses array of object no The customer's addresses. The array REPLACES the whole address set across both types: omit the field to leave every address unchanged, or send an empty array to remove them all.
addresses[].type string yes Which address this is. One of 'billTo', 'soldTo'.
addresses[].attention string no Person or department correspondence at this address is directed to.
addresses[].isDefault boolean no Marks this entry as its type's default. At most one per type; when a type has none marked, its first entry becomes the default.
addresses[].line1 string yes Street address line 1: number, street name, or PO box.
addresses[].line2 string no Apartment, suite, unit, building, floor, etc.
addresses[].city string yes City or locality.
addresses[].stateProvince string no State, province, or region.
addresses[].country string yes Country, as a name or ISO 3166-1 code.
addresses[].zipCode string yes Postal or ZIP code.
createAddresses array of object no Addresses to add, on top of the ones the customer already has. Cannot be combined with addresses.
createAddresses[].type string yes Which address this is. One of 'billTo', 'soldTo'.
createAddresses[].attention string no Person or department correspondence at this address is directed to.
createAddresses[].isDefault boolean no Marks this entry as its type's default, demoting the previous holder. At most one per type per request.
createAddresses[].line1 string yes Street address line 1: number, street name, or PO box.
createAddresses[].line2 string no Apartment, suite, unit, building, floor, etc.
createAddresses[].city string yes City or locality.
createAddresses[].stateProvince string no State, province, or region.
createAddresses[].country string yes Country, as a name or ISO 3166-1 code.
createAddresses[].zipCode string yes Postal or ZIP code.
updateAddresses array of object no Addresses to rewrite, each identified by the addressId the read endpoints return. Every field but addressId is optional: an omitted one keeps its stored value. Rejected with ADDRESS_NOT_FOUND if the addressId is not on this customer. Cannot be combined with addresses.
updateAddresses[].addressId string yes Id of the address record to rewrite (a UUID), as returned by GET accounting/customers/:id.
updateAddresses[].type string no Moves the address to a different set. One of 'billTo', 'soldTo'.
updateAddresses[].attention string no Person or department correspondence at this address is directed to.
updateAddresses[].isDefault boolean no Marks this entry as its type's default, demoting the previous holder.
updateAddresses[].line1 string no Street address line 1: number, street name, or PO box.
updateAddresses[].line2 string no Apartment, suite, unit, building, floor, etc.
updateAddresses[].city string no City or locality.
updateAddresses[].stateProvince string no State, province, or region.
updateAddresses[].country string no Country, as a name or ISO 3166-1 code.
updateAddresses[].zipCode string no Postal or ZIP code.
deleteAddresses array of string no addressIds of addresses to remove from this customer. The address record itself is kept, since an invoice may still reference it; only the customer's link to it goes. Rejected with ADDRESS_NOT_FOUND if the addressId is not on this customer. Cannot be combined with addresses.
createExternalIdentifiers array of object no External identifiers to add. Rejected with DUPLICATE_EXTERNAL_IDENTIFIER if the fieldName is already present on the record.
createExternalIdentifiers[].fieldName string yes
createExternalIdentifiers[].value string yes
createExternalIdentifiers[].externalUrl string no
updateExternalIdentifiers array of object no External identifiers to rewrite, matched by fieldName. Rejected with EXTERNAL_IDENTIFIER_NOT_FOUND if the fieldName is not already present.
updateExternalIdentifiers[].fieldName string yes
updateExternalIdentifiers[].value string yes
updateExternalIdentifiers[].externalUrl string no
deleteExternalIdentifiers array of string no fieldNames of external identifiers to remove. Rejected with EXTERNAL_IDENTIFIER_NOT_FOUND if a name is not present.

Example:

{
  "name": "<name>",
  "customerType": "<customerType>",
  "partnerType": "<partnerType>",
  "businessType": "<businessType>",
  "invoiceEmail": "ap@example-robotics.com",
  "mainEmail": "<mainEmail>",
  "taxExempt": true,
  "defaultCurrency": "<defaultCurrency>",
  "segment": "MidMarket",
  "exemptionNumber": "<exemptionNumber>",
  "paymentTermCode": "<paymentTermCode>",
  "parentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "partnerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "salesChannel": "<salesChannel>",
  "additionalContactEmail": "<additionalContactEmail>",
  "mainContactName": "<mainContactName>",
  "preferredLanguage": "<preferredLanguage>",
  "crmCustomerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "businessIdentificationNumber": "<businessIdentificationNumber>",
  "invoiceConsolidation": "<invoiceConsolidation>",
  "invoiceDeliveryMode": "<invoiceDeliveryMode>",
  "isExemptFromCreditCardFee": true,
  "billableTravelExpenseInvoiceDetail": "<billableTravelExpenseInvoiceDetail>",
  "status": "<status>",
  "taxExemptCode": "<taxExemptCode>",
  "taxRegistrations": [
    {
      "country": "<country>",
      "taxNumber": "<taxNumber>",
      "type": "<type>",
      "effectiveDate": "2026-01-15",
      "isActive": true
    }
  ],
  "payment": {
    "provider": "<provider>",
    "externalCustomerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "externalPaymentMethodId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "addresses": [
    {
      "type": "<type>",
      "attention": "<attention>",
      "isDefault": true,
      "line1": "<line1>",
      "line2": "<line2>",
      "city": "<city>",
      "stateProvince": "<stateProvince>",
      "country": "<country>",
      "zipCode": "<zipCode>"
    }
  ],
  "createAddresses": [
    {
      "type": "<type>",
      "attention": "<attention>",
      "isDefault": true,
      "line1": "<line1>",
      "line2": "<line2>",
      "city": "<city>",
      "stateProvince": "<stateProvince>",
      "country": "<country>",
      "zipCode": "<zipCode>"
    }
  ],
  "updateAddresses": [
    {
      "addressId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "type": "<type>",
      "attention": "<attention>",
      "isDefault": true,
      "line1": "<line1>",
      "line2": "<line2>",
      "city": "<city>",
      "stateProvince": "<stateProvince>",
      "country": "<country>",
      "zipCode": "<zipCode>"
    }
  ],
  "deleteAddresses": [
    "<deleteAddresses>"
  ],
  "createExternalIdentifiers": [
    {
      "fieldName": "<fieldName>",
      "value": "<value>",
      "externalUrl": "<externalUrl>"
    }
  ],
  "updateExternalIdentifiers": [
    {
      "fieldName": "<fieldName>",
      "value": "<value>",
      "externalUrl": "<externalUrl>"
    }
  ],
  "deleteExternalIdentifiers": [
    "<deleteExternalIdentifiers>"
  ]
}

Response

200 Success

Response headers

Errors

Code Status
NOT_FOUND 400
INVALID_FIELD_VALUE 400
MULTIPLE_DEFAULT_ADDRESSES 400
DUPLICATE_CUSTOMER 400
END_CUSTOMER_NOT_SUPPORTED 400
UNKNOWN_EXTERNAL_IDENTIFIER 400
DUPLICATE_EXTERNAL_IDENTIFIER 400
EXTERNAL_IDENTIFIER_NOT_FOUND 400
ADDRESS_NOT_FOUND 400
CUSTOMER_TYPE_CHANGE_NOT_ALLOWED 400
UNKNOWN_REFERENCE 400
UNKNOWN_PAYMENT_PROVIDER 400
PAYMENT_METHOD_REQUIRES_CUSTOMER_ID 400
EXEMPTION_NUMBER_REQUIRES_TAX_EXEMPT 400
IDEMPOTENCY_KEY_CONFLICT 409
IDEMPOTENCY_PAYLOAD_MISMATCH 422

Statuses