Tracepos Developer HubTracepos Developer Hub
Home
Guide
POS & Integrations
API Reference
Webhooks
Postman Collection
Home
Guide
POS & Integrations
API Reference
Webhooks
Postman Collection
  • Getting Started

    • Getting Started
    • Authentication & Security Scopes
    • Postman Collection
    • Architecture & Core Concepts
    • Security & Best Practices
    • Deployment & Hosting Guide

Getting Started

Welcome to the Tracepos Public API. Our REST API is built on high-performance infrastructure, providing developer-friendly access to inventory catalogs, multi-branch warehouses, customer ledgers, sales recording, purchase procurement, and real-time double-entry accounting.


Base URLs

All API interactions must take place over secure HTTPS:

EnvironmentBase URL
Production Cloudhttps://app.tracepos.net/api/v1/public/
Local Developmenthttp://localhost:8000/api/v1/public/

Authentication at a Glance

Tracepos uses an Enterprise Dual-Key Architecture for maximum security and warehouse-level scoping:

  1. X-Tracepos-Public-Key: A public identifier (e.g. Trp-pk-9f8a...) used by Tracepos to route the request to the correct tenant and warehouse branch.
  2. X-Tracepos-Secret-Key: A private secret (e.g. Trp-sk-7c1b...) verified server-side against a one-way cryptographic hash (Hash::check()). Secrets are displayed only once upon generation and cannot be viewed later. Never expose this key in client-side code.

Both headers are mandatory for every API request:

X-Tracepos-Public-Key: YOUR_PUBLIC_KEY
X-Tracepos-Secret-Key: YOUR_SECRET_KEY
Accept: application/json
Content-Type: application/json

Every key must also have assigned Scopes (read, write, inventory) and a configured per-key rate limit. For full details on key generation, scopes, and permissions, see the Authentication Guide.


Step 1: Generate Your Warehouse API Keys

  1. Log in to your Tracepos Admin Dashboard.
  2. Navigate to Settings → API Keys.
  3. Click Generate New API Key.
  4. Give your key a label (e.g. Main Cashier POS 1, E-Commerce Storefront, Paystack Terminal).
  5. Select the warehouse branch that this key will operate against.
  6. Configure the key's Rate Limit (defaults to 60 req/min) and assign required Scopes (read, write, inventory).
  7. Copy both the Public Key and Secret Key. Store the secret immediately in a secure vault; it is shown only once and cannot be recovered later.

Step 2: Make Your First API Call

Test connectivity by retrieving the list of products in your warehouse catalog:

cURL
curl -X GET "https://app.tracepos.net/api/v1/public/products?limit=5" \
  -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');

const tracepos = axios.create({
  baseURL: 'https://app.tracepos.net/api/v1/public',
  headers: {
    'X-Tracepos-Public-Key': process.env.TRACEPOS_PUBLIC_KEY,
    'X-Tracepos-Secret-Key': process.env.TRACEPOS_SECRET_KEY,
    'Accept': 'application/json',
  },
});

async function getProducts() {
  try {
    const response = await tracepos.get('/products', { params: { limit: 5 } });
    console.log('Products:', response.data);
  } catch (error) {
    console.error('API Error:', error.response?.data || error.message);
  }
}

getProducts();
Python (Requests)
import os
import requests

BASE_URL = "https://app.tracepos.net/api/v1/public"
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(f"{BASE_URL}/products", headers=headers, params={"limit": 5})

if response.status_code == 200:
    print("Catalog:", response.json())
else:
    print("Error:", response.status_code, response.text)
PHP (Guzzle)
<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://app.tracepos.net/api/v1/public/',
    'headers' => [
        'X-Tracepos-Public-Key' => getenv('TRACEPOS_PUBLIC_KEY'),
        'X-Tracepos-Secret-Key' => getenv('TRACEPOS_SECRET_KEY'),
        'Accept'             => 'application/json',
    ]
]);

$response = $client->get('products', [
    'query' => ['limit' => 5]
]);

echo $response->getBody();

Step 3: Import Official Postman Collection

Instead of constructing every curl command or payload manually, download our official Postman Collection covering all 19 public endpoints:

Tracepos Public API Postman Collection (v2.1.0)

Pre-configured dual-key authentication headers and sample request bodies.

📥 Download Postman Collection

For instructions on importing, setting environment variables, and automated workflows, visit the Postman Collection Guide.


Response Envelope Standard

Every API response follows a consistent JSON envelope structure:

Successful Response (200 OK, 201 Created)

{
  "status": "success",
  "data": {
    "current_page": 1,
    "data": [
      {
        "xid": "w8vBqGZ0",
        "name": "Basmati Rice 50kg",
        "item_code": "RICE-50KG",
        "sales_price": 75000.00,
        "current_stock": 142
      }
    ]
  }
}

Error Response (4xx, 5xx)

{
  "status": "error",
  "message": "The product items field is required.",
  "errors": {
    "product_items": [
      "The product items field is required."
    ]
  }
}

HTTP Status Codes

Tracepos returns standard RFC HTTP status codes:

CodeStatusMeaning
200OKRequest completed successfully.
201CreatedResource created (e.g. sale, payment, or customer).
400Bad RequestMalformed JSON or invalid parameter types.
401UnauthorizedMissing or invalid Public Key / Secret Key headers.
403ForbiddenExpired SaaS license or key deactivated.
404Not FoundThe requested resource (product, customer, order) does not exist in this warehouse.
422Unprocessable EntityForm validation failed (e.g. missing required line items).
429Too Many RequestsRate limit exceeded (60 requests/minute default). Retry after header indicates seconds.
500Internal Server ErrorUnexpected server condition. Transaction was rolled back automatically.

Rate Limiting

The Public API enforces rate limits per active key to safeguard warehouse infrastructure:

  • Default Window: 60 requests per minute.
  • Custom enterprise limits can be configured in your Warehouse API Key settings.

Tracepos includes rate limit status headers with every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1775040060

When throttled, the server returns HTTP 429 Too Many Requests with a Retry-After header. Learn how to handle backoff gracefully in the Security Guide.

Next
Authentication & Security Scopes