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

Tracepos Public API Reference

Overview

The Tracepos Public API is served under /api/v1/public. All routes are scoped to the company, warehouse, and staff user associated with the supplied API key pair.

  • Base path: /api/v1/public
  • Rate limit: Configured per API key; new keys default to 60 requests per minute
  • Response format: JSON
🚀 Ready-to-use Postman Collection (v2.1.0)

Contains all 19 endpoints, pre-configured variables, and ready-to-test JSON payloads.

📥 Download JSONSetup Guide

Authentication

Every API request requires both public and secret keys supplied via custom request headers:

Accept: application/json
Content-Type: application/json
X-Tracepos-Public-Key: <public-key>
X-Tracepos-Secret-Key: <secret-key>
cURL
curl -X GET "https://app.tracepos.net/api/v1/public/products" \
  -H "X-Tracepos-Public-Key: <public-key>" \
  -H "X-Tracepos-Secret-Key: <secret-key>" \
  -H "Accept: application/json"
Node.js (Axios)
const axios = require('axios');

const client = 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',
    'Content-Type': 'application/json',
  },
});
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",
    "Content-Type": "application/json",
}

response = requests.get(
    "https://app.tracepos.net/api/v1/public/products",
    headers=headers
)
PHP (Guzzle)
$client = new \GuzzleHttp\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',
        'Content-Type'          => 'application/json',
    ],
]);

Uniform 401 Authentication Failure

Missing, expired, inactive, or invalid credentials all return an identical HTTP 401 Unauthorized response to prevent key probing and timing attacks:

{
  "status": "error",
  "message": "Invalid API credentials."
}

Secret Key Storage & Lifecycle

Secrets are shown only once, when an API key is created. Store them immediately in a secure secrets manager. Because secrets are hashed irreversibly using strong one-way cryptographic algorithms (Hash::make() / Hash::check()), they cannot be revealed or recovered later.

To replace a lost or exposed secret, create a replacement key and disable the old key. Existing legacy credentials are invalidated when the security migration (php artisan migrate) is applied.

Permission Scopes (HTTP 403)

Every key must have one or more assigned scopes. A request without the required scope returns HTTP 403 Forbidden:

{
  "status": "error",
  "message": "API key does not have the required permission."
}
  • read: All GET discovery, list, and detail endpoints.
  • write: Customer, supplier, sales, purchase, payment, expense, and return creation (POST).
  • inventory: Stock adjustments and price adjustments (POST /stock-adjustments and POST /price-adjustments).

Per-Key Throttling (HTTP 429)

Rate limiting is applied independently to each authenticated API key. Exceeding its configured limit returns HTTP 429 Too Many Requests:

{
  "status": "error",
  "message": "API rate limit exceeded."
}

Identifiers and Pagination

Use a resource's xid (unique hash identifier) when sending customer, supplier, product, payment mode, order, category, brand, warehouse, adjustment, or expense references.

[!NOTE] Backward Compatibility Handlers also accept positive numeric IDs for backward compatibility, but all new integrations should use xid values exclusively.

  • Collection Endpoints: Accept limit (e.g. ?limit=20) and page (e.g. ?page=1).
  • Date Filters: Date-filtered resources accept dates=YYYY-MM-DD,YYYY-MM-DD (e.g. ?dates=2026-09-01,2026-09-30).

Endpoint Quick Reference

1. Catalog & Outlets

Method & RouteRequired ScopeDescriptionDocumentation
GET /productsreadLists products available in the API key warehouse. Supports category_id (xid) and limit.Products Reference
GET /products/{product-xid}readRetrieves a warehouse-available product.Products Reference
GET /categoriesreadLists categories for the API key company.Categories Reference
GET /categories/{category-xid}readRetrieves a category by xid.Categories Reference
GET /brandsreadLists brands for the API key company.Brands Reference
GET /brands/{brand-xid}readRetrieves a brand by xid.Brands Reference
GET /warehousesreadLists warehouses in the API key company.Warehouses Reference
GET /warehouses/{warehouse-xid}readRetrieves a warehouse in that company.Warehouses Reference

2. Inventory and Pricing

Method & RouteRequired ScopeDescriptionDocumentation
GET /stock-adjustmentsreadLists stock adjustments in the warehouse.Stock Adjustments
GET /stock-adjustments/{stock-adjustment-xid}readRetrieves a specific stock adjustment.Stock Adjustments
POST /stock-adjustmentsinventorySubmits a stock adjustment (add or subtract).Stock Adjustments
GET /price-adjustmentsreadLists historical price updates for products.Price Adjustments
GET /price-adjustments/{price-adjustment-xid}readRetrieves a specific price adjustment.Price Adjustments
POST /price-adjustmentsinventorySets a new warehouse selling price for a product.Price Adjustments

Stock Adjustment Payload Example

{
  "product_id": "<product-xid>",
  "quantity": 2,
  "adjustment_type": "add"
}
  • adjustment_type must be 'add' or 'subtract'.
  • quantity must be at least 0.01.
  • Optional fields: notes, batch_number (xid), and expiry_date.

Price Adjustment Payload Example

{
  "product_id": "<product-xid>",
  "new_sales_price": 1500
}
  • new_sales_price must be zero or greater (>= 0).

3. Customers and Suppliers

Method & RouteRequired ScopeDescriptionDocumentation
GET /customersreadLists customers scoped to the company/warehouse.Customers Reference
GET /customers/{customer-xid}readRetrieves a specific customer.Customers Reference
POST /customerswriteCreates a new customer profile.Customers Reference
GET /suppliersreadLists suppliers for the company.Suppliers Reference
GET /suppliers/{supplier-xid}readRetrieves a specific supplier.Suppliers Reference
POST /supplierswriteCreates a new supplier profile.Suppliers Reference

