Tracepos Developer HubTracepos Developer Hub
Home
Guide
POS & Integrations
API Reference
Webhooks
Postman Collection
Home
Guide
POS & Integrations
API Reference
Webhooks
Postman Collection
  • Overview & Specifications

    • Tracepos Public API Reference
  • Core Catalog & Outlets

    • Products API
    • Categories & Brands API
    • Warehouses & Outlets API
  • Parties & CRM

    • Customers & Suppliers API
  • Operations & Stock

    • Sales & Transactions API
    • Purchases & Procurement API
    • Inventory & Price Adjustments API
    • Returns & Reversals API
  • Financial Ledger & Expenses

    • Payments & Settlements API
    • Expense Management API
    • Double-Entry Accounting Architecture
  • Real-Time Sync

    • Webhooks & Real-Time Sync

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.

GET/api/v1/public/categoriesScope: read

Headers

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

Code Samples

cURL
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"
Node.js (Axios)
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;
}
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://app.tracepos.net/api/v1/public/categories", headers=headers)
categories = response.json().get("data", [])
PHP (Guzzle)
<?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).

GET/api/v1/public/categories/{category-xid}Scope: read

Path Parameters

ParameterTypeRequiredDescription
category-xidString / IntegerYesCategory 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

GET/api/v1/public/brandsScope: read

Code Samples

cURL
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"
Node.js (Axios)
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;
}
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://app.tracepos.net/api/v1/public/brands", headers=headers)
brands = response.json().get("data", [])
PHP (Guzzle)
<?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

GET/api/v1/public/brands/{brand-xid}Scope: read

Path Parameters

ParameterTypeRequiredDescription
brand-xidString / IntegerYesBrand 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

  1. 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.
  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.
Prev
Products API
Next
Warehouses & Outlets API