---
api: 'Merchant API'
---

# Retrieve a customer list

Get a paginated list of your customer profiles.

| Filtering | Pagination |
| --------- | ---------- |
| Filter the customers that you want to retrieve, for example, only retrieve customers created within a specific date range. <br/><br/>Parameters used for filtering:<br/><ul><li>`from`</li><li>`to`</li></ul> | View customers without loading all of them at once, for example, return a specified number of customers per page. <br/><br/>Parameters used for pagination:<br/><ul><li>`limit`</li><li>`page_token`</li></ul> |

To paginate through all results:

1. Make an initial request with the desired `limit` and any filter parameters.
1. If more results are available, the response includes a `next_page_token`.
1. Pass `next_page_token` as `page_token` in your next request, keeping all other parameters unchanged.
1. Repeat until `next_page_token` is no longer present in the response.

## Endpoint

GET `/api/customers`

## Parameters

### query parameters

- `limit` (integer, optional)
  Maximum number of records to return. Used for **pagination**.

- `page_token` (string, optional)
  Token for retrieving the next page of results. Used for **pagination**.
  
  To paginate through results:
  
    1. Make an initial request with the desired `limit`.
    1. The response will include a `next_page_token` if more results are available.
    1. Use that token in the `page_token` parameter of your next request.
    1. Repeat until `next_page_token` is not present.
  
  :::note
  When using `page_token`, you must include all query parameters from the initial request (such as `from`, `to`, or other filter parameters) to maintain consistent filtering across pages.
  :::

- `from` (string, optional)
  Filter records created from this date/time. Used for **filtering**.

- `to` (string, optional)
  Filter records created until this date/time. Used for **filtering**.

## Returns

### 200

OK

#### Response attributes

- `next_page_token` (string | null, optional)
    Token for retrieving the next page of results. Use this token as the value of the `page_token` query parameter in your next request to retrieve the next page.
    
    If not present, there are no more results to retrieve.
- `customers` (array of object)
    List of customers.
  - `customers[].id` (string)
      Unique identifier for the customer.
  - `customers[].full_name` (string, optional)
      The full name of the customer.
  - `customers[].email` (string)
      The email address of the customer.
  - `customers[].phone` (string, optional)
      The phone number of the customer in [E.164 format](https://en.wikipedia.org/wiki/E.164).
  - `customers[].created_at` (string)
      The date and time the customer was created.
  - `customers[].updated_at` (string)
      The date and time the customer was last updated.

## Error responses

| HTTP status code | Description |
| --- | --- |
| 401 | Unauthorized |