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
Contains all 19 endpoints, pre-configured variables, and ready-to-test JSON payloads.
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 -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"
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',
},
});
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
)
$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: AllGETdiscovery, list, and detail endpoints.write: Customer, supplier, sales, purchase, payment, expense, and return creation (POST).inventory: Stock adjustments and price adjustments (POST /stock-adjustmentsandPOST /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
xidvalues exclusively.
- Collection Endpoints: Accept
limit(e.g.?limit=20) andpage(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 & Route | Required Scope | Description | Documentation |
|---|---|---|---|
GET /products | read | Lists products available in the API key warehouse. Supports category_id (xid) and limit. | Products Reference |
GET /products/{product-xid} | read | Retrieves a warehouse-available product. | Products Reference |
GET /categories | read | Lists categories for the API key company. | Categories Reference |
GET /categories/{category-xid} | read | Retrieves a category by xid. | Categories Reference |
GET /brands | read | Lists brands for the API key company. | Brands Reference |
GET /brands/{brand-xid} | read | Retrieves a brand by xid. | Brands Reference |
GET /warehouses | read | Lists warehouses in the API key company. | Warehouses Reference |
GET /warehouses/{warehouse-xid} | read | Retrieves a warehouse in that company. | Warehouses Reference |
2. Inventory and Pricing
| Method & Route | Required Scope | Description | Documentation |
|---|---|---|---|
GET /stock-adjustments | read | Lists stock adjustments in the warehouse. | Stock Adjustments |
GET /stock-adjustments/{stock-adjustment-xid} | read | Retrieves a specific stock adjustment. | Stock Adjustments |
POST /stock-adjustments | inventory | Submits a stock adjustment (add or subtract). | Stock Adjustments |
GET /price-adjustments | read | Lists historical price updates for products. | Price Adjustments |
GET /price-adjustments/{price-adjustment-xid} | read | Retrieves a specific price adjustment. | Price Adjustments |
POST /price-adjustments | inventory | Sets a new warehouse selling price for a product. | Price Adjustments |
Stock Adjustment Payload Example
{
"product_id": "<product-xid>",
"quantity": 2,
"adjustment_type": "add"
}
adjustment_typemust be'add'or'subtract'.quantitymust be at least0.01.- Optional fields:
notes,batch_number(xid), andexpiry_date.
Price Adjustment Payload Example
{
"product_id": "<product-xid>",
"new_sales_price": 1500
}
new_sales_pricemust be zero or greater (>= 0).
3. Customers and Suppliers
| Method & Route | Required Scope | Description | Documentation |
|---|---|---|---|
GET /customers | read | Lists customers scoped to the company/warehouse. | Customers Reference |
GET /customers/{customer-xid} | read | Retrieves a specific customer. | Customers Reference |
POST /customers | write | Creates a new customer profile. | Customers Reference |
GET /suppliers | read | Lists suppliers for the company. | Suppliers Reference |
GET /suppliers/{supplier-xid} | read | Retrieves a specific supplier. | Suppliers Reference |
POST /suppliers | write | Creates a new supplier profile. | Suppliers Reference |
Customer and supplier creation requires name.
- Optional fields:
phone,email,opening_balance, andopening_balance_type(receiveorpay). - Customers additionally accept
credit_limit. - Suppliers additionally accept
credit_period(in days).
4. Sales & Orders
| Method & Route | Required Scope | Description | Documentation |
|---|---|---|---|
GET /sales | read | Lists sales orders for the warehouse (supports dates & limit). | Sales Reference |
GET /sales/{sale-xid} | read | Retrieves details and line items for a sale order. | Sales Reference |
POST /sales | write | Creates and settles a sale transaction. | Sales Reference |
GET /payment-modes | read | Lists 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 & Route | Required Scope | Description | Documentation |
|---|---|---|---|
GET /purchases | read | Lists purchase orders (supports dates & limit). | Purchases Reference |
GET /purchases/{purchase-xid} | read | Retrieves purchase order details and items. | Purchases Reference |
POST /purchases | write | Records 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 & Route | Required Scope | Description | Documentation |
|---|---|---|---|
GET /payment-modes | read | Lists active payment methods for the warehouse. | Payments Reference |
GET /payments | read | Lists payment records for the warehouse. | Payments Reference |
POST /payments | write | Records an incoming or outgoing payment voucher. | Payments Reference |
GET /payments/user-invoices | read | Discovers unpaid invoices for a customer or supplier. | Payments Reference |
GET /payments/customer-suppliers | read | Lightweight 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"
}
amountmust be at least0.01.payment_typeis'in'(customer collections) or'out'(supplier disbursements).- Optional fields are
notesandinvoices. Each invoice item usesorder_id(xid) andamount. GET /payments/user-invoicesrequires query parameteruser_id(xid). Setpayment_type=infor sales and purchase-return invoices; any other value retrieves purchase and sales-return invoices.
7. Expenses
| Method & Route | Required Scope | Description | Documentation |
|---|---|---|---|
GET /expense-categories | read | Lists configured company expense categories. | Expenses Reference |
GET /expenses | read | Lists recorded expenses in the warehouse. | Expenses Reference |
POST /expenses | write | Records an operational expense. | Expenses Reference |
POST /expenses/{expense-xid}/payments | write | Pays off a pending or due expense. | Expenses Reference |
- Create an expense with
expense_category_id(xid),amount(minimum0.01), anddate. Optional fields arepayment_mode_id(xid) andnotes. Whether a payment mode is needed depends on the warehouse payment-approval setting (approve_payments). - Pay an expense with
payment_mode_id(xid),amount(minimum0.01), anddate.
8. Returns & Reversals
| Method & Route | Required Scope | Description | Documentation |
|---|---|---|---|
GET /sales-returns | read | Lists customer sales returns. | Returns Reference |
POST /sales-returns | write | Records a customer product return. | Returns Reference |
GET /purchase-returns | read | Lists supplier purchase returns. | Returns Reference |
POST /purchase-returns | write | Records a vendor return for debit memo. | Returns Reference |
- Sales Returns: Require customer
user_id(xid),order_date, anditems. Optional:notesandinvoice_number. - Purchase Returns: Require supplier
user_id(xid),order_date, anditems. - Item Structure: Each item requires
product_id(xid),quantity(minimum0.01), andunit_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."
]
}
}
