List customers

Credentials

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. Hosts, tokens and the error format: Hosts, authentication and errors.

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

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

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

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

$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. 
{
  "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. 
{
  "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. 
{
  "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.