Purchases & Procurement API
The Purchases API manages the procurement of goods from suppliers and manufacturers. When stock arrives at a warehouse, recording a purchase through this endpoint:
- Increments Physical Stock: Updates
current_stockfor each product line in the receiving warehouse. - Creates Inventory Batches: Logs batch details for FIFO expiry and costing tracking.
- Posts Accounts Payable (A/P): Enters the liability into double-entry accounting (Debiting Inventory Asset
11700, Crediting Accounts Payable21100). - Dispatches Supplier Disbursements: If
all_paymentsare provided, records outward payments from the designated bank account or petty cash drawer.
1. List Purchases
Retrieve a paginated history of procurement orders for the authorized warehouse.
GET
/api/v1/public/purchasesScope: readQuery Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
dates | String | - | Date range filter in YYYY-MM-DD,YYYY-MM-DD format. |
limit | Integer | 20 | Results per page (max: 100). |
page | Integer | 1 | Page number. |
Code Samples
cURL
curl -X GET "https://app.tracepos.net/api/v1/public/purchases?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 listPurchases() {
const response = await axios.get('https://app.tracepos.net/api/v1/public/purchases', {
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/purchases", headers=headers)
purchases = 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('purchases', [
'headers' => [
'X-Tracepos-Public-Key' => getenv('TRACEPOS_PUBLIC_KEY'),
'X-Tracepos-Secret-Key' => getenv('TRACEPOS_SECRET_KEY'),
'Accept' => 'application/json',
],
]);
$purchases = json_decode($response->getBody()->getContents(), true)['data'];
Response (200 OK)
{
"status": "success",
"data": {
"current_page": 1,
"per_page": 20,
"total": 35,
"data": [
{
"id": 94,
"unique_id": "ord_pur_18374ab90",
"invoice_number": "PUR-00102",
"order_type": "purchases",
"order_date": "2026-09-28",
"subtotal": 250000.00,
"total": 250000.00,
"paid_amount": 250000.00,
"due_amount": 0.00,
"order_status": "received",
"user": {
"id": 201,
"name": "Dangote Sugar Refinery Plc"
},
"staff_member": {
"id": 2,
"name": "Procurement Officer"
}
}
]
}
}
2. Get Single Purchase Order
Retrieve purchase details including received quantities, line item costs, and attached supplier disbursements.
GET
/api/v1/public/purchases/{purchase-xid}Scope: readPath Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
purchase-xid | String / Integer | Yes | Purchase Order Hash ID (xid). Positive numeric IDs are accepted for backward compatibility. |
Response (200 OK)
{
"status": "success",
"data": {
"id": 94,
"invoice_number": "PUR-00102",
"order_date": "2026-09-28",
"total": 250000.00,
"paid_amount": 250000.00,
"due_amount": 0.00,
"user": {
"id": 201,
"name": "Dangote Sugar Refinery Plc",
"phone": "+23412700000"
},
"items": [
{
"id": 142,
"product_id": 12,
"quantity": 100,
"unit_price": 2500.00,
"subtotal": 250000.00,
"product": {
"id": 12,
"name": "Granulated White Sugar 50kg",
"item_code": "SUG-50KG-WHT"
}
}
],
"payments": [
{
"id": 88,
"amount": 250000.00,
"payment_type": "out",
"date": "2026-09-28"
}
]
}
}
3. Create Purchase (Stock Inward)
Record new inventory intake from a supplier into your warehouse.
POST
/api/v1/public/purchasesScope: writeRequest Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
user_id | String / Integer | Yes | Supplier xid (or numeric ID for backward compatibility). |
order_date | Date (YYYY-MM-DD) | Yes | Goods receipt date (e.g. 2026-10-02). |
product_items | Array | Yes | Array of received stock items. |
product_items[].product_id | String / Integer | Yes | Product xid (or numeric ID). |
product_items[].quantity | Numeric | Yes | Units received into stock (min: 0.01). |
product_items[].unit_price | Numeric | Yes | Purchase/landing unit cost price. |
product_items[].tax_id | String / Integer | No | Applied tax rule xid (or numeric ID). |
invoice_number | String | No | Supplier's delivery note or tax invoice number. |
all_payments | Array | No | Outward payments made at time of intake. |
all_payments[].amount | Numeric | Yes (if payment) | Amount disbursed to supplier. |
all_payments[].payment_mode_id | String / Integer | Yes (if payment) | Payment mode xid (e.g. bank transfer). |
Request Payload Example
{
"user_id": "<supplier-xid>",
"order_date": "2026-10-02",
"invoice_number": "DANGOTE-INV-99382",
"product_items": [
{
"product_id": "<product-xid>",
"quantity": 50,
"unit_price": 2200.00
}
],
"all_payments": [
{
"payment_mode_id": "<payment-mode-xid>",
"amount": 110000.00
}
]
}
Code Samples
cURL
curl -X POST "https://app.tracepos.net/api/v1/public/purchases" \
-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": "<supplier-xid>",
"order_date": "2026-10-02",
"invoice_number": "DANGOTE-INV-99382",
"product_items": [
{
"product_id": "<product-xid>",
"quantity": 50,
"unit_price": 2200.00
}
],
"all_payments": [
{
"payment_mode_id": "<payment-mode-xid>",
"amount": 110000.00
}
]
}'
Node.js (Axios)
const axios = require('axios');
async function createPurchase() {
const payload = {
user_id: '<supplier-xid>',
order_date: '2026-10-02',
invoice_number: 'DANGOTE-INV-99382',
product_items: [
{ product_id: '<product-xid>', quantity: 50, unit_price: 2200.00 },
],
all_payments: [
{ payment_mode_id: '<payment-mode-xid>', amount: 110000.00 },
],
};
const response = await axios.post(
'https://app.tracepos.net/api/v1/public/purchases',
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": "<supplier-xid>",
"order_date": "2026-10-02",
"invoice_number": "DANGOTE-INV-99382",
"product_items": [
{"product_id": "<product-xid>", "quantity": 50, "unit_price": 2200.00}
],
"all_payments": [
{"payment_mode_id": "<payment-mode-xid>", "amount": 110000.00}
],
}
response = requests.post("https://app.tracepos.net/api/v1/public/purchases", 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('purchases', [
'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' => '<supplier-xid>',
'order_date' => '2026-10-02',
'invoice_number' => 'DANGOTE-INV-99382',
'product_items' => [
['product_id' => '<product-xid>', 'quantity' => 50, 'unit_price' => 2200.00],
],
'all_payments' => [
['payment_mode_id' => '<payment-mode-xid>', 'amount' => 110000.00],
],
],
]);
$result = json_decode($response->getBody()->getContents(), true);
echo print_r($result, true);
Response (200 OK)
{
"status": "success",
"purchase_xid": "purch_a1b2c3d4e5",
"invoice_number": "DANGOTE-INV-99382",
"current_status": "Stock updated and entry recorded"
}
