Create Customer

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/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.

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

string

required

Customer’s full name. This field is required.

string

Customer’s email address.

string

Customer’s primary phone number. Must be unique across all customers.

string

Customer code/identifier. Must be unique across all customers.

string

Customer UUID identifier. Must be unique across all customers. If not provided, the system will generate one automatically.

string

Additional notes or description about the customer.

integer

ID of the customer group to assign this customer to.

integer

Customer’s gender. Use 1 for male, 2 for female, or null for unspecified.

string

Customer’s date of birth in YYYY-MM-DD format.

Request Examples

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

const customerData = {
  name: "John Doe",
  email: "john.doe@example.com",
  code: "CUST001",
  cid: "0f9654bc-9520-43d7-8109-317d9820f54c",
  phone: "+15551234567",
  description: "Test Customer",
  group_id: 1,
  gender: 1,
  date_of_birth: "1990-05-15"
};

const response = await fetch('https://integrations.clopos.com/open-api/v2/customers', {
  method: 'POST',
  headers: {
    'x-token': 'oauth_example_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(customerData)
});

const customer = await response.json();

import requests

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

customer_data = {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "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 = requests.post(url, headers=headers, json=customer_data)
customer = response.json()

Response

200 OK — Customer created successfully

{
  "success": true,
  "data": {
    "id": 14,
    "venue_id": 1,
    "cid": "0f9654bc-9520-43d7-8109-317d9820f54c",
    "group_id": 1,
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone": "+15551234567",
    "phones": [],
    "address": null,
    "address_data": [],
    "description": "Test Customer",
    "discount": 0,
    "spent": 0,
    "total_discount": 0,
    "total_bonus": 0,
    "receipt_count": 0,
    "gender": 1,
    "date_of_birth": "1990-05-15",
    "code": "CUST001",
    "source": null,
    "reference_id": null,
    "status": true,
    "can_use_loyalty_system": false,
    "is_verified": false,
    "created_at": "2025-11-14T08:31:17.000000Z",
    "updated_at": "2025-11-14T08:31:17.000000Z"
  }
}

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

Field	Type	Description
`name`	string	Customer’s full name.

Optional Fields

Field	Type	Description
`email`	string	Customer’s email address.
`phone`	string	Primary phone number. Must be unique.
`code`	string	Customer code/identifier. Must be unique.
`cid`	string	Customer UUID. Must be unique. Auto-generated if not provided.
`description`	string	Additional notes about the customer.
`group_id`	integer	ID of the customer group.
`gender`	integer	Gender: `1` = male, `2` = female, `null` = unspecified.
`date_of_birth`	string	Date of birth in `YYYY-MM-DD` format.

Response Fields

Field	Type	Description
`id`	integer	Unique customer identifier (auto-assigned).
`venue_id`	integer	Venue the customer was created in.
`cid`	string	UUID identifier for the customer.
`status`	boolean	Account status (defaults to `true`).
`can_use_loyalty_system`	boolean	Loyalty enrollment status (defaults to `false`).
`is_verified`	boolean	Verification status (defaults to `false`).
`created_at`	string	Creation timestamp (ISO 8601).
`updated_at`	string	Last update timestamp (ISO 8601).

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.
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.

Overview

Auth

Venues

Users

Customers

Categories

Station

Products

Price Lists

Sales

Orders

Receipts

Tables

Purpose

HTTP Request

Request Body

Request Examples

Response

200 OK — Customer created successfully

400 Bad Request — Validation error

409 Conflict — Duplicate unique field

Field Reference

Required Fields

Optional Fields

Response Fields

Notes

​Purpose

​HTTP Request

​Request Body

​Request Examples

​Response

​200 OK — Customer created successfully

​400 Bad Request — Validation error

​409 Conflict — Duplicate unique field

​Field Reference

​Required Fields

​Optional Fields

​Response Fields

​Notes

Purpose

HTTP Request

Request Body

Request Examples

Response

200 OK — Customer created successfully

400 Bad Request — Validation error

409 Conflict — Duplicate unique field

Field Reference

Required Fields

Optional Fields

Response Fields

Notes