# List customers

Building with an AI agent? Start at https://docs.payme.io/agents.md

- Sandbox: `GET https://payme-store-staging.payme.io/api/customers`
- Production: `GET https://payme-store.payme.io/api/customers`

## Credentials

- Header `Authorization: Bearer <token>`

Lists the seller's customers, one page at a time. `page` and `items_per_page` are required. Filter by status, name, email, phone or creation date, or search across the names, the email and the `guid`. Sort by first name, last name, email or creation date; without `sort_by` the order isn't defined.

Pass the date range in deep-object form, e.g. `?created_at[from]=2026-01-01&created_at[to]=2026-06-30`.

Send `Authorization: Bearer <auth_token>`, the token from [`POST /auth-tokens`](/products-and-customers/authentication/post-auth-token). Hosts, tokens and the error format: [Hosts, authentication and errors](/products-and-customers/authentication).

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | yes | Page number, from `1`. |
| `items_per_page` | query | integer | yes | Customers per page, from `1` to `100`. |
| `status` | query | integer | no | `0` – inactive, `1` – active, `2` – draft. |
| `search` | query | string | no | Case-insensitive text to find in the first, middle or last name, the full name, the `guid` or the email. |
| `first_name` | query | string | no | First name, exact match. |
| `last_name` | query | string | no | Last name, exact match. |
| `email` | query | string | no | Email address, exact match. |
| `mobile_number` | query | string | no | Phone number, exact match against the main or the additional phone. |
| `created_at[from]` | query | string | no | Created at or after this time: `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS`. |
| `created_at[to]` | query | string | no | Created at or before this time, in the same formats. |
| `sort_by` | query | string | no | `first_name`, `last_name`, `email` or `created_at`. |
| `sort_direction` | query | string | no | `asc` or `desc`. Default `desc`. Applies only together with `sort_by`. |

## Code samples

### curl

```bash
curl -X GET 'https://payme-store-staging.payme.io/api/customers?page=<page>&items_per_page=<items_per_page>' \
  -H 'Authorization: Bearer <YOUR_TOKEN>'
```

### Node.js

```javascript
const response = await fetch("https://payme-store-staging.payme.io/api/customers?page=<page>&items_per_page=<items_per_page>", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
});

console.log(await response.text());
```

### Python

```python
import requests

response = requests.get(
    "https://payme-store-staging.payme.io/api/customers?page=<page>&items_per_page=<items_per_page>",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$ch = curl_init('https://payme-store-staging.payme.io/api/customers?page=<page>&items_per_page=<items_per_page>');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <YOUR_TOKEN>',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
```

## Responses

### 200 — A page of customers. (success)

| Field | Type | Description |
| --- | --- | --- |
| `items` | array | The customers on this page. |
| `items[].guid` | string | Customer id (a UUID) assigned by PayMe. Use it in `/customers/{guid}`. |
| `items[].first_name` | string | First name. |
| `items[].middle_name` | string | Middle name. |
| `items[].last_name` | string | Last name. |
| `items[].email` | string | Email address. |
| `items[].phone_number` | string | Main phone number. You send it as `phone`. |
| `items[].additional_phone_number` | string | Second phone number. You send it as `additional_phone`. |
| `items[].address` | object | Postal address. You send these fields at the top level of the request. |
| `items[].address.country` | string | Country. |
| `items[].address.city` | string | City. |
| `items[].address.street` | string | Street. |
| `items[].address.building_number` | string | Building number, e.g. `12A`. |
| `items[].address.floor` | string | Floor. |
| `items[].address.zip` | string | Postal code. |
| `items[].company_name` | string | Company name. |
| `items[].description` | string | Your note about the customer. |
| `items[].birthday` | string | Date of birth, `YYYY-MM-DD`. |
| `items[].status` | integer | `0` – inactive, `1` – active, `2` – draft. |
| `items[].payment_tokens` | array | The customer's saved payment tokens. |
| `items[].payment_tokens[].token` | string | A payment token you saved for the customer. |
| `items[].payment_tokens[].token_data` | string | The JSON string you saved with the token, e.g. the card mask and brand. |
| `total` | integer | How many customers match the filters, across all pages. |
| `page` | integer | The page returned. |
| `items_per_page` | integer | The page size you asked for. |

```json
{
  "items": [
    {
      "guid": "6c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "first_name": "Dana",
      "middle_name": null,
      "last_name": "Levi",
      "email": "dana@example.com",
      "phone_number": "0501234567",
      "additional_phone_number": null,
      "address": {
        "country": "Israel",
        "city": "Tel Aviv",
        "street": "Rothschild",
        "building_number": "12A",
        "floor": "3",
        "zip": "6688101"
      },
      "company_name": "Example Ltd",
      "description": "Prefers email contact",
      "birthday": "1990-05-17",
      "status": 1,
      "payment_tokens": [
        {
          "token": "8f3a2c1d9e7b4a60",
          "token_data": "{\"card_mask\":\"4580 **** **** 0000\",\"card_brand\":\"visa\"}"
        }
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "items_per_page": 20
}
```

### 400 — A required parameter is missing or a parameter is invalid, e.g. `items_per_page` above `100`. (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_error_details` | string | What went wrong. Validation messages are in Hebrew unless you send `Accept-Language: en`. |
| `status_error_code` | integer | `501` for a validation error or a body that isn't valid JSON, `999` for any other error. |
| `validation_errors` | object | The fields that failed validation. Each key is a field name; its value maps each failed rule to a message. |
| `session` | string | Trace id of the request. Quote it when you contact PayMe support. |

```json
{
  "status_error_details": "Field validation failed.",
  "validation_errors": {
    "items_per_page": {
      "max": "The value must be less than max amount."
    }
  },
  "status_error_code": 501,
  "session": "f3a1c2b0-9e4d-11ef-8c1a-0242ac120002"
}
```

### 401 — The `Authorization` header is missing, or the access token is invalid or expired. Get a new token with `POST /refresh-exchanges` or `POST /auth-tokens`. (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_error_details` | string | What went wrong. |
| `status_error_code` | integer | `999`. |
| `session` | string | Trace id of the request. Quote it when you contact PayMe support. |

```json
{
  "status_error_details": "Unauthorized",
  "status_error_code": 999,
  "session": "f3a1c2b0-9e4d-11ef-8c1a-0242ac120002"
}
```

### 500 — Server error. Contact PayMe support and quote the `session`. (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_error_details` | string | What went wrong. |
| `status_error_code` | integer | `999`. |
| `session` | string | Trace id of the request. Quote it when you contact PayMe support. |