Categories & Brands API
The Categories and Brands endpoints provide company-wide master taxonomy data. Smart POS terminals, self-service kiosks, and eCommerce storefronts use these resources to build department hierarchies, menu navigation tiles, and brand filtering widgets.
All category and brand records are automatically scoped to your company context based on the authorized API key.
1. Categories Hierarchy
Tracepos categories support parent-child hierarchies. Top-level categories have parent_id = null, and their subcategories are nested in the children array.
List All Categories
Retrieve the complete category tree for your company. Root categories contain their nested sub-departments.
/api/v1/public/categoriesScope: readHeaders
| Header | Type | Required | Description |
|---|---|---|---|
X-Tracepos-Public-Key | String | Yes | Warehouse public API key |
X-Tracepos-Secret-Key | String | Yes | Warehouse secret API key |
Accept | String | Yes | application/json |
Code Samples
curl -X GET "https://app.tracepos.net/api/v1/public/categories" \
-H "X-Tracepos-Public-Key: YOUR_PUBLIC_KEY" \
-H "X-Tracepos-Secret-Key: YOUR_SECRET_KEY" \
-H "Accept: application/json"
const axios = require('axios');
async function getCategories() {
const response = await axios.get('https://app.tracepos.net/api/v1/public/categories', {
headers: {
'X-Tracepos-Public-Key': process.env.TRACEPOS_PUBLIC_KEY,
'X-Tracepos-Secret-Key': process.env.TRACEPOS_SECRET_KEY,
'Accept': 'application/json',
},
});
return response.data.data;
}
import os
import requests
headers = {
"X-Tracepos-Public-Key": os.getenv("TRACEPOS_PUBLIC_KEY"),
"X-Tracepos-Secret-Key": os.getenv("TRACEPOS_SECRET_KEY"),
"Accept": "application/json",
}
response = requests.get("https://app.tracepos.net/api/v1/public/categories", headers=headers)
categories = response.json().get("data", [])
<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;
$client = new Client(['base_uri' => 'https://app.tracepos.net/api/v1/public/']);
$response = $client->get('categories', [
'headers' => [
'X-Tracepos-Public-Key' => getenv('TRACEPOS_PUBLIC_KEY'),
'X-Tracepos-Secret-Key' => getenv('TRACEPOS_SECRET_KEY'),
'Accept' => 'application/json',
],
]);
$categories = json_decode($response->getBody()->getContents(), true)['data'];
Response (200 OK)
{
"status": "success",
"data": [
{
"id": 12,
"name": "Beverages",
"slug": "beverages",
"parent_id": null,
"image": "https://app.tracepos.net/uploads/cat-beverages.png",
"children": [
{
"id": 45,
"name": "Energy Drinks",
"slug": "energy-drinks",
"parent_id": 12,
"image": null
},
{
"id": 46,
"name": "Mineral Water",
"slug": "mineral-water",
"parent_id": 12,
"image": null
}
]
},
{
"id": 18,
"name": "Bakery & Pastries",
"slug": "bakery-pastries",
"parent_id": null,
"image": "https://app.tracepos.net/uploads/cat-bakery.png",
"children": []
}
]
}
Get Single Category
Retrieve metadata and subcategories for a specific category ID or Hash ID (xid).
/api/v1/public/categories/{category-xid}Scope: readPath Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
category-xid | String / Integer | Yes | Category Hash ID (xid). Positive numeric IDs are supported for backward compatibility. |
Response (200 OK)
{
"status": "success",
"data": {
"id": 12,
"name": "Beverages",
"slug": "beverages",
"parent_id": null,
"image": "https://app.tracepos.net/uploads/cat-beverages.png",
"children": [
{
"id": 45,
"name": "Energy Drinks",
"slug": "energy-drinks",
"parent_id": 12,
"image": null
}
]
}
}
2. Brands Catalog
The Brands API provides manufacturers, labels, and product line taxonomy for the authenticated company.
List All Brands
/api/v1/public/brandsScope: readCode Samples
curl -X GET "https://app.tracepos.net/api/v1/public/brands" \
-H "X-Tracepos-Public-Key: YOUR_PUBLIC_KEY" \
-H "X-Tracepos-Secret-Key: YOUR_SECRET_KEY" \
-H "Accept: application/json"
const axios = require('axios');
async function getBrands() {
const response = await axios.get('https://app.tracepos.net/api/v1/public/brands', {
headers: {
'X-Tracepos-Public-Key': process.env.TRACEPOS_PUBLIC_KEY,
'X-Tracepos-Secret-Key': process.env.TRACEPOS_SECRET_KEY,
'Accept': 'application/json',
},
});
return response.data.data;
}
import os
import requests
headers = {
"X-Tracepos-Public-Key": os.getenv("TRACEPOS_PUBLIC_KEY"),
"X-Tracepos-Secret-Key": os.getenv("TRACEPOS_SECRET_KEY"),
"Accept": "application/json",
}
response = requests.get("https://app.tracepos.net/api/v1/public/brands", headers=headers)
brands = response.json().get("data", [])
<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;
$client = new Client(['base_uri' => 'https://app.tracepos.net/api/v1/public/']);
$response = $client->get('brands', [
'headers' => [
'X-Tracepos-Public-Key' => getenv('TRACEPOS_PUBLIC_KEY'),
'X-Tracepos-Secret-Key' => getenv('TRACEPOS_SECRET_KEY'),
'Accept' => 'application/json',
],
]);
$brands = json_decode($response->getBody()->getContents(), true)['data'];
Response (200 OK)
{
"status": "success",
"data": [
{
"id": 1,
"name": "Coca-Cola Company",
"slug": "coca-cola-company",
"image": "https://app.tracepos.net/uploads/brands/coke.png"
},
{
"id": 2,
"name": "Nestle",
"slug": "nestle",
"image": "https://app.tracepos.net/uploads/brands/nestle.png"
},
{
"id": 3,
"name": "Unilever",
"slug": "unilever",
"image": null
}
]
}
Get Single Brand
/api/v1/public/brands/{brand-xid}Scope: readPath Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
brand-xid | String / Integer | Yes | Brand Hash ID (xid). Positive numeric IDs are supported for backward compatibility. |
Response (200 OK)
{
"status": "success",
"data": {
"id": 1,
"name": "Coca-Cola Company",
"slug": "coca-cola-company",
"image": "https://app.tracepos.net/uploads/brands/coke.png"
}
}
POS UI Best Practices
- Local SQLite Caching: Categories and brands change infrequently. Cache them in the POS terminal's local SQLite database and refresh upon terminal startup or when receiving a webhook event.
- Dynamic Quick-Select Grid: Render top-level categories as horizontal scrolling tabs on the cash register interface. Tapping a category displays its subcategories or directly filters the product grid.
- Optimized Image Assets: Use CDN thumbnail URLs provided in
imagefor 100x100px POS department icons to minimize mobile data usage across 4G/GPRS POS terminals.
