post https://{shopdomain}.myshoplaza.com/openapi/2022-01/customers
Requires
write_customeraccess 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
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 | [email protected] | Email address, required when contact_type is email. |
phone | string | Conditional | +8615014471143 | Phone number with area code, required when contact_type is phone. |
first_name | string | No | Ryan | Customer's first name. |
last_name | string | No | Zhang | 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 | [email protected] | 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 150 1447 1143 | 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
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 | [email protected] | Customer's email address. |
customer.phone | string | +8615014471143 | 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-9c0046b4d1ae | 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 | 深圳 | 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 150 1447 1143 | 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 | [email protected] | 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 150 1447 1143 | Phone number associated with the address. |
customer.addresses.area | string | "" | Area or region of the address. |
customer.addresses.email | string | [email protected] | 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. |