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_idand assigns it to the authenticatedwarehouse_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
readscope for discovery and list/detail endpoints, and thewritescope 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.
/api/v1/public/customersScope: readQuery Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | Integer | 20 | Items per page (max: 100) |
page | Integer | 1 | Pagination page number |
Code Samples
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"
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;
}
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
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
/api/v1/public/customers/{customer-xid}Scope: readPath Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
customer-xid | String / Integer | Yes | Customer 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.
/api/v1/public/customersScope: writeRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
name | String | Yes | Full customer or corporate entity name (max: 255 chars). |
phone | String | No | Mobile phone number. |
email | String | No | Valid email address. |
opening_balance | Decimal | No | Historical starting balance (Default: 0.00). |
opening_balance_type | String | No | 'receive' (customer owes you) or 'pay' (credit balance). Default: 'receive'. |
credit_limit | Decimal | No | Maximum 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 -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
}'
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;
}
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
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
/api/v1/public/suppliersScope: readResponse (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
/api/v1/public/suppliers/{supplier-xid}Scope: readPath Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
supplier-xid | String / Integer | Yes | Supplier 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
/api/v1/public/suppliersScope: writeRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
name | String | Yes | Supplier / vendor business name (max: 255 chars). |
phone | String | No | Contact phone number. |
email | String | No | Accounts payable email. |
opening_balance | Decimal | No | Starting balance owed to supplier (Default: 0.00). |
opening_balance_type | String | No | 'pay' (you owe supplier) or 'receive' (supplier owes you credit). Default: 'pay'. |
credit_period | Integer | No | Payment 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 -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
}'
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;
}
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
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
- Automatic Multi-Warehouse Synchronization: When a party is created, Tracepos creates a
user_detailsrecord across every warehouse in the company. Transactions at any branch immediately aggregate to the customer's balance. - Real-Time Debt Calculation:
due_amountis 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}$$ - Credit Limit Enforcement: When integrating external checkout or POS terminals, check
due_amount + cart_total <= credit_limitbefore permitting a sale on credit (payment_status = unpaid).
