Retrieve a list of customers associated with a merchant's account.
The Find All Customers endpoint retrieves a list of customers associated with a merchant's account. This includes all stored customer records that can be filtered, sorted, and searched using flexible query parameters. If no matching customers are found, the data array in the response will be empty.
Key Features
- Retrieve All Customers: Access a comprehensive list of customer records tied to the merchant account.
- Search and Filter: Supports advanced filtering by fields such as name, email, company, and custom keywords.
- Sorting Options: Allows sorting results by specific attributes like
firstnameorcreated_atin ascending or descending order. - Integration with Update Customer: Use the Update a Customer endpoint to modify customer details retrieved from this endpoint.
Usage Notes
Query Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
firstname | string | Filter customers by first name. | /customer?firstname=James |
lastname | string | Filter customers by last name. | /customer?lastname=Wilson |
email | string | Search customers by email. | /[email protected] |
reference | string | Search by a custom reference field. | /customer?reference=order123 |
keywords[] | array | Search across multiple fields using keywords. | /customer?keywords[]=James&keywords[]=123 |
Sorting and Ordering Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
sort | string | Attribute to sort by (e.g., firstname, lastname). | /customer?sort=firstname&order=ASC |
order | string | Sorting order, either ascending (ASC) or descending (DESC). | /customer?sort=created_at&order=DESC |
Response Structure
| Code | Response | Description |
|---|---|---|
| 200 | Success | Returns a list of matching customer records. |
| 400 | Bad Request | Invalid query parameters or malformed request. |
| 401 | Unauthorized | API key invalid or missing. |
| 500 | Internal Server Error | An unexpected error occurred on the server. |
Important Considerations
Keyword Searches: Using the keywords[] parameter performs a broad search across most customer fields but can be slower, especially with large datasets.
Empty Results: If no customers match the query, the data array in the response will be empty, and the total will be 0.
Sorting Defaults: If no sort parameter is provided, results are ordered by created_at in descending order (DESC) by default.
Pagination: For larger datasets, consider implementing pagination for better performance.
Best Practices
- Use targeted filters (e.g.,
emailorreference) to narrow down results for faster response times. - Combine multiple query parameters to refine searches, such as
/customer?firstname=James&[email protected]. - When using
keywords[], limit the number of terms for optimal performance.