Skip to main content
GET
/
customers
List customers
curl --request GET \
  --url https://integrations.clopos.com/open-api/customers \
  --header 'x-brand: <api-key>' \
  --header 'x-token: <api-key>' \
  --header 'x-venue: <api-key>'
[
    {
        "id": 7,
        "venue_id": 1,
        "cid": "3bb96485-2d8e-404b-b25c-3b7ee4ef732a",
        "group_id": 1,
        "balance_id": 2868,
        "name": "Best User",
        "discount": 0,
        "email": null,
        "phones": [],
        "phone": "+994 50 333 22 11",
        "address": null,
        "description": "sadsad",
        "addresses": [],
        "address_data": null,
        "bonus_balance_id": null,
        "cashback_balance_id": null,
        "spent": 544.73,
        "total_discount": 59.25,
        "total_bonus": 0,
        "receipt_count": 3,
        "gender": null,
        "date_of_birth": null,
        "code": null,
        "created_at": "2024-07-19T19:11:02.000000Z",
        "updated_at": "2024-08-27T05:52:45.000000Z",
        "deleted_at": null,
        "source": null,
        "reference_id": null,
        "phone_verified_at": null,
        "status": true,
        "can_use_loyalty_system": false,
        "is_verified": false,
        "group": {
            "id": 1,
            "name": "My Customers",
            "discount_type": null,
            "discount_value": 10,
            "system_type": "my_customers",
            "created_at": "203-05-25T12:08:43.000000Z",
            "updated_at": "2024-02-27T07:43:09.000000Z",
            "deleted_at": null
        },
        "balance": {
            "id": 2868,
            "system_type": null,
            "venue_id": null,
            "name": "CUSTOMER:",
            "description": null,
            "type": "CUSTOMER",
            "amount": 0,
            "position": 0,
            "created_at": "2024-07-19T19:11:02.000000Z",
            "updated_at": "2024-07-19T19:11:02.000000Z",
            "deleted_at": null
        },
        "cashback_balance": {
            "type": "CASHBACK",
            "amount": 0,
            "name": "Customer cashback balance:da39a3e"
        }
    }
]
This endpoint retrieves a list of all customers with support for pagination, filtering, and including related data.

​
HTTP Request

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

​
Authorization

Include the following headers:
  • x-token
  • x-brand
  • x-venue

​
Query Parameters

​
page
integer
default:"1"
Page number for pagination (1-based).
​
limit
integer
default:"50"
Number of customers to return per page (1-999).
​
with[]
string
Include related data in the response. Supported values: group, balance, cashback_balance. You can include multiple with parameters.
​
filters
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/customers?page=1&limit=50" \
  -H "x-token: oauth_example_token" \
  -H "x-brand: openapitest" \
  -H "x-venue: 1"

​
Response Example

[
    {
        "id": 7,
        "venue_id": 1,
        "cid": "3bb96485-2d8e-404b-b25c-3b7ee4ef732a",
        "group_id": 1,
        "balance_id": 2868,
        "name": "Best User",
        "discount": 0,
        "email": null,
        "phones": [],
        "phone": "+994 50 333 22 11",
        "address": null,
        "description": "sadsad",
        "addresses": [],
        "address_data": null,
        "bonus_balance_id": null,
        "cashback_balance_id": null,
        "spent": 544.73,
        "total_discount": 59.25,
        "total_bonus": 0,
        "receipt_count": 3,
        "gender": null,
        "date_of_birth": null,
        "code": null,
        "created_at": "2024-07-19T19:11:02.000000Z",
        "updated_at": "2024-08-27T05:52:45.000000Z",
        "deleted_at": null,
        "source": null,
        "reference_id": null,
        "phone_verified_at": null,
        "status": true,
        "can_use_loyalty_system": false,
        "is_verified": false,
        "group": {
            "id": 1,
            "name": "My Customers",
            "discount_type": null,
            "discount_value": 10,
            "system_type": "my_customers",
            "created_at": "203-05-25T12:08:43.000000Z",
            "updated_at": "2024-02-27T07:43:09.000000Z",
            "deleted_at": null
        },
        "balance": {
            "id": 2868,
            "system_type": null,
            "venue_id": null,
            "name": "CUSTOMER:",
            "description": null,
            "type": "CUSTOMER",
            "amount": 0,
            "position": 0,
            "created_at": "2024-07-19T19:11:02.000000Z",
            "updated_at": "2024-07-19T19:11:02.000000Z",
            "deleted_at": null
        },
        "cashback_balance": {
            "type": "CASHBACK",
            "amount": 0,
            "name": "Customer cashback balance:da39a3e"
        }
    }
]

​
Customer Object

FieldTypeDescription
idintegerThe unique identifier for the customer.
namestringThe name of the customer.
phonestringThe primary phone number of the customer.
emailstring | nullThe email address of the customer.
group_idintegerThe ID of the customer group they belong to.
balanceobjectContains details about the customer’s store credit balance.
cashback_balanceobjectContains details about the customer’s cashback balance.
spentnumberThe total amount spent by the customer.
receipt_countintegerThe total number of receipts for the customer.
groupobjectAn object containing details of the customer’s group.
addressesarrayAn array of the customer’s saved addresses.
statusbooleanThe status of the customer account.
created_atstringThe timestamp when the customer was created.

Authorizations

​
x-token
string
header
required

Access token obtained from /auth endpoint

​
x-brand
string
header
required

Brand identifier

​
x-venue
string
header
required

Venue identifier

Query Parameters

​
page
integer
default:1

Page number for pagination (1-based)

Required range: x >= 1
​
limit
integer
default:50

Maximum number of customers to return per page (1-999)

Required range: 1 <= x <= 999
​
with[]
enum<string>[]

Include related data in the response. Supported values: group, balance, cashback_balance

Available options:
group,
balance,
cashback_balance
​
filters
string[][]

Filter customers by specific fields. Use array notation: filters[0][0]=field_name&filters[0][1]=value. Supported fields: name, phones, group_id

​
search
string

Search customers by name or email (legacy parameter, consider using filters instead)

Response

200 - application/json

Customers retrieved successfully

​
data
object[]
​
pagination
object