Skip to main content
GET
/
categories
List categories
curl --request GET \
  --url https://integrations.clopos.com/open-api/categories \
  --header 'x-brand: <api-key>' \
  --header 'x-token: <api-key>' \
  --header 'x-venue: <api-key>'
{
  "success": true,
  "data": [
    {
      "id": 123,
      "parent_id": 123,
      "name": "<string>",
      "slug": "<string>",
      "type": "PRODUCT",
      "color": "<string>",
      "status": 123,
      "depth": 123,
      "_lft": 123,
      "_rgt": 123,
      "properties": {},
      "children": [
        {}
      ],
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    }
  ],
  "total": 123,
  "time": 123,
  "timestamp": "2023-11-07T05:31:56Z",
  "unix": 123
}

​
Purpose

Allows you to retrieve your category tree, including subcategories, in a single call.

​
HTTP Request

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

​
Authorization

Include the following headers:
  • x-token
  • x-brand
  • x-venue

​
Query Parameters

​
page
integer
default:"1"
Page number for pagination (1-based).
​
limit
integer
default:"50"
Number of categories to return (1-999).
​
parent_id
integer
Filters records under a specific parent category.
​
type
string
Category type; PRODUCT, INGREDIENT, ACCOUNTING.
​
include_children
boolean
default:"true"
Include child categories in the response.
​
include_inactive
boolean
default:"false"
Return inactive categories.

​
Request Example

curl -X GET "https://integrations.clopos.com/open-api/categories?page=1&limit=20&filters%5B0%5D%5B0%5D=type&filters%5B0%5D%5B1%5D=PRODUCT" \
  -H "x-token: oauth_example_token" \
  -H "x-brand: openapitest" \
  -H "x-venue: 1"

​
Response

​
200 OK — List of categories

{
  "success": true,
  "data": [
    {
      "id": 1,
      "parent_id": null,
      "name": "Beverages",
      "slug": "beverages",
      "type": "PRODUCT",
      "color": "#3498db",
      "status": 1,
      "depth": 0,
      "_lft": 1,
      "_rgt": 8,
      "properties": {
        "visible": true,
        "sortable": true,
        "description": "All beverages and drinks"
      },
      "children": [
        {
        "id": 2,
        "parent_id": 1,
          "name": "Coffee",
          "slug": "coffee",
        "type": "PRODUCT",
          "status": 1,
          "depth": 1,
          "children": []
        }
      ],
      "created_at": "2024-01-20T16:00:00Z",
      "updated_at": "2024-01-20T16:00:00Z"
    }
  ],
  "total": 12,
  "time": 71,
  "timestamp": "2025-10-24 05:38:15",
  "unix": 1761284295
}

​
400 Bad Request — Parameter error

{
  "success": false,
  "error": "invalid_parameter",
  "message": "type must be one of product_category, ingredient_category, accounting_category"
}

​
Field Reference

​
Top-Level Fields

FieldTypeDescription
successbooleanIndicates if the request was successful.
dataarrayCategory objects.
totalnumberTotal number of categories.
timenumberResponse time (ms).
timestampstringISO 8601 date.
unixnumberUnix timestamp.

​
Category Object

FieldTypeDescription
idintegerUnique identifier.
parent_idintegerParent category ID, null for root.
namestringCategory name.
slugstringURL-friendly identifier.
typestringPRODUCT, INGREDIENT, ACCOUNTING.
statusinteger1 = active, 0 = inactive.
depthintegerHierarchy level.
_lft, _rgtintegerNested set boundaries.
colorstringHEX color.
propertiesobjectAdditional settings and visibility info.
childrenarraySubcategories.
created_atstringCreation time.
updated_atstringLast update time.

​
Notes

  • With the type parameter, you can call different category collections (menu, ingredient, accounting) from a single endpoint.
  • By sending include_children=false, you can retrieve only top-level categories; sub-branches are retrieved with separate calls.
  • Hierarchy values (_lft, _rgt, depth) allow you to resolve parent-child relationships using nested set logic.
  • To see inactive categories, send include_inactive=true; otherwise, they are hidden by default.
  • In a production environment, adjust pagination values (page, limit) according to the brand’s inventory size.

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

Query Parameters

​
page
integer
default:1

Page number for pagination (starts at 1)

Required range: x >= 1
​
limit
integer
default:50

Number of categories to return per page (1-999)

Required range: 1 <= x <= 999
​
parent_id
string | null

Filter to categories under a specific parent ID

​
type
enum<string>

Filter by category type

Available options:
PRODUCT,
INGREDIENT,
ACCOUNTING
​
include_children
boolean
default:true

Include nested child categories in the response

​
include_inactive
boolean
default:false

Whether to include inactive categories

Response

Categories retrieved successfully

​
success
boolean
​
data
object[]
​
total
integer
​
time
integer
​
timestamp
string<date-time>
​
unix
integer