Update Customer

Server URLloading...

PUT

/customers/{id}.json

Send

Authorization

Path

Body

Updates the customer.

Tax and Business Identifiers

Send entity_identifier_kind and entity_identifier_value together to store the customer's tax or business identifier, such as an EU VAT number, a French SIREN, or a LEI. A customer holds one identifier at a time, so saving an identifier of a different kind replaces the existing one.

The vat_eu and national_tax kinds also require vat_country. An unsupported kind, a missing or mismatched vat_country, or a gln, duns, or lei value in the wrong format returns 422.

Always send the kind. entity_identifier_value on its own is stored as a company_reg when no vat_country is present, and returns 422 naming entity_identifier_kind when one is.

To clear an identifier, send a supported entity_identifier_kind with a blank entity_identifier_value, or send a blank vat_number on its own. The first form also clears vat_number and vat_country, and it removes whichever identifier the customer holds, whatever kind you send with it.

The legacy vat_number and vat_country pair still works on its own. When neither entity identifier field is sent, Advanced Billing derives the kind from vat_country: an EU member state code or GB gives vat_eu, one of the national tax country codes gives national_tax, and a blank or unrecognized country gives company_reg.

Sending a customer response straight back leaves the tax ID alone. A blank pair, and a pair that still matches the stored identifier with vat_country unchanged, are read as nothing to change rather than as a request to clear. For gln, duns, and lei that also covers the vat_number the response mirrors back, so the kind survives the round trip.

What you do change is applied, and the entity identifier fields take precedence over vat_number. A different kind or value writes that identifier, and vat_number and vat_country follow from it. A different vat_country next to an unchanged pair is a real edit, so it is validated and can return 422. Changing only vat_number leaves the pair unchanged, so the derivation above decides the kind, which turns a gln, duns, or lei customer into a company_reg. Setting vat_number to null or a blank string still clears the identifier.

The response reports the stored identifier in entity_identifier_kind and entity_identifier_value, and repeats its value in vat_number.

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

curl -X PUT "https://example.com/customers/0.json" \  -H "Content-Type: application/json" \  -d '{    "customer": {      "first_name": "Martha",      "last_name": "Washington",      "email": "martha.washington@example.com"    }  }'

{  "customer": {    "first_name": "Martha",    "last_name": "Washington",    "email": "martha.washington@example.com",    "cc_emails": "george.washington@example.com",    "organization": null,    "reference": null,    "id": 14967442,    "created_at": "2016-12-05T10:33:07-05:00",    "updated_at": "2016-12-05T10:38:00-05:00",    "address": null,    "address_2": null,    "city": null,    "state": null,    "zip": null,    "country": null,    "phone": null,    "verified": false,    "portal_customer_created_at": null,    "portal_invite_last_sent_at": null,    "portal_invite_last_accepted_at": null,    "tax_exempt": false,    "surcharging": false,    "vat_number": "012345678",    "vat_country": null,    "entity_identifier_kind": null,    "entity_identifier_value": null  }}