Skip to main content

​
Core concepts

Before building against the API, it helps to understand the four identifiers that appear on every v2 request: brand, venue, integrator, and the JWT that ties them together.

​
Brand

A brand is the top-level tenant on the Clopos platform. Every restaurant chain, cloud kitchen, or coffee shop operator has its own brand, identified by a short string such as openapitest. All data — venues, products, orders, receipts — lives inside a brand. You receive your brand identifier from Clopos when your account is provisioned.

​
Venue

A venue is a physical location that belongs to a brand — a single restaurant, branch, or kiosk. A brand can have one venue or hundreds. Venues are identified by numeric IDs (for example, venue_id: 1). Each JWT is issued with a default venue_id encoded inside it. You can override it on any request with the optional x-venue header, which is useful when a single integration needs to operate across multiple venues under the same brand without re-authenticating. 
# Default venue (from the JWT)
curl "https://integrations.clopos.com/open-api/v2/products" \
  -H "x-token: eyJhbGciOi..."

# Override the venue for this request only
curl "https://integrations.clopos.com/open-api/v2/products" \
  -H "x-token: eyJhbGciOi..." \
  -H "x-venue: 7"

​
Integrator

An integrator represents the third-party system talking to the Clopos API — a delivery marketplace, a loyalty platform, an ERP connector, and so on. Each integrator is registered with Clopos and receives a unique integrator_id. Integrators are a v2 concept and are required on every authentication call. They allow Clopos to:
  • Attribute traffic and rate limits to a specific partner.
  • Gate access to experimental or test-only brands.
  • Revoke a single partner’s access without rotating every client credential.

​
Test vs production integrators

Integrators are flagged as either is_test: true or is_test: false. The rule enforced on both /v2/auth and every authenticated endpoint is:
A test integrator (is_test: true) can only call non-production brands. If a test integrator attempts to call a production brand, the API rejects the request with the error "Integrator is in test mode. But brand is not in test mode".
Use a test integrator while you are building and verifying your integration against a sandbox brand. When you are ready to go live against a real brand, request a production integrator_id.

​
JWT access token

Once you call /v2/auth with client_id, client_secret, brand, and integrator_id, Clopos returns a signed JWT that encodes all of the above plus the default venue_id and upstream authentication state. That is why authenticated v2 requests need only a single header (x-token) — everything else is already inside the token. 
┌──────────────────── JWT payload ────────────────────┐
│  brand           your brand identifier              │
│  venue_id        default venue (override with       │
│                  x-venue header)                    │
│  integrator_id   your integrator identity           │
│  stage           brand environment (test / prod)    │
│  expires_at      Unix timestamp, ~1h from issue     │
└──────────────────────────────────────────────────────┘
Tokens are short-lived. Refresh them a little before expires_at rather than waiting for a 401 Token expired. See Authentication for the full flow and code examples.

​
Putting it together

A typical v2 request therefore carries:
  1. A JWT in x-token that authenticates who is calling (integrator) and where they are calling (brand + default venue).
  2. Optionally x-venue to target a different venue under the same brand.
  3. The request body or query parameters for the endpoint itself.
curl -X GET "https://integrations.clopos.com/open-api/v2/receipts?limit=20" \
  -H "x-token: eyJhbGciOi..." \
  -H "x-venue: 3"
All interaction on v2 is currently synchronous and client-initiated. Webhooks are on the roadmap; until they ship, poll the relevant list endpoints with a sensible interval, keeping the rate limits in mind.