List All Customers

This endpoint retrieves a list of all customers with support for pagination, filtering, and including related data.

There is no search parameter on this endpoint. To find customers by name or phone, use the filters parameter described below.

HTTP Request

GET https://integrations.clopos.com/open-api/v2/customers

This endpoint requires authentication. Include your JWT in the x-token header. See Authentication for how to obtain a token and Errors for error responses.

Query Parameters

integer

default:"1"

Page number for pagination (1-based).

integer

default:"50"

Number of customers to return per page (1-999).

string

Include related data in the response. Supported values: group. You can include multiple with parameters.

array

Filter customers by specific fields. Filters use array notation: filters[0][0]=field_name&filters[0][1]=value. Multiple filters can be combined using different indices (e.g., filters[0], filters[1]). Supported filter fields: - name: Filter by customer name (partial match) - phones: Filter by phone number (searches in all phone numbers) - group_id: Filter by customer group ID Filter Examples: - Filter by name: filters[0][0]=name&filters[0][1]=John - Filter by phone: filters[0][0]=phones&filters[0][1]=15551234567 - Multiple filters: filters[0][0]=name&filters[0][1]=John&filters[1][0]=phones&filters[1][1]=15551234567

Request Examples

curl --location "https://integrations.clopos.com/open-api/v2/customers?page=1&limit=50" \
  -H "x-token: oauth_example_token" \

curl --location --globoff 'https://integrations.clopos.com/open-api/v2/customers?page=1&limit=50&with[0]=group&filters[0][0]=name&filters[0][1]=John&filters[1][0]=phones&filters[1][1]=15551234567' \
  -H "x-token: oauth_example_token" \

// Basic request
const params = new URLSearchParams({
    page: "1",
    limit: "50",
});

// With filters and relations
const paramsWithFilters = new URLSearchParams({
    page: "1",
    limit: "50",
    "with[0]": "group",
    "filters[0][0]": "name",
    "filters[0][1]": "John",
    "filters[1][0]": "phones",
    "filters[1][1]": "15551234567",
});

const response = await fetch(
    `https://integrations.clopos.com/open-api/v2/customers?${paramsWithFilters}`,
    {
        headers: {
            "x-token": "oauth_example_token",
        },
    },
);

const customers = await response.json();

import requests

url = "https://integrations.clopos.com/open-api/v2/customers"
headers = {
    "x-token": "oauth_example_token",
}

# Basic request
params = {
    "page": 1,
    "limit": 50
}

# With filters and relations
params_with_filters = {
    "page": 1,
    "limit": 50,
    "with[0]": "group",
    "filters[0][0]": "name",
    "filters[0][1]": "John",
    "filters[1][0]": "phones",
    "filters[1][1]": "15551234567"
}

response = requests.get(url, headers=headers, params=params_with_filters)
customers = response.json()

Response Example

{
    "success": true,
    "data": [
        {
            "id": 1,
            "venue_id": 1,
            "cid": "1266eb42-9bdb-4e93-9fe0-3603c110f128",
            "group_id": 5,
            "name": "Rahid Akhundzada",
            "discount": 0,
            "email": null,
            "phones": [],
            "phone": "+994505355757",
            "address": null,
            "description": null,
            "address_data": [],
            "spent": 1162.8,
            "total_discount": 1.7,
            "total_bonus": 0,
            "receipt_count": 9,
            "gender": 1,
            "date_of_birth": null,
            "code": null,
            "source": null,
            "reference_id": null,
            "status": true,
            "can_use_loyalty_system": false,
            "is_verified": false,
            "created_at": "2026-01-31T16:23:27.000000Z",
            "updated_at": "2026-03-12T16:37:15.000000Z"
        },
        {
            "id": 2,
            "venue_id": 1,
            "cid": "24d7865f-f1bc-4948-be6a-e497d20bad0c",
            "group_id": 1,
            "name": "Reyal",
            "discount": 0,
            "email": null,
            "phones": [],
            "phone": null,
            "address": null,
            "description": null,
            "address_data": [],
            "spent": 714,
            "total_discount": 0,
            "total_bonus": 0,
            "receipt_count": 10,
            "gender": null,
            "date_of_birth": null,
            "code": null,
            "source": null,
            "reference_id": null,
            "status": true,
            "can_use_loyalty_system": false,
            "is_verified": false,
            "created_at": "2026-02-02T19:45:10.000000Z",
            "updated_at": "2026-02-02T23:37:33.000000Z"
        }
    ],
    "total": 7
}

Field Reference

Customer Object

Field	Type	Description
`id`	integer	Unique customer identifier.
`cid`	string	UUID identifier for the customer.
`venue_id`	integer	The venue this customer belongs to.
`group_id`	integer	The ID of the customer group they belong to.
`name`	string	Customer’s full name.
`email`	string (nullable)	Customer’s email address.
`phone`	string (nullable)	Primary phone number.
`phones`	array	Additional phone numbers.
`address`	string (nullable)	Customer’s address.
`address_data`	array	Structured address entries with type, source, and formatted address.
`description`	string (nullable)	Additional notes about the customer.
`discount`	number	Customer-level discount value.
`spent`	number	Total amount spent by the customer.
`total_discount`	number	Total discount amount received across all receipts.
`total_bonus`	number	Total bonus amount used.
`receipt_count`	integer	Total number of receipts for the customer.
`gender`	integer (nullable)	Gender: `1` = male, `2` = female, `null` = unspecified.
`date_of_birth`	string (nullable)	Date of birth in `YYYY-MM-DD` format.
`code`	string (nullable)	Customer code/identifier.
`source`	string (nullable)	Where the customer was created from (e.g., `LOYALTY`).
`reference_id`	string (nullable)	External reference ID for third-party integrations.
`status`	boolean	Whether the customer account is active.
`can_use_loyalty_system`	boolean	Whether the customer is enrolled in the loyalty system.
`is_verified`	boolean	Whether the customer’s identity has been verified.
`created_at`	string	Timestamp when the customer was created (ISO 8601).
`updated_at`	string	Timestamp when the customer was last updated (ISO 8601).

Notes

Filterable fields: name (partial match), phones (searches across all phone numbers), group_id (exact match). Note: use phones (plural) — the singular phone field is not filterable.
Sortable fields: id, cid, group_id, name, email, address, created_at, updated_at.
The search query parameter is listed in some older references but is not implemented — use filters instead.

Overview

Auth

Venues

Users

Customers

Categories

Station

Products

Price Lists

Sales

Orders

Receipts

Tables

HTTP Request

Query Parameters

Request Examples

Response Example

Field Reference

Customer Object

Notes

​HTTP Request

​Query Parameters

​Request Examples

​Response Example

​Field Reference

​Customer Object

​Notes

HTTP Request

Query Parameters

Request Examples

Response Example

Field Reference

Customer Object

Notes