Create Customer

post

https://{subdomain}.myshoplaza.com/openapi/2025-06/customers

Create a new customer with the provided details.

🔒
Requires write_customer access scope.

The Create Customer API enables creating a new customer and optionally assign a default address.

This API is especially useful for:

Creating a new customer with contact information.
Associating addresses (billing or shipping) during creation.
Managing marketing subscription preferences.

Note: The operation is scoped to a specific shop, identified by its unique domain prefix (shopdomain), ensuring all updates are applied to the correct store.

Request Parameters

Public Request Parameters

📘
Public Request Parameters

Body Parameters

Field	Type	Required	Example	Description
`customers.contact_type`	`string`	Yes	`email`	Should be `phone` or `email`. If phone, the phone parameter is required; otherwise, email is required.
`customer.email`	`string`	Conditional	`[email protected]`	Email address, required when contact_type is email.
`customer.phone`	`string`	Conditional	`+`	Phone number with area code, required when contact_type is phone.
`customer.first_name`	`string`	No	`Ran`	Customer's first name.
`customer.last_name`	`string`	No	`Zhao`	Customer's last name.
`customer.accepts_marketing`	`boolean`	No	`true`	Whether to subscribe to marketing email campaigns. Defaults to `true`.
`customer.accepts_sms_marketing`	`boolean`	No	`true`	Whether to subscribe to SMS marketing campaigns. Defaults to `true`.
`customer.password`	`string`	No	`123456`	Customer's password.
`customer.password_confirmation`	`string`	No	`123456`	Confirmation of the password.
`customer.tags`	`array of strings.`	No	`["New Customer","Repeat Customer"]`	array of tag strings.
`customer.registered_at`	`string`	No	`2024-03-11T03:32:00Z`	The registered_at field records the creation time in UTC (0 timezone), formatted as ISO-8601.
`customer.addresses`	`array of objects`	No	`[ ... ]`	A list of address objects under the customer object.
`customer.addresses .first_name`	`string`	Yes	`Test`	First name of the consignee.
`customer.addresses .last_name`	`string`	Yes	`Test`	Last name of the consignee.
`customer.addresses .email`	`string`	No	`[email protected]`	Email address for the address.
`customer.addresses .address1`	`string`	No	`6`	Primary street address.
`customer.addresses .address2`	`string`	No	`1111`	Secondary street address (e.g., apartment, suite).
`customer.addresses .area`	`string`	No	`Bay Area`	Area or region of the address.
`customer.addresses .city`	`string`	No	`city`	City.
`customer.addresses .province`	`string`	No	`Guangdong`	Province or state.
`customer.addresses .province_code`	`string`	No	`US-NM`	Province code.
`customer.addresses .country`	`string`	Yes	`Aland Islands`	Country name.
`customer.addresses .country_code`	`string`	Yes	`US`	ISO country code.
`customer.addresses .company`	`string`	No	`ABC Limited`	Company name.
`customer.addresses .phone`	`string`	No	`+86 1231231234`	Phone number associated with the address.
`customer.addresses .phone_area_code`	`string`	No	`+86`	Area code for the phone number.
`customer.addresses .zip`	`string`	No	`515300`	Postal or ZIP code.
`customer.addresses .gender`	`string`	No	`male`	Gender, e.g., `male` or `female`.
`customer.addresses .default`	`boolean`	No	`true`	Indicates if this is the default address. Defaults to `true`.

Response Explanation

Public Response Parameters

📘
Public Response Parameters

Successful Response

