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

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:

  1. Decrements Stock: Deducts inventory from the warehouse using FIFO batch allocation (product_batches).
  2. Generates Invoices: Issues a sequence-controlled company invoice number (SAL-XXXXX).
  3. Processes Payments: Immediately settles full or partial payments if the all_payments array is provided.
  4. Posts Journal Entries: Creates a balanced double-entry accounting record (Debiting Cash/Receivables, Crediting Sales Revenue and Sales Tax).
  5. 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: read

Query Parameters

ParameterTypeDefaultDescription
datesString-Date range filter in YYYY-MM-DD,YYYY-MM-DD format (e.g. 2026-09-01,2026-09-30).
limitInteger20Items per page (maximum: 100).
pageInteger1Pagination 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: read

Path Parameters

ParameterTypeRequiredDescription
sale-xidString / IntegerYesSale 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: write

Request Parameters

ParameterTypeRequiredDescription
user_idString / IntegerYesCustomer xid (or numeric ID for backward compatibility).
order_dateDate (ISO 8601 / YYYY-MM-DD)YesTransaction timestamp or date (e.g. 2026-10-02T10:30:00Z).
product_itemsArrayYesLine items array (minimum 1 item).
product_items[].product_idString / IntegerYesProduct xid (or numeric ID).
product_items[].quantityNumericYesQuantity purchased (min: 0.01).
product_items[].unit_priceNumericNoSelling price per unit (defaults to warehouse sales price if omitted).
product_items[].discountNumericNoLine-item discount amount (default: 0).
product_items[].unit_idString / IntegerNoUnit xid (or numeric ID) if custom packaging applies.
shippingNumericNoDelivery / shipping surcharge (default: 0).
invoice_numberStringNoCustom invoice number (auto-generated if omitted).
notesStringNoOrder note or external reference comment.
all_paymentsArrayNoSplit or immediate payment array (cannot exceed computed sale total; lower total creates credit sale).
all_payments[].payment_mode_idString / IntegerYes (if payment provided)Payment mode xid (discovered via GET /payment-modes).
all_payments[].amountNumericYes (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.

Next
Purchases & Procurement API