get
https://{subdomain}.myshoplaza.com/openapi/2025-06/customers
Retrieve a list of all customers with pagination.
Requiresread_customeraccess scope.
The Get Customer List API retrieves a paginated list of all customers from the system. The response is paginated using cursor-based pagination for efficient data retrieval.
This API is especially useful for:
- filter customers by various criteria including creation time, last update time, specific customer IDs, email addresses, contact information, and more.
Request Parameters
Public Request Parameters
Query Parameters
| Parameter | Type | Required | Description | Example Value |
|---|---|---|---|---|
cursor | string | No | A cursor used for pagination to navigate through the customer list. | "eyJpZCI6IjEwMDAiLCJ..." |
page_size | int32 | No | Specifies the number of customers to retrieve per page. The default value is 10, and the maximum allowed value is 250. | 20 |
ids | array of strings | No | A list of specific customer IDs to retrieve. | ["cust_001", "cust_002"] |
created_at_min | string | No | Filters customers created after this date. The date should be in UTC (0 timezone) and formatted as ISO-8601. | "2023-01-01T00:00:00Z" |
created_at_max | string | No | Filters customers created before this date. The date should be in UTC (0 timezone) and formatted as ISO-8601. | "2023-12-31T23:59:59Z" |
updated_at_min | string | No | Filters customers last updated after this date. The date should be in UTC (0 timezone) and formatted as ISO-8601. | "2023-06-01T00:00:00Z" |
updated_at_max | string | No | Retrieve customers last updated before this date. It's in UTC(0 timezone), formatted as ISO-8601. | "2023-10-31T23:59:59Z" |
email | string | No | Filter customers by email. | "[email protected]" |
contact | string | No | Filter customers by contact information (email or phone). | "+1234567890" |
Response Explanation
Public Response Parameters
Successful Response
| Field | Type | Example | Description |
|---|---|---|---|
code | string | "success" | Status code of the response |
message | string | Descriptive message of the response | |
customers | array of customer object | 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 | Zhan | Customer's last name. |
customers[].name | string | Ryan Zhan | Full name of the customer. |
customers[].email | string | [email protected] | Customer's email address. |
customers[].phone | string | +86 1231231234 | 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. |
data.customer.tags | array of string | ["New Customer"] | array of tag strings. |
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[].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. |
data.has_more | boolean | true | true if there is more results, others else |
data.cursor | string | 165618e4-3243-4cd7-abc3-1234567890ab | A cursor used for pagination to navigate through the list. |
Error Response
| Field | Type | Example | Description |
|---|---|---|---|
code | string | InvalidParameter | Error http message |
message | string | `` | Error message |