🔒
Requires read_customer access 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

📘
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.	"customer@example.com"
`contact`	string	No	Filter customers by contact information (email or phone).	"+1234567890"

Response Explanation

Public Response Parameters

📘
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	`test@shoplazza.com`	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

API Structure Overview