Skip to main content
POST
/
customers
Create customer
curl --request POST \
  --url https://integrations.clopos.com/open-api/customers \
  --header 'Content-Type: application/json' \
  --header 'x-brand: <api-key>' \
  --header 'x-token: <api-key>' \
  --header 'x-venue: <api-key>' \
  --data '{
  "name": "John Doe"
}'
{
  "success": true,
  "data": {
    "id": "<string>",
    "name": "<string>",
    "email": "[email protected]",
    "phone": "<string>",
    "group_id": 123,
    "balance": {
      "id": 123,
      "amount": 123,
      "type": "<string>"
    },
    "cashback_balance": {
      "id": 123,
      "amount": 123,
      "type": "<string>"
    },
    "group": {
      "id": 123,
      "name": "<string>",
      "discount_type": "<string>",
      "discount_value": 123,
      "system_type": "<string>",
      "total_amount": 123,
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "deleted_at": "2023-11-07T05:31:56Z"
    },
    "created_at": "2023-11-07T05:31:56Z"
  },
  "message": "<string>",
  "time": 123,
  "timestamp": "2023-11-07T05:31:56Z",
  "unix": 123
}

​
Purpose

Create a new customer in the Clopos system. This endpoint allows you to register customers with their contact information, assign them to customer groups, and set up their profile details.

​
HTTP Request

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

​
Authorization

The following custom headers are required:
  • x-token
  • x-brand
  • x-venue
  • Content-Type: application/json
The fields code, phone, and cid are unique. If you attempt to create a customer with duplicate values for any of these fields, the API will return an error.

​
Request Body

​
name
string
required
Customer’s full name. This field is required.
​
email
string
Customer’s email address.
​
phone
string
Customer’s primary phone number. Must be unique across all customers.
​
code
string
Customer code/identifier. Must be unique across all customers.
​
cid
string
Customer UUID identifier. Must be unique across all customers. If not provided, the system will generate one automatically.
​
description
string
Additional notes or description about the customer.
​
group_id
integer
ID of the customer group to assign this customer to.
​
gender
integer
Customer’s gender. Use 1 for male, 2 for female, or null for unspecified.
​
date_of_birth
string
Customer’s date of birth in YYYY-MM-DD format.

​
Request Examples

curl --location 'https://integrations.clopos.com/open-api/customers' \
  --header 'accept: application/json, text/plain, */*' \
  --header 'x-token: oauth_example_token' \
  --header 'x-brand: openapitest' \
  --header 'x-venue: 1' \
  --header 'content-type: application/json' \
  --data-raw '{
    "name": "John Doe",
    "email": "[email protected]",
    "code": "CUST001",
    "cid": "0f9654bc-9520-43d7-8109-317d9820f54c",
    "phone": "+15551234567",
    "description": "Test Customer",
    "group_id": 1,
    "gender": 1,
    "date_of_birth": "1990-05-15"
}'

​
Response

​
200 OK — Customer created successfully

{
    "success": true,
    "data": {
        "name": "John Doe",
        "email": "[email protected]",
        "code": "CUST001",
        "cid": "0f9654bc-9520-43d7-8109-317d9820f54c",
        "phone": "+15551234567",
        "description": "Test Customer",
        "group_id": 1,
        "gender": 1,
        "date_of_birth": "1990-05-15",
        "balance_id": 1017,
        "venue_id": 1,
        "updated_at": "2025-11-14T08:31:17.000000Z",
        "created_at": "2025-11-14T08:31:17.000000Z",
        "id": 14,
        "can_use_loyalty_system": false,
        "is_verified": false,
        "balance": {
            "id": 1017,
            "venue_id": null,
            "system_type": null,
            "name": "CUSTOMER:",
            "description": null,
            "type": "CUSTOMER",
            "amount": 0,
            "position": 0,
            "created_at": "2025-11-14T08:31:17.000000Z",
            "updated_at": "2025-11-14T08:31:17.000000Z",
            "deleted_at": null
        },
        "cashback_balance": {
            "type": "CASHBACK",
            "amount": 0,
            "name": "Customer cashback balance:da39a3e"
        },
        "service_data": [],
        "group": {
            "id": 1,
            "name": "My Customers",
            "discount_type": null,
            "discount_value": 0,
            "system_type": "my_customers",
            "created_at": "2025-08-16T15:21:15.000000Z",
            "updated_at": "2025-08-16T15:21:15.000000Z",
            "deleted_at": null
        }
    },
    "message": "Əməliyyat uğurla həyata keçirildi",
    "time": 162,
    "timestamp": "2025-11-14 08:31:17",
    "unix": 1763109077
}

​
400 Bad Request — Validation error

{
    "success": false,
    "message": "Validation failed",
    "error": "The name field is required."
}

​
409 Conflict — Duplicate unique field

{
    "success": false,
    "message": "Customer with this phone number already exists",
    "error": "duplicate_phone"
}

​
Field Reference

​
Required Fields

FieldTypeDescription
namestringCustomer’s full name.

​
Optional Fields

FieldTypeDescription
emailstringCustomer’s email address.
phonestringPrimary phone number. Must be unique.
codestringCustomer code/identifier. Must be unique.
cidstringCustomer UUID. Must be unique. Auto-generated if not provided.
descriptionstringAdditional notes about the customer.
group_idintegerID of the customer group.
genderintegerGender: 1 = male, 2 = female, null = unspecified.
date_of_birthstringDate of birth in YYYY-MM-DD format.

​
Notes

  • The name field is required and cannot be empty.
  • The fields code, phone, and cid must be unique. Attempting to create a customer with duplicate values will result in a 409 Conflict error.
  • If cid is not provided, the system will automatically generate a UUID for the customer.
  • Upon successful creation, the customer is automatically assigned a balance_id and a balance account is created.
  • The response includes the customer’s group information if group_id was provided.
  • The can_use_loyalty_system and is_verified fields are set to false by default for new customers.

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

Body

application/json

Customer details

​
name
string
required

Customer's full name (required)

Example:

"John Doe"

​
email
string<email>

Customer's email address

Example:

"[email protected]"

​
phone
string

Customer's primary phone number. Must be unique.

Example:

"+15551234567"

​
code
string

Customer code/identifier. Must be unique.

Example:

"CUST001"

​
cid
string<uuid>

Customer UUID identifier. Must be unique. Auto-generated if not provided.

Example:

"0f9654bc-9520-43d7-8109-317d9820f54c"

​
description
string

Additional notes or description about the customer

Example:

"Test Customer"

​
group_id
integer

ID of the customer group to assign this customer to

Example:

1

​
gender
integer | null

Customer's gender: 1 = male, 2 = female, null = unspecified

Example:

1

​
date_of_birth
string<date>

Customer's date of birth in YYYY-MM-DD format

Example:

"1990-05-15"

Response

Customer created successfully

​
success
boolean
​
data
object
​
message
string
​
time
integer
​
timestamp
string<date-time>
​
unix
integer