Customer and supplier creation requires name.

  • Optional fields: phone, email, opening_balance, and opening_balance_type (receive or pay).
  • Customers additionally accept credit_limit.
  • Suppliers additionally accept credit_period (in days).

4. Sales & Orders

Method & RouteRequired ScopeDescriptionDocumentation
GET /salesreadLists sales orders for the warehouse (supports dates & limit).Sales Reference
GET /sales/{sale-xid}readRetrieves details and line items for a sale order.Sales Reference
POST /saleswriteCreates and settles a sale transaction.Sales Reference
GET /payment-modesreadLists global and warehouse payment modes.Payments Reference

GET /payment-modes returns global and warehouse-specific modes available to the API key warehouse. Use a returned mode xid in a sale payment.

POST /sales requires a customer user_id (xid), order_date, and at least one item in product_items. Product prices default to the warehouse sales price when unit_price is omitted. Tracepos calculates line tax, totals, stock movement, journal entries, and payment records.

Sale Payload Example

{
  "user_id": "<customer-xid>",
  "order_date": "2026-10-02T10:30:00Z",
  "notes": "External order reference 12345",
  "shipping": 0,
  "product_items": [
    {
      "product_id": "<product-xid>",
      "quantity": 2,
      "unit_price": 1500,
      "discount": 0
    }
  ],
  "all_payments": [
    {
      "payment_mode_id": "<payment-mode-xid>",
      "amount": 3000
    }
  ]
}

all_payments is optional. Submitted payments cannot exceed the computed sale total; a lower payment total creates a credit sale. Optional item fields include unit_id (xid).


5. Purchases & Procurement

Method & RouteRequired ScopeDescriptionDocumentation
GET /purchasesreadLists purchase orders (supports dates & limit).Purchases Reference
GET /purchases/{purchase-xid}readRetrieves purchase order details and items.Purchases Reference
POST /purchaseswriteRecords inventory receipt from a vendor.Purchases Reference

POST /purchases requires supplier user_id (xid), order_date, and product_items. Optional fields are invoice_number and all_payments.


6. Payments and Settlements

Method & RouteRequired ScopeDescriptionDocumentation
GET /payment-modesreadLists active payment methods for the warehouse.Payments Reference
GET /paymentsreadLists payment records for the warehouse.Payments Reference
POST /paymentswriteRecords an incoming or outgoing payment voucher.Payments Reference
GET /payments/user-invoicesreadDiscovers unpaid invoices for a customer or supplier.Payments Reference
GET /payments/customer-suppliersreadLightweight directory of parties eligible for payments.Payments Reference

Payment Payload Example

{
  "user_id": "<customer-or-supplier-xid>",
  "amount": 3000,
  "payment_type": "in",
  "payment_mode_id": "<payment-mode-xid>",
  "date": "2026-10-02"
}
  • amount must be at least 0.01.
  • payment_type is 'in' (customer collections) or 'out' (supplier disbursements).
  • Optional fields are notes and invoices. Each invoice item uses order_id (xid) and amount.
  • GET /payments/user-invoices requires query parameter user_id (xid). Set payment_type=in for sales and purchase-return invoices; any other value retrieves purchase and sales-return invoices.

7. Expenses

Method & RouteRequired ScopeDescriptionDocumentation
GET /expense-categoriesreadLists configured company expense categories.Expenses Reference
GET /expensesreadLists recorded expenses in the warehouse.Expenses Reference
POST /expenseswriteRecords an operational expense.Expenses Reference
POST /expenses/{expense-xid}/paymentswritePays off a pending or due expense.Expenses Reference
  • Create an expense with expense_category_id (xid), amount (minimum 0.01), and date. Optional fields are payment_mode_id (xid) and notes. Whether a payment mode is needed depends on the warehouse payment-approval setting (approve_payments).
  • Pay an expense with payment_mode_id (xid), amount (minimum 0.01), and date.

8. Returns & Reversals

Method & RouteRequired ScopeDescriptionDocumentation
GET /sales-returnsreadLists customer sales returns.Returns Reference
POST /sales-returnswriteRecords a customer product return.Returns Reference
GET /purchase-returnsreadLists supplier purchase returns.Returns Reference
POST /purchase-returnswriteRecords a vendor return for debit memo.Returns Reference
  • Sales Returns: Require customer user_id (xid), order_date, and items. Optional: notes and invoice_number.
  • Purchase Returns: Require supplier user_id (xid), order_date, and items.
  • Item Structure: Each item requires product_id (xid), quantity (minimum 0.01), and unit_price.

Response Formats

Collection Responses

All collection endpoints return a standardized JSON pagination envelope:

{
  "status": "success",
  "data": {
    "data": [],
    "current_page": 1,
    "last_page": 1,
    "per_page": 20,
    "total": 0
  }
}

Resource Responses

Single-resource endpoints return status and data:

{
  "status": "success",
  "data": {
    "id": 45,
    "xid": "<resource-xid>",
    "name": "Example Resource"
  }
}

Write Responses

Write actions (POST) return status: "success" plus route-specific *_xid identifiers, invoice numbers, totals, or payment details. For example:

{
  "status": "success",
  "order_xid": "<order-xid>",
  "invoice_number": "SAL-00451",
  "total": 3000,
  "paid_amount": 3000,
  "due_amount": 0,
  "payment_status": "paid"
}

Validation Error Responses (HTTP 422)

Validation failures follow Laravel's standard HTTP 422 Unprocessable Content JSON format:

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