Field	Type	Example	Description
`code`	string	`"success"`	Response status code
`message`	string	`"Addresses retrieved"`	Descriptive message of the response
`data.customer`	`object`		Customer object containing customer details.
`data.customer.id`	`string`	`2dd957e3-2051-4cdf-8584-9c0046b4d1ae`	Unique identifier for the customer.
`data.customer.first_name`	`string`	`Ryan`	Customer's first name.
`data.customer.last_name`	`string`	`Zhang`	Customer's last name.
`data.customer.name`	`string`	`Ryan Zhang`	Full name of the customer.
`data.customer.email`	`string`	`[email protected]`	Customer's email address.
`data.customer.phone`	`string`	`+86 1231231234`	Customer's phone number.
`data.customer.phone_area_code`	`string`	`null`	Area code of the phone number.
`data.customer.contact_type`	`string`	`email`	Contact type, either `email` or `phone`.
`data.customer.accepts_marketing`	`boolean`	`true`	Indicates if the customer is subscribed to marketing emails.
`data.customer.source`	`string`	`null`	Source of the customer data.
`data.customer.free_tax`	`boolean`	`false`	Indicates if the customer is exempt from taxes.
`data.customer.registered`	`boolean`	`false`	Indicates if the customer is registered.
`data.customer.orders_count`	`integer`	`0`	Number of orders placed by the customer.
`data.customer.last_order_at`	`string`	`null`	Timestamp of the customer's last order.
`data.customer.total_spent`	`string`	`"0.00"`	Total amount spent by the customer.
`data.customer.tags`	`array of string`	`["New Customer"]`	array of tag strings.
`data.customer.created_at`	`string`	`2024-04-17T11:10:33Z`	Timestamp when the customer was created, in ISO8601 format.
`data.customer.updated_at`	`string`	`2024-04-17T11:10:33Z`	Timestamp when the customer was last updated, in ISO8601 format.
`data.customer.subscribed_flag`	`integer`	`5`	Customer's marketing subscription status flag.
`data.customer. sms_subscribed_flag`	`integer`	`5`	Customer's SMS subscription status flag.
`data.customer. accepts_sms_marketing`	`boolean`	`true`	Indicates if the customer is subscribed to SMS marketing campaigns.
`data.customer.addresses`	`array of objects`	See Address Object fields below for full details.	List of all customer addresses.
`data.customer.addresses.id`	`string`	`9ffa8dc0-25b8-4424-832e-bab46fcfeb20`	Unique identifier for the address.
`data.customer. addresses.customer_id`	`string`	`2dd957e3-2051-4cdf-8584-9c0046b4d1ae`	ID of the customer this address belongs to.
`data.customer. addresses.first_name`	`string`	`Test`	First name of the consignee.
`data.customer. addresses.last_name`	`string`	`Test`	Last name of the consignee.
`data.customer.addresses.company`	`string`	`""`	Company name.
`data.customer.addresses.city`	`string`	``	City of the address.
`data.customer.addresses.province`	`string`	`""`	Province or state of the address.
`data.customer.addresses.country`	`string`	`Aland Islands`	Country name of the address.
`data.customer.addresses.zip`	`string`	`515300`	Postal or ZIP code.
`data.customer. addresses.province_code`	`string`	`"US-NM"`	Province code.
`data.customer. addresses.country_code`	`string`	`US`	ISO country code.
`data.customer. addresses.gender`	`string`	`""`	Gender of the consignee.
`data.customer.addresses.phone`	`string`	`+86 1231231234`	Phone number associated with the address.
`data.customer.addresses.area`	`string`	`""`	Area or region of the address.
`data.customer.addresses.email`	`string`	`[email protected]`	Email associated with the address.
`data.customer.addresses.address1`	`string`	``	Primary street address.
`data.customer.addresses.address2`	`string`	`1111`	Secondary street address.
`data.customer. addresses.country_name`	`string`	`Aland Islands`	Full name of the country.
`data.customer.addresses.default`	`boolean`	`true`	Indicates if this is the default address.

Error Response

Field	Type	Example	Description
`code`	string	`InvalidParameter`	Error http message
`message`	string	``	Error message

API Structure Overview

Language

Credentials

Header

URL

Click Try It! to start a request and see the response here!

Requires write_customer access scope.

Request Parameters

Public Request Parameters

Public Request Parameters

Body Parameters

Response Explanation

Public Response Parameters

Public Response Parameters

Successful Response

Error Response

API Structure Overview

Requires `write_customer` access scope.