Sign in

v1

latestOpenAPI 3.1.02026-07-134488210.8 KB
Customers

Create or update customer

Create or update a customer profile. Uses the email address as the upsert key — if a customer with that email exists, their profile is updated; otherwise, a new customer is created.

Profile fields

  • firstName and lastName are set directly on the customer. A full display name is automatically generated from these fields.
  • phoneNumber should be in E.164 format (e.g., +12345678900). If the number is new, it is added to the customer's contact information.

Location

Providing location sets the customer's current location. Only the fields you include are updated.

Custom fields

Use customFields to store arbitrary key-value data on the customer (e.g., pricing_plan, subscription_source). Values can be strings, numbers, or booleans. If a custom field doesn't exist yet, it is created automatically.

Requires the customers_write scope.

put/stores/{storeId}/customers

Path parameters

storeIdstring required
Example:64e5a8a1af49a89df37e4ee7

Store ID

Request body

emailstring email required

Customer email address. Used as the upsert key to find or create the customer.

firstNamestring

Customer first name

lastNamestring

Customer last name

phoneNumberstring

Customer phone number in E.164 format (e.g., +12345678900). Appended to the existing phone list if not already present.

customFieldsobject

Custom field values as key-value pairs. Keys are field names and values can be strings, numbers, or booleans. The field type is determined automatically based on the value:

  • String values → STRING custom field
  • Number values → NUMBER custom field
  • Boolean values → BOOLEAN custom field
  • ISO 8601 datetime strings (e.g., "2026-02-24T12:15:00.000Z") → DATE custom field (auto-detected)

If a field name does not already have a declaration, one is created automatically. For STRING fields, unique values are tracked as options (used for segment filtering dropdowns). NUMBER, BOOLEAN, and DATE fields do not track options.

Example request

{
  "phoneNumber": "+12345678900",
  "location": {
    "state": "Washington",
    "stateCode": "WA",
    "postalCode": "12345",
    "country": "United States",
    "countryCode": "US",
    "ianaTimeZoneName": "America/New_York"
  },
  "customFields": {
    "subscription_source": "web",
    "status": "Active",
    "loyalty_points": 1250,
    "vip_member": true,
    "signup_date": "2026-02-24T12:15:00.000Z"
  }
}

Response

Existing customer updated

idstring required

Redo customer ID

emailstring required

Customer email address

createdboolean required

Whether a new customer was created (true) or an existing customer was updated (false).