Create Customer

post https://{shopdomain}.myshoplaza.com/openapi/2022-01/customers

🔒
Requires write_customer access scope.

Create 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
`contact_type`	`string`	Yes	`email`	Should be `phone` or `email`. If phone, the phone parameter is required; otherwise, email is required.
`email`	`string`	Conditional	`test@shoplazza.com`	Email address, required when contact_type is email.
`phone`	`string`	Conditional	`+`	Phone number with area code, required when contact_type is phone.
`first_name`	`string`	No	`Ran`	Customer's first name.
`last_name`	`string`	No	`Zhao`	Customer's last name.
`accepts_marketing`	`boolean`	No	`true`	Whether to subscribe to marketing email campaigns. Defaults to `true`.
`accepts_sms_marketing`	`boolean`	No	`true`	Whether to subscribe to SMS marketing campaigns. Defaults to `true`.
`password`	`string`	No	`123456`	Customer's password.
`password_confirmation`	`string`	No	`123456`	Confirmation of the password.
`tags`	`string`	No	`New Customer,Repeat Customer`	Comma-separated tags assigned to the 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.
`addresses`	`array of objects`	No	`[ ... ]`	A list of address objects under the customer object.
`addresses .first_name`	`string`	Yes	`Test`	First name of the consignee.
`addresses .last_name`	`string`	Yes	`Test`	Last name of the consignee.
`addresses .email`	`string`	No	`test@shoplazza.com`	Email address for the address.
`addresses .address1`	`string`	No	`6`	Primary street address.
`addresses .address2`	`string`	No	`1111`	Secondary street address (e.g., apartment, suite).
`addresses .area`	`string`	No	`Bay Area`	Area or region of the address.
`addresses .city`	`string`	No	`city`	City.
`addresses .province`	`string`	No	`Guangdong`	Province or state.
`addresses .province_code`	`string`	No	`GD`	Province code.
`addresses .country`	`string`	Yes	`Aland Islands`	Country name.
`addresses .country_code`	`string`	Yes	`AX`	ISO country code.
`addresses .company`	`string`	No	`ABC Limited`	Company name.
`addresses .phone`	`string`	No	`+86 1231231234`	Phone number associated with the address.
`addresses .phone_area_code`	`string`	No	`+86`	Area code for the phone number.
`addresses .zip`	`string`	No	`515300`	Postal or ZIP code.
`addresses .gender`	`string`	No	`male`	Gender, e.g., `male` or `female`.
`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
`customer`	`object`		Customer object containing customer details.
`customer .id`	`string`	`2dd957e3-2051-4cdf-8584-9c0046b4d1ae`	Unique identifier for the customer.
`customer .first_name`	`string`	`Ryan`	Customer's first name.
`customer .last_name`	`string`	`Zhang`	Customer's last name.
`customer .name`	`string`	`Ryan Zhang`	Full name of the customer.
`customer .email`	`string`	`test@shoplazza.com`	Customer's email address.
`customer .phone`	`string`	`+86 1231231234`	Customer's phone number.
`customer .phone_area_code`	`string`	`null`	Area code of the phone number.
`customer .contact_type`	`string`	`email`	Contact type, either `email` or `phone`.
`customer .accepts_marketing`	`boolean`	`true`	Indicates if the customer is subscribed to marketing emails.
`customer .source`	`string`	`null`	Source of the customer data.
`customer .free_tax`	`boolean`	`false`	Indicates if the customer is exempt from taxes.
`customer .registered`	`boolean`	`false`	Indicates if the customer is registered.
`customer .orders_count`	`integer`	`0`	Number of orders placed by the customer.
`customer .last_order_at`	`string`	`null`	Timestamp of the customer's last order.
`customer .total_spent`	`string`	`"0.00"`	Total amount spent by the customer.
`customer .tags`	`string`	`New Customer`	Comma-separated tags associated with the customer.
`customer .created_at`	`string`	`2024-04-17T11:10:33Z`	Timestamp when the customer was created, in ISO8601 format.
`customer .updated_at`	`string`	`2024-04-17T11:10:33Z`	Timestamp when the customer was last updated, in ISO8601 format.
`customer .subscribed_flag`	`integer`	`5`	Customer's marketing subscription status flag.
`customer .sms_subscribed_flag`	`integer`	`5`	Customer's SMS subscription status flag.
`customer .accepts_sms_marketing`	`boolean`	`true`	Indicates if the customer is subscribed to SMS marketing campaigns.
`customer .default_address`	`object`	See Address Object fields below.	Default address object for the customer.
`customer .default_address .id`	`string`	`9ffa8dc0-25b8-4424-832e-bab46fcfeb20`	Unique identifier for the address.
`customer .default_address .customer_id`	`string`	`2dd957e3-2051-4cdf-8584-9c0046b4d1a`	ID of the customer this address belongs to.
`customer .default_address .first_name`	`string`	`Test`	First name of the consignee.
`customer .default_address .last_name`	`string`	`Test`	Last name of the consignee.
`customer .default_address .company`	`string`	`""`	Company name.
`customer .default_address .city`	`string`	`shenzhen`	City of the address.
`customer .default_address .province`	`string`	`""`	Province or state of the address.
`customer .default_address .country`	`string`	`Aland Islands`	Country name of the address.
`customer .default_address .zip`	`string`	`515300`	Postal or ZIP code.
`customer .default_address .province_code`	`string`	`""`	Province code.
`customer .default_address .country_code`	`string`	`AX`	ISO country code.
`customer .default_address .gender`	`string`	`""`	Gender of the consignee.
`customer .default_address .phone`	`string`	`+86 1231231234`	Phone number associated with the address.
`customer .default_address .phone_area_code`	`string`	`null`	Area code of the phone number.
`customer .default_address .area`	`string`	`""`	Area or region of the address.
`customer .default_address .email`	`string`	`test@shoplazza.com`	Email associated with the address.
`customer .default_address .name`	`string`	`Test Test`	Full name of the consignee.
`customer .default_address .address1`	`string`	`6 三聖街`	Primary street address.
`customer .default_address .address2`	`string`	`1111`	Secondary street address.
`customer .default_address .country_name`	`string`	`Aland Islands`	Full name of the country.
`customer .default_address .default`	`boolean`	`true`	Indicates if this is the default address.
`customer .addresses`	`array of objects`	See Address Object fields below for full details.	List of all customer addresses.
`customer .addresses .id`	`string`	`9ffa8dc0-25b8-4424-832e-bab46fcfeb20`	Unique identifier for the address.
`customer .addresses .customer_id`	`string`	`2dd957e3-2051-4cdf-8584-9c0046b4d1ae`	ID of the customer this address belongs to.
`customer .addresses .first_name`	`string`	`Test`	First name of the consignee.
`customer .addresses .last_name`	`string`	`Test`	Last name of the consignee.
`customer .addresses .company`	`string`	`""`	Company name.
`customer .addresses .city`	`string`	`深圳`	City of the address.
`customer .addresses .province`	`string`	`""`	Province or state of the address.
`customer .addresses .country`	`string`	`Aland Islands`	Country name of the address.
`customer .addresses .zip`	`string`	`515300`	Postal or ZIP code.
`customer .addresses .province_code`	`string`	`""`	Province code.
`customer .addresses .country_code`	`string`	`AX`	ISO country code.
`customer .addresses .gender`	`string`	`""`	Gender of the consignee.
`customer .addresses .phone`	`string`	`+86 1231231234`	Phone number associated with the address.
`customer .addresses .area`	`string`	`""`	Area or region of the address.
`customer .addresses .email`	`string`	`test@shoplazza.com`	Email associated with the address.
`customer .addresses .address1`	`string`	`6 三聖街`	Primary street address.
`customer .addresses .address2`	`string`	`1111`	Secondary street address.
`customer .addresses .country_name`	`string`	`Aland Islands`	Full name of the country.
`customer .addresses .default`	`boolean`	`true`	Indicates if this is the default address.

Error Response

Error responses in the API can be represented using two different fields: errors and error. Both fields provide details about issues encountered during request processing. Below is an explanation of the fields with their respective examples and descriptions.

Field	Type	Example	Description
`errors`	Email or Phone is already taken	`["Context"]`	A list of errors encountered during the request processing.

Field	Type	Example	Description
`error`	String	`"store is not active"`	Indicates an error encountered during the process

Error Detail

Status Code	Message	Possible Reason	Example Response
400	Bad Request	Invalid input format or request structure (e.g., missing required fields or incorrect data types).	`Bad Request`
	Unauthorized	The request is missing valid authentication credentials or the credentials provided are invalid.	`Unauthorized`
422	Email or Phone is already taken	Provided existed phone number or email.
	Password is too short (minimum is 6 characters)	Provides password's length is less than 6
	Password confirmation must be equal to password	Confirmation Password is not equal to Password.
	Phone is invalid	Phone number is not invalid
	Country can't be blank	empty Country.
	Country code can't be blank	empty Country code.

Create Customer

🔒
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

Error Detail

API Structure Overview

🔒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

Error Detail

API Structure Overview

🔒
Requires `write_customer` access scope.

📘
Public Request Parameters

📘
Public Response Parameters