Syncing customers

A customer is a person your account sells to or rewards: shop buyers, order recipients, and the contacts you sync in from another tool (a CRM, a membership platform, a booking system). Customers are unique by email within your account.

Reading needs the customers:read scope; creating and updating needs customers:write (which implies customers:read).

Syncing: create or update by email

POST /v1/customers
Authorization: Bearer mchp_…
Content-Type: application/json

{
  "email": "sam@example.com",
  "first_name": "Sam",
  "last_name": "Lee",
  "custom_fields": { "membership_tier": "gold", "joined_year": 2024, "vip": true }
}

The customer is matched by email (case-insensitive):

• No match — a customer is created and the response is 201. Creating needs first_name and last_name.
• Match — only the fields you send are changed and the response is 200. Send just email and custom_fields to update a tag without touching the name.

Either way the body is the customer. Calling it again with the same payload is safe, so a sync can simply send every changed contact.

Custom fields

custom_fields holds your own data on a customer — a membership tier, a CRM id, a join date. Up to 50 fields per customer:

Writes merge: the fields you send are set, fields you leave out are kept, and a field sent as null is removed.

{ "email": "sam@example.com", "custom_fields": { "membership_tier": "platinum", "vip": null } }

Listing and finding customers

GET /v1/customers?limit=50
GET /v1/customers?email=sam@example.com

Newest first, cursor-paginated (see Pagination, errors & rate limits). The email filter is an exact, case-insensitive match, so it returns zero or one customer — use it to look a contact up before acting on it.

GET /v1/customers/{id} returns one customer.

Updating a customer

PATCH /v1/customers/{id}
Content-Type: application/json

{ "phone": "+61 400 000 000", "custom_fields": { "membership_tier": "silver" } }

Changes only the fields sent, with the same custom_fields merge. Changing email to one another customer already has returns 422.

Fields