Create Customer

Server URLloading...

POST

/customers.json

Send

Authorization

Body

Creates a new customer; can also be created alongside a new subscription. The only validation restriction is that you can only create one customer for a given reference value.

If provided, the reference value must be unique. It represents a unique identifier for the customer from your own app, i.e. the customer’s ID. This allows you to retrieve a given customer via a piece of shared information. Alternatively, you can choose to leave reference blank, and store the system-assigned unique ID for the customer, which is in the id attribute.

For more information, see Customer Details.

Required Country Format

Format the country attribute of the customer using the ISO Standard Country codes.

Countries should be formatted as two characters. For more information, see ISO 3166-1.

Required State Format

Format the state attribute of the customer using the ISO Standard State codes.

• US States (two characters): see ISO 3166-2.

• States Outside the US (two to three characters): To find the correct state codes outside the US, go to ISO 3166-1 and click on the link in the “ISO 3166-2 codes” column next to the country you wish to populate.

Locale

You can attribute a language/region to the customer to deliver invoices in any required language. For more information, see Customer Locale.

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.

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.

A blank pair is ignored rather than rejected, so a vat_number sent alongside it still takes effect.

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.

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

Response BodyCopy Anchor Link

curl -X POST "https://example.com/customers.json" \  -H "Content-Type: application/json" \  -d '{    "customer": {      "first_name": "Martha",      "last_name": "Washington",      "email": "martha@example.com",      "cc_emails": "george@example.com",      "organization": "ABC, Inc.",      "reference": "1234567890",      "address": "123 Main Street",      "address_2": "Unit 10",      "city": "Anytown",      "state": "MA",      "zip": "02120",      "country": "US",      "phone": "555-555-1212",      "locale": "es-MX"    }  }'

{  "customer": {    "first_name": "Cathryn",    "last_name": "Parisian",    "email": "Stella.McLaughlin6@example.net",    "cc_emails": null,    "organization": "Greenholt - Oberbrunner",    "reference": null,    "id": 76,    "created_at": "2021-03-29T07:47:00-04:00",    "updated_at": "2021-03-29T07:47:00-04:00",    "address": "739 Stephon Bypass",    "address_2": "Apt. 386",    "city": "Sedrickchester",    "state": "KY",    "state_name": "Kentucky",    "zip": "46979-7719",    "country": "US",    "country_name": "United States",    "phone": "230-934-3685",    "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": null,    "vat_country": null,    "entity_identifier_kind": null,    "entity_identifier_value": null,    "parent_id": null,    "locale": "en-US"  }}