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

Customers & Suppliers API

Tracepos provides a unified CRM and Accounts Ledger architecture for trading parties. Both Customers (Accounts Receivable) and Suppliers (Accounts Payable) are modeled as sub-ledger accounts.

When you create or query a customer or supplier through the Public API, the system strictly enforces tenant- and warehouse-binding:

  • Creation Binding: Creating a customer or supplier automatically binds the record to the API key's company_id and assigns it to the authenticated warehouse_id.
  • Tenant Isolation: Detail queries (GET /{xid}) verify that the party belongs to the authenticated company (api_company_id) and possesses active ledger records for the requested warehouse.
  • Scope Enforcement: Requires the read scope for discovery and list/detail endpoints, and the write scope for creation.

1. Customers API

Customers represent retail buyers, wholesale distributors, and corporate accounts.

List Customers

Retrieve a paginated list of customers along with their warehouse-specific credit limit and outstanding due balance.

GET/api/v1/public/customersScope: read

Query Parameters

ParameterTypeDefaultDescription
limitInteger20Items per page (max: 100)
pageInteger1Pagination page number

Code Samples

cURL
curl -X GET "https://app.tracepos.net/api/v1/public/customers?limit=20&page=1" \
  -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 listCustomers(page = 1) {
  const response = await axios.get('https://app.tracepos.net/api/v1/public/customers', {
    params: { limit: 20, page },
    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/customers",
    params={"limit": 20, "page": 1},
    headers=headers,
)
data = 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('customers', [
    'query' => ['limit' => 20, 'page' => 1],
    'headers' => [
        'X-Tracepos-Public-Key' => getenv('TRACEPOS_PUBLIC_KEY'),
        'X-Tracepos-Secret-Key' => getenv('TRACEPOS_SECRET_KEY'),
        'Accept'                => 'application/json',
    ],
]);

$customers = json_decode($response->getBody()->getContents(), true)['data'];

Response (200 OK)

{
  "status": "success",
  "data": {
    "current_page": 1,
    "per_page": 20,
    "total": 65,
    "data": [
      {
        "id": 105,
        "name": "Adeola Adeleke",
        "email": "[email protected]",
        "phone": "+2348031234567",
        "user_type": "customers",
        "opening_balance": "0.00",
        "due_amount": "14500.00",
        "credit_limit": "50000.00",
        "is_walkin_customer": 0
      },
      {
        "id": 106,
        "name": "Walk In Customer",
        "email": null,
        "phone": null,
        "user_type": "customers",
        "opening_balance": "0.00",
        "due_amount": "0.00",
        "credit_limit": "0.00",
        "is_walkin_customer": 1
      }
    ]
  }
}

Get Single Customer

GET/api/v1/public/customers/{customer-xid}Scope: read

Path Parameters

ParameterTypeRequiredDescription
customer-xidString / IntegerYesCustomer Hash ID (xid). Positive numeric IDs are accepted for backward compatibility.

Response (200 OK)

{
  "status": "success",
  "data": {
    "id": 105,
    "name": "Adeola Adeleke",
    "email": "[email protected]",
    "phone": "+2348031234567",
    "user_type": "customers",
    "details": [
      {
        "user_id": 105,
        "warehouse_id": 1,
        "opening_balance": "0.00",
        "opening_balance_type": "receive",
        "credit_period": 30,
        "credit_limit": "50000.00",
        "due_amount": "14500.00",
        "paid_amount": "85000.00"
      }
    ]
  }
}

Create Customer

Create a new customer profile. Tracepos automatically initializes sub-ledger balances across all company warehouses and sets default credit terms.

POST/api/v1/public/customersScope: write

Request Body

FieldTypeRequiredDescription
nameStringYesFull customer or corporate entity name (max: 255 chars).
phoneStringNoMobile phone number.
emailStringNoValid email address.
opening_balanceDecimalNoHistorical starting balance (Default: 0.00).
opening_balance_typeStringNo'receive' (customer owes you) or 'pay' (credit balance). Default: 'receive'.
credit_limitDecimalNoMaximum outstanding invoice debt allowed.

Request Payload

{
  "name": "Kafspeedway Logistics Ltd",
  "phone": "+2348149876543",
  "email": "[email protected]",
  "opening_balance": 15000.00,
  "opening_balance_type": "receive",
  "credit_limit": 200000.00
}

Code Samples

cURL
curl -X POST "https://app.tracepos.net/api/v1/public/customers" \
  -H "X-Tracepos-Public-Key: YOUR_PUBLIC_KEY" \
  -H "X-Tracepos-Secret-Key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Kafspeedway Logistics Ltd",
    "phone": "+2348149876543",
    "email": "[email protected]",
    "opening_balance": 15000.00,
    "opening_balance_type": "receive",
    "credit_limit": 200000.00
  }'
Node.js (Axios)
const axios = require('axios');

async function createCustomer() {
  const response = await axios.post(
    'https://app.tracepos.net/api/v1/public/customers',
    {
      name: 'Kafspeedway Logistics Ltd',
      phone: '+2348149876543',
      email: '[email protected]',
      opening_balance: 15000.00,
      opening_balance_type: 'receive',
      credit_limit: 200000.00,
    },
    {
      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 = {
    "name": "Kafspeedway Logistics Ltd",
    "phone": "+2348149876543",
    "email": "[email protected]",
    "opening_balance": 15000.00,
    "opening_balance_type": "receive",
    "credit_limit": 200000.00,
}

response = requests.post("https://app.tracepos.net/api/v1/public/customers", 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('customers', [
    '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' => [
        'name'                 => 'Kafspeedway Logistics Ltd',
        'phone'                => '+2348149876543',
        'email'                => '[email protected]',
        'opening_balance'      => 15000.00,
        'opening_balance_type' => 'receive',
        'credit_limit'         => 200000.00,
    ],
]);

echo $response->getBody();

Response (200 OK)

{
  "status": "success",
  "customer_xid": "usr_9x8a7b6c5d4e",
  "name": "Kafspeedway Logistics Ltd"
}

2. Suppliers API

Suppliers represent vendors, manufacturers, and importers supplying stock to your business.

List Suppliers

GET/api/v1/public/suppliersScope: read

Response (200 OK)

{
  "status": "success",
  "data": {
    "current_page": 1,
    "per_page": 20,
    "total": 12,
    "data": [
      {
        "id": 201,
        "name": "Dangote Sugar Refinery Plc",
        "email": "[email protected]",
        "phone": "+23412700000",
        "user_type": "suppliers",
        "opening_balance": "0.00",
        "due_amount": "250000.00",
        "credit_period": 45
      }
    ]
  }
}

Get Single Supplier

GET/api/v1/public/suppliers/{supplier-xid}Scope: read

Path Parameters

ParameterTypeRequiredDescription
supplier-xidString / IntegerYesSupplier Hash ID (xid). Positive numeric IDs are accepted for backward compatibility.

Response (200 OK)

{
  "status": "success",
  "data": {
    "id": 201,
    "name": "Dangote Sugar Refinery Plc",
    "email": "[email protected]",
    "phone": "+23412700000",
    "user_type": "suppliers",
    "details": [
      {
        "user_id": 201,
        "warehouse_id": 1,
        "opening_balance": "0.00",
        "opening_balance_type": "pay",
        "credit_period": 45,
        "due_amount": "250000.00"
      }
    ]
  }
}

Create Supplier

POST/api/v1/public/suppliersScope: write

Request Body

FieldTypeRequiredDescription
nameStringYesSupplier / vendor business name (max: 255 chars).
phoneStringNoContact phone number.
emailStringNoAccounts payable email.
opening_balanceDecimalNoStarting balance owed to supplier (Default: 0.00).
opening_balance_typeStringNo'pay' (you owe supplier) or 'receive' (supplier owes you credit). Default: 'pay'.
credit_periodIntegerNoPayment terms in days (e.g. 30, 60). Default: 30.

Request Payload

{
  "name": "Nestle Nigeria Direct Distribution",
  "phone": "+23412790000",
  "email": "[email protected]",
  "opening_balance": 0.00,
  "opening_balance_type": "pay",
  "credit_period": 30
}

Code Samples

cURL
curl -X POST "https://app.tracepos.net/api/v1/public/suppliers" \
  -H "X-Tracepos-Public-Key: YOUR_PUBLIC_KEY" \
  -H "X-Tracepos-Secret-Key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Nestle Nigeria Direct Distribution",
    "phone": "+23412790000",
    "email": "[email protected]",
    "opening_balance": 0.00,
    "opening_balance_type": "pay",
    "credit_period": 30
  }'
Node.js (Axios)
const axios = require('axios');

async function createSupplier() {
  const response = await axios.post(
    'https://app.tracepos.net/api/v1/public/suppliers',
    {
      name: 'Nestle Nigeria Direct Distribution',
      phone: '+23412790000',
      email: '[email protected]',
      opening_balance: 0.00,
      opening_balance_type: 'pay',
      credit_period: 30,
    },
    {
      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 = {
    "name": "Nestle Nigeria Direct Distribution",
    "phone": "+23412790000",
    "email": "[email protected]",
    "opening_balance": 0.00,
    "opening_balance_type": "pay",
    "credit_period": 30,
}

response = requests.post("https://app.tracepos.net/api/v1/public/suppliers", 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('suppliers', [
    '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' => [
        'name'                 => 'Nestle Nigeria Direct Distribution',
        'phone'                => '+23412790000',
        'email'                => '[email protected]',
        'opening_balance'      => 0.00,
        'opening_balance_type' => 'pay',
        'credit_period'        => 30,
    ],
]);

echo $response->getBody();

Response (200 OK)

{
  "status": "success",
  "supplier_xid": "usr_7z6y5x4w3v2u",
  "name": "Nestle Nigeria Direct Distribution"
}

Sub-Ledger Accounting Rules

  1. Automatic Multi-Warehouse Synchronization: When a party is created, Tracepos creates a user_details record across every warehouse in the company. Transactions at any branch immediately aggregate to the customer's balance.
  2. Real-Time Debt Calculation: due_amount is updated by database transactions on every sale, purchase, payment, and return: $$\text{Customer Due} = \text{Opening Balance} + \sum \text{Sales} - \sum \text{Payments Received} - \sum \text{Sales Returns}$$ $$\text{Supplier Due} = \text{Opening Balance} + \sum \text{Purchases} - \sum \text{Payments Made} - \sum \text{Purchase Returns}$$
  3. Credit Limit Enforcement: When integrating external checkout or POS terminals, check due_amount + cart_total <= credit_limit before permitting a sale on credit (payment_status = unpaid).