Skip to main content
The Clopos API uses RESTful endpoints with JSON payloads and standard HTTP status codes.

​
Base URLs

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

​
Authentication

All API endpoints require three specific headers for authentication:
  • x-brand - Your brand identifier
  • x-venue - Your venue identifier
  • x-token - Access token from /auth endpoint
1

Get API credentials

Obtain your client_id, client_secret, brand, and venue_id from your Clopos dashboard
2

Generate access token

Exchange your credentials for an access token using the /auth endpoint
3

Include required headers

Add all three headers to every API request (except /auth)

​
Required Headers

curl -X GET https://integrations.clopos.com/open-api/products \
  -H "x-brand: your_brand" \
  -H "x-venue: your_venue_id" \
  -H "x-token: your_access_token" \
  -H "Content-Type: application/json"

​
Get Access Token

First, authenticate with your credentials: 
curl -X POST https://integrations.clopos.com/open-api/auth \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "brand": "your_brand",
    "venue_id": "your_venue_id"
  }'

​
Rate Limits

API requests are rate limited to ensure fair usage:
  • 100 requests per minute per API key
  • 1000 requests per hour per API key
Rate limit headers are included in every response: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1640995200
When rate limits are exceeded, the API returns a 429 Too Many Requests status code.

​
Error Handling

The API uses standard HTTP status codes and returns detailed error information: 
{
  "error": "invalid_parameter",
  "message": "The 'limit' parameter must be between 1 and 100",
  "details": {
    "parameter": "limit",
    "provided_value": 150,
    "valid_range": "1-100"
  }
}

​
Common Status Codes

Status CodeDescription
200Success
201Created
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing token
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error

​
Pagination

List endpoints support pagination using limit and offset parameters: 
{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 150,
    "total_pages": 8
  }
}

​
Idempotency

POST requests support idempotency using the Idempotency-Key header: 
curl -X POST https://integrations.clopos.com/open-api/orders \
  -H "x-brand: your_brand" \
  -H "x-venue: your_venue_id" \
  -H "x-token: your_access_token" \
  -H "Idempotency-Key: your-unique-key" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "cust_123", "line_items": [...]}'