Categories & Brands API

The Categories and Brands endpoints provide company-wide master taxonomy data. POS terminals, self-service kiosks, and eCommerce storefronts use these resources to build visual 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.

GET/api/v1/public/categories

Headers

HeaderTypeRequiredDescription
X-Tracepos-Public-KeyStringYesWarehouse public API key
X-Tracepos-Secret-KeyStringYesWarehouse secret API key
AcceptStringYesapplication/json

Code Examples

:::: code-group ::: code-group-item cURL

curl -X GET "https://api.tracepos.com/api/v1/public/categories" \
  -H "X-Tracepos-Public-Key: tp_pub_live_7f8a9c2d1e" \
  -H "X-Tracepos-Secret-Key: tp_sec_live_9b3e1f7a4c" \
  -H "Accept: application/json"

::: ::: code-group-item Node.js (Axios)

const axios = require('axios');

async function getCategories() {
  const response = await axios.get('https://api.tracepos.com/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'
    }
  });

  console.log('Categories count:', response.data.data.length);
  return response.data.data;
}

::: ::: code-group-item Python (Requests)

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://api.tracepos.com/api/v1/public/categories", headers=headers)
categories = response.json().get("data", [])

::: ::: code-group-item PHP (Guzzle)

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://api.tracepos.com/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://cdn.tracepos.com/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://cdn.tracepos.com/uploads/cat-bakery.png",
      "children": []
    }
  ]
}

Get Single Category

Retrieve metadata and subcategories for a specific category ID.

GET/api/v1/public/categories/{id}

Response (200 OK)

{
  "status": "success",
  "data": {
    "id": 12,
    "name": "Beverages",
    "slug": "beverages",
    "parent_id": null,
    "image": "https://cdn.tracepos.com/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.

List All Brands

GET/api/v1/public/brands

Response (200 OK)

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "Coca-Cola Company",
      "slug": "coca-cola-company",
      "image": "https://cdn.tracepos.com/uploads/brands/coke.png"
    },
    {
      "id": 2,
      "name": "Nestle",
      "slug": "nestle",
      "image": "https://cdn.tracepos.com/uploads/brands/nestle.png"
    },
    {
      "id": 3,
      "name": "Unilever",
      "slug": "unilever",
      "image": null
    }
  ]
}

Get Single Brand

GET/api/v1/public/brands/{id}

Response (200 OK)

{
  "status": "success",
  "data": {
    "id": 1,
    "name": "Coca-Cola Company",
    "slug": "coca-cola-company",
    "image": "https://cdn.tracepos.com/uploads/brands/coke.png"
  }
}

POS UI Best Practices

  1. Local SQLite Caching: Categories and brands change infrequently. Cache them in the POS terminal's local SQLite database and refresh on terminal startup or when receiving a product.updated webhook.
  2. 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.
  3. Optimized Image Assets: Use CDN thumbnail URLs provided in image for 100x100px POS department icons to minimize mobile data usage across 4G/GPRS POS terminals.