get https://{shopdomain}.myshoplaza.com/openapi/2022-01/customers
Requires
read_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
Query Parameters
| Parameter | Type | Required | Example | Description |
|---|---|---|---|---|
ids | string | No | 701670d5-4afd-40b5-8d4f-7e0e55683849,da1bb9af-2489-40df-a15e-f54abd7fd86 | A comma-separated list of customer IDs. |
limit | int32 | No | 10 | Number of records to retrieve per page. Default is 10, maximum is 250. |
page | int32 | No | 1 | Page number to retrieve. Default is 1. |
created_at_min | string | No | 2016-01-18T23:41:00Z | Retrieve customers created after this date. It's in UTC (0 timezone), formatted as ISO-8601 |
created_at_max | string | No | 2016-01-18T23:41:00Z | Retrieve customers created before this date. It's in UTC (0 timezone), formatted as ISO-8601 |
updated_at_min | string | No | 2016-01-18T23:41:00Z | Retrieve customers last updated after this date. It's in UTC (0 timezone), formatted as ISO-8601 |
updated_at_max | string | No | 2016-01-18T23:41:00Z | Retrieve customers last updated before this date. It's in UTC (0 timezone), formatted as ISO-8601 |
email | string | No | [email protected] | Filter customers by email. |
contact | string | No | [email protected] | Filter customers by contact information (email or phone). |
Response Explanation
Public Response Parameters
Successful Response
| Field | Type | Example | Description |
|---|---|---|---|
customers | array of objects | Array containing customer objects. | |
customers[].id | string | 2dd957e3-2051-4cdf-8584-9c0046b4d1ae | Unique identifier for the customer. |
customers[].first_name | string | Ryan | Customer's first name. |
customers[].last_name | string | Zhang | Customer's last name. |
customers[].name | string | Ryan Zhang | Full name of the customer. |
customers[].email | string | [email protected] | Customer's email address. |
customers[].phone | string | +8615014471143 | Customer's phone number. |
customers[].phone_area_code | string | null | Phone area code. |
customers[].contact_type | string | email | Contact type, either email or phone. |
customers[].accepts_marketing | boolean | true | Whether the customer is subscribed to emails. |
customers[].source | string | null | Source of the customer data. |
customers[].free_tax | boolean | false | Whether the customer is exempt from tax. |
customers[].registered | boolean | false | Indicates if the customer is registered. |
customers[].orders_count | integer | 0 | Number of orders placed by the customer. |
customers[].last_order_at | string | null | Timestamp of the customer's last order. |
customers[].total_spent | string | 0.00 | Total amount spent by the customer. |
customers[].tags | string | New Customer | Tags associated with the customer. |
customers[].created_at | string | 2024-04-17T11:10:33Z | Timestamp when the customer was created. |
customers[].updated_at | string | 2024-04-17T11:10:33Z | Timestamp when the customer was last updated. |
customers[].subscribed_flag | integer | 5 | Marketing subscription flag. |
customers[].sms_subscribed_flag | integer | 5 | SMS marketing subscription flag. |
customers[].accepts_sms_marketing | boolean | true | Whether the customer is subscribed to SMS. |
customers[].default_address | address object | Default address of the customer. | |
customers[].default_address.id | string | 9ffa8dc0-25b8-4424-832e-bab46fcfeb20 | Unique identifier for the default address. |
customers[].default_address.first_name | string | John | First name of the consignee. |
customers[].default_address.last_name | string | Smith | Last name of the consignee. |
customers[].default_address.company | string | `` | Company name. |
customers[].default_address.city | string | New York | City of the address. |
customers[].default_address.province | string | `` | Province or state. |
customers[].default_address.country | string | United States | Country name. |
customers[].default_address.zip | string | 10001 | Postal or ZIP code. |
customers[].default_address.phone | string | +1 123 456 7890 | Phone number associated with the address. |
customers[].default_address.address1 | string | 123 Main Street | Primary street address. |
customers[].default_address.address2 | string | Suite 100 | Secondary street address. |
customers[].default_address.country_code | string | US | ISO country code. |
customers[].addresses | array of address objects | Array containing all customer addresses. | |
customers[].addresses[].id | string | 9ffa8dc0-25b8-4424-832e-bab46fcfeb20 | Unique identifier for the address. |
customers[].addresses[].first_name | string | John | First name of the consignee. |
customers[].addresses[].last_name | string | Smith | Last name of the consignee. |
customers[].addresses[].company | string | `` | Company name. |
customers[].addresses[].city | string | New York | City of the address. |
customers[].addresses[].province | string | `` | Province or state. |
customers[].addresses[].country | string | United States | Country name. |
customers[].addresses[].zip | string | 10001 | Postal or ZIP code. |
customers[].addresses[].phone | string | +1 123 456 7890 | Phone number associated with the address. |
customers[].addresses[].address1 | string | 123 Main Street | Primary street address. |
customers[].addresses[].address2 | string | Suite 100 | Secondary street address. |
customers[].addresses[].country_code | string | US | ISO country code. |
customers[].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 | array | ["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 |
invalid limit input, for example, input251 in limit. | "Exceeds maximum limit of 250" | ||
| Unauthorized | The request is missing valid authentication credentials or the credentials provided are invalid. | Unauthorized | |
| 406 | Not Acceptable | invalid input in created_at_min | Created at min time format error |
invalid input in updated_at_max | Updated at min time format error | ||
invalid input in updated_at_max | Updated at max time format error | ||
invalid input in created_at_max | Created at max time format error |