Quick Start Guide

Get started with the Clopos Open API in just a few simple steps. This guide will walk you through authentication and making your first API request.

Prerequisites

Before you begin, make sure you have:

Client ID & Client Secret

Generated by the Clopos customer in their back office, under Add-ons → Open API

Brand

The customer’s brand identifier, shared with you along with the credentials

Integrator ID

Required for v2 authentication. Issued by Clopos — request one via this form.

Support

Stuck on any of the above? Email dev@clopos.com

Only the integrator_id is issued by Clopos. The Client ID, Client Secret, and brand come from the customer you are integrating with — see Authentication for the exact back office steps to send them.

Step 1: Authenticate

Exchange your credentials for a JWT by calling the v2 auth endpoint. Note that v2 requires an integrator_id and no longer accepts venue_id in the request body.

curl -X POST https://integrations.clopos.com/open-api/v2/auth \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "{{client_id}}",
    "client_secret": "{{client_secret}}",
    "brand": "{{brand}}",
    "integrator_id": "{{integrator_id}}"
  }'

const response = await fetch('https://integrations.clopos.com/open-api/v2/auth', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    client_id: '{{client_id}}',
    client_secret: '{{client_secret}}',
    brand: '{{brand}}',
    integrator_id: '{{integrator_id}}'
  })
});

const data = await response.json();
const accessToken = data.token;

// The only header needed for subsequent v2 requests
const apiHeaders = {
  'x-token': accessToken
};

import requests

url = "https://integrations.clopos.com/open-api/v2/auth"
payload = {
    "client_id": "{{client_id}}",
    "client_secret": "{{client_secret}}",
    "brand": "{{brand}}",
    "integrator_id": "{{integrator_id}}"
}

response = requests.post(url, json=payload)
data = response.json()
access_token = data["token"]

# The only header needed for subsequent v2 requests
api_headers = {
    "x-token": access_token
}

You’ll receive a response like this:

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expires_at": 1767852332,
  "message": "Authentication successful"
}

Save the token value — you’ll need it in the x-token header on every subsequent request. The token is a JWT that encodes your brand, venue_id, and integrator_id, so you no longer need to send x-brand or x-venue. Tokens expire after expires_in seconds (typically 1 hour).

Don’t have an integrator_id yet? Request one from Clopos by filling out this form. Missing the client_id or client_secret? Ask your customer to generate them under Add-ons → Open API in their back office. See the Authenticate reference for details.

Step 2: Make Your First Request

Now let’s fetch the list of products using your access token:

curl -X GET "https://integrations.clopos.com/open-api/v2/products?limit=5" \
  -H "x-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

const response = await fetch('https://integrations.clopos.com/open-api/v2/products?limit=5', {
  headers: apiHeaders  // Using the headers from Step 1
});

const products = await response.json();
console.log('Products:', products.data);

import requests

url = "https://integrations.clopos.com/open-api/v2/products"
params = {"limit": 5}

response = requests.get(url, headers=api_headers, params=params)  # Using headers from Step 1
products = response.json()
print("Products:", products["data"])

You’ll receive a response with your products:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Coffee",
      "price": "4.50",
      "status": 1,
      "category_id": 3
    },
    {
      "id": 2,
      "name": "Sandwich",
      "price": "8.99",
      "status": 1,
      "category_id": 5
    }
  ],
  "total": 150,
  "time": 45
}

Step 3: Explore More Endpoints

Now that you’re authenticated, you can explore other endpoints:

Get Categories

Fetch product categories

Create Order

Place a new order

Get Customers

Retrieve customer data

List Receipts

Browse open and closed receipts

Next Steps

Authentication Guide - Learn more about token management
API Reference - Explore all available endpoints
Contact Support - Get help with integration

You’re now ready to build amazing applications with the Clopos Open API! 🚀

Introduction

Concepts

Quick Start

Quick Start Guide

Prerequisites

Client ID & Client Secret

Brand

Integrator ID

Support

Step 1: Authenticate

Step 2: Make Your First Request

Step 3: Explore More Endpoints

Get Categories

Create Order

Get Customers

List Receipts

Next Steps

​Quick Start Guide

​Prerequisites

Client ID & Client Secret

Brand

Integrator ID

Support

​Step 1: Authenticate

​Step 2: Make Your First Request

​Step 3: Explore More Endpoints

Get Categories

Create Order

Get Customers

List Receipts

​Next Steps

Quick Start Guide

Prerequisites

Step 1: Authenticate

Step 2: Make Your First Request

Step 3: Explore More Endpoints

Next Steps