Sales & Transactions API
The Sales API is the core transactional engine of Tracepos. When an order is submitted through this endpoint, Tracepos executes an atomic database transaction that:
- Decrements Stock: Deducts inventory from the warehouse using FIFO batch allocation (
product_batches). - Generates Invoices: Issues a sequence-controlled company invoice number (
SAL-XXXXX). - Processes Payments: Immediately settles full or partial payments if the
all_paymentsarray is provided. - Posts Journal Entries: Creates a balanced double-entry accounting record (Debiting Cash/Receivables, Crediting Sales Revenue and Sales Tax).
- Updates Balances: Updates customer outstanding debt in real time.
1. List Sales Orders
Retrieve a paginated list of sales orders created in the authorized warehouse.
GET
/api/v1/public/salesScope: readQuery Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
dates | String | - | Date range filter in YYYY-MM-DD,YYYY-MM-DD format (e.g. 2026-09-01,2026-09-30). |
limit | Integer | 20 | Items per page (maximum: 100). |
page | Integer | 1 | Pagination page number. |
Code Samples
cURL
curl -X GET "https://app.tracepos.net/api/v1/public/sales?dates=2026-09-01,2026-09-30&limit=20" \
-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 listSales(startDate, endDate) {
const response = await axios.get('https://app.tracepos.net/api/v1/public/sales', {
params: {
dates: `${startDate},${endDate}`,
limit: 20,
},
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/sales",
params={"dates": "2026-09-01,2026-09-30", "limit": 20},
headers=headers,
)
sales = 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('sales', [
'query' => [
'dates' => '2026-09-01,2026-09-30',
'limit' => 20,
],
'headers' => [
'X-Tracepos-Public-Key' => getenv('TRACEPOS_PUBLIC_KEY'),
'X-Tracepos-Secret-Key' => getenv('TRACEPOS_SECRET_KEY'),
'Accept' => 'application/json',
],
]);
$sales = json_decode($response->getBody()->getContents(), true)['data'];
Response (200 OK)
{
"status": "success",
"data": {
"current_page": 1,
"per_page": 20,
"total": 450,
"data": [
{
"id": 182,
"unique_id": "ord_9182ab3c4d5e",
"invoice_number": "SAL-00451",
"order_type": "sales",
"order_date": "2026-09-30",
"subtotal": 5500.00,
"tax_amount": 412.50,
"discount": 0.00,
"shipping": 0.00,
"total": 5912.50,
"paid_amount": 5912.50,
"due_amount": 0.00,
"order_status": "delivered",
"user": {
"id": 105,
"name": "Adeola Adeleke"
},
"staff_member": {
"id": 2,
"name": "POS Terminal 01 Key"
}
}
]
}
}
2. Get Single Sale Order
Retrieve complete line items, applied product taxes, and customer details for a single sale.
GET
/api/v1/public/sales/{sale-xid}Scope: readPath Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
sale-xid | String / Integer | Yes | Sale Order Hash ID (xid). Positive numeric IDs are accepted for backward compatibility. |
Response (200 OK)
{
"status": "success",
"data": {
"id": 182,
"unique_id": "ord_9182ab3c4d5e",
"invoice_number": "SAL-00451",
"order_date": "2026-09-30",
"subtotal": 5500.00,
"total": 5912.50,
"paid_amount": 5912.50,
"due_amount": 0.00,
"user": {
"id": 105,
"name": "Adeola Adeleke",
"phone": "+2348031234567"
},
"items": [
{
"id": 412,
"product_id": 45,
"quantity": 2,
"unit_price": 2750.00,
"subtotal": 5500.00,
"product": {
"id": 45,
"name": "Premium Basmati Rice 5kg",
"item_code": "RICE-5KG-01"
}
}
]
}
}
3. Create Sale (POS Checkout)
Record a completed or credit sale from a smart POS terminal, self-checkout kiosk, or eCommerce gateway.
POST
/api/v1/public/salesScope: writeRequest Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
user_id | String / Integer | Yes | Customer xid (or numeric ID for backward compatibility). |
order_date | Date (ISO 8601 / YYYY-MM-DD) | Yes | Transaction timestamp or date (e.g. 2026-10-02T10:30:00Z). |
product_items | Array | Yes | Line items array (minimum 1 item). |
product_items[].product_id | String / Integer | Yes | Product xid (or numeric ID). |
product_items[].quantity | Numeric | Yes | Quantity purchased (min: 0.01). |
product_items[].unit_price | Numeric | No | Selling price per unit (defaults to warehouse sales price if omitted). |
product_items[].discount | Numeric | No | Line-item discount amount (default: 0). |
product_items[].unit_id | String / Integer | No | Unit xid (or numeric ID) if custom packaging applies. |
shipping | Numeric | No | Delivery / shipping surcharge (default: 0). |
invoice_number | String | No | Custom invoice number (auto-generated if omitted). |
notes | String | No | Order note or external reference comment. |
all_payments | Array | No | Split or immediate payment array (cannot exceed computed sale total; lower total creates credit sale). |
all_payments[].payment_mode_id | String / Integer | Yes (if payment provided) | Payment mode xid (discovered via GET /payment-modes). |
all_payments[].amount | Numeric | Yes (if payment provided) | Payment tender amount (> 0). |
Request 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
}
]
}
Code Samples
cURL
curl -X POST "https://app.tracepos.net/api/v1/public/sales" \
-H "X-Tracepos-Public-Key: <public-key>" \
-H "X-Tracepos-Secret-Key: <secret-key>" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"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
}
]
}'
Node.js (Axios)
const axios = require('axios');
async function createSale() {
const payload = {
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,
},
],
};
const response = await axios.post(
'https://app.tracepos.net/api/v1/public/sales',
payload,
{
headers: {
'X-Tracepos-Public-Key': process.env.TRACEPOS_PUBLIC_KEY,
'X-Tracepos-Secret-Key': process.env.TRACEPOS_SECRET_KEY,
'Content-Type': 'application/json',
'Accept': 'application/json',
},
}
);
return response.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"),
"Content-Type": "application/json",
"Accept": "application/json",
}
payload = {
"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,
}
],
}
response = requests.post("https://app.tracepos.net/api/v1/public/sales", json=payload, headers=headers)
print(response.json())
PHP (Guzzle)
<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;
$client = new Client(['base_uri' => 'https://app.tracepos.net/api/v1/public/']);
$response = $client->post('sales', [
'headers' => [
'X-Tracepos-Public-Key' => getenv('TRACEPOS_PUBLIC_KEY'),
'X-Tracepos-Secret-Key' => getenv('TRACEPOS_SECRET_KEY'),
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'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,
],
],
],
]);
$result = json_decode($response->getBody()->getContents(), true);
echo print_r($result, true);
Response (200 OK)
{
"status": "success",
"order_xid": "ord_9182ab3c4d5e",
"invoice_number": "SAL-00451",
"total_amount": 3000.00
}
Split Tender Payments
Tracepos supports multi-tender transactions directly within all_payments. For example, a customer paying part Cash and part Card:
{
"user_id": "<customer-xid>",
"order_date": "2026-10-02T10:30:00Z",
"product_items": [
{ "product_id": "<product-xid>", "quantity": 4, "unit_price": 2500.00 }
],
"all_payments": [
{ "payment_mode_id": "<cash-mode-xid>", "amount": 4000.00 },
{ "payment_mode_id": "<card-mode-xid>", "amount": 6000.00 }
]
}
Tracepos automatically creates two Payment records and two OrderPayment ledger entries, updating the order to payment_status = "paid" and settling the cashier drawer accounts.
