Expense Management API
Operational overheads—including store rent, generator diesel, utility bills, POS terminal roll paper, delivery motorbike fuel, and petty cash outlays—are tracked via the Expense Management API.
In Tracepos, expenses are integrated with the double-entry accounting engine:
- Immediate Settlement: If warehouse payment approval is disabled (
approve_payments = 0), recording an expense immediately debits the expense ledger account and credits the cash drawer or bank account. - Two-Step Approval & Pay-Off: If warehouse approval is enabled (
approve_payments = 1), expenses are logged aspendingliabilities crediting Accounts Payable (21100). Once approved, an external disbursement or manager records payment viaPOST /expenses/{id}/paymentsto release the funds.
1. List Expense Categories
Retrieve all active expense categories configured for your company. Each category maps to an internal general ledger expense account.
GET
/api/v1/public/expense-categoriesScope: readCode Samples
cURL
curl -X GET "https://app.tracepos.net/api/v1/public/expense-categories" \
-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 getExpenseCategories() {
const response = await axios.get('https://app.tracepos.net/api/v1/public/expense-categories', {
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/expense-categories", headers=headers)
categories = 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('expense-categories', [
'headers' => [
'X-Tracepos-Public-Key' => getenv('TRACEPOS_PUBLIC_KEY'),
'X-Tracepos-Secret-Key' => getenv('TRACEPOS_SECRET_KEY'),
'Accept' => 'application/json',
],
]);
$categories = json_decode($response->getBody()->getContents(), true)['data'];
Response (200 OK)
{
"status": "success",
"data": [
{
"id": 1,
"name": "Fuel & Generator Diesel",
"description": "Store generator and delivery motorbike fueling"
},
{
"id": 2,
"name": "Store Maintenance & Repairs",
"description": "AC repairs, lighting, POS hardware replacement"
},
{
"id": 3,
"name": "Office Supplies & Stationeries",
"description": "Receipt rolls, barcode labels, packaging bags"
}
]
}
2. List Recorded Expenses
Retrieve historical expenses logged in the authorized warehouse.
GET
/api/v1/public/expensesScope: readQuery Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
dates | String | - | Filter by date range YYYY-MM-DD,YYYY-MM-DD. |
expense_status | String | all | Filter by approval status: approved, pending. |
limit | Integer | 20 | Results per page (max: 100). |
page | Integer | 1 | Page number. |
Response (200 OK)
{
"status": "success",
"data": {
"current_page": 1,
"per_page": 20,
"total": 18,
"data": [
{
"id": 42,
"expense_number": "EXP-18",
"date": "2026-09-30",
"amount": "8500.00",
"paid_amount": "8500.00",
"due_amount": "0.00",
"expense_status": "approved",
"payment_status": "paid",
"notes": "Thermal paper rolls for POS terminals",
"expense_category": {
"id": 3,
"name": "Office Supplies & Stationeries"
},
"payment_mode": {
"id": 1,
"name": "Cash Drawer"
}
}
]
}
}
3. Record New Expense
Log an operational expense.
POST
/api/v1/public/expensesScope: writeRequest Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
expense_category_id | Integer / String | Yes | Category ID or Hash ID (e.g. 1). |
amount | Numeric | Yes | Expense amount (min: 0.01). |
date | Date | Yes | Expense date (YYYY-MM-DD). |
payment_mode_id | Integer / String | No | Payment method ID (required if warehouse is auto-approved). |
notes | String | No | Narrative description or invoice receipt note. |
Request Payload Example
{
"expense_category_id": "<expense-category-xid>",
"amount": 15000.00,
"payment_mode_id": "<payment-mode-xid>",
"date": "2026-10-02",
"notes": "Purchased 20L diesel for generator"
}
Code Samples
cURL
curl -X POST "https://app.tracepos.net/api/v1/public/expenses" \
-H "X-Tracepos-Public-Key: <public-key>" \
-H "X-Tracepos-Secret-Key: <secret-key>" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"expense_category_id": "<expense-category-xid>",
"amount": 15000.00,
"payment_mode_id": "<payment-mode-xid>",
"date": "2026-10-02",
"notes": "Purchased 20L diesel for generator"
}'
Node.js (Axios)
const axios = require('axios');
async function recordExpense() {
const payload = {
expense_category_id: '<expense-category-xid>',
amount: 15000.00,
payment_mode_id: '<payment-mode-xid>',
date: '2026-10-02',
notes: 'Purchased 20L diesel for generator',
};
const response = await axios.post(
'https://app.tracepos.net/api/v1/public/expenses',
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 = {
"expense_category_id": "<expense-category-xid>",
"amount": 15000.00,
"payment_mode_id": "<payment-mode-xid>",
"date": "2026-10-02",
"notes": "Purchased 20L diesel for generator",
}
response = requests.post("https://app.tracepos.net/api/v1/public/expenses", 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('expenses', [
'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' => [
'expense_category_id' => '<expense-category-xid>',
'amount' => 15000.00,
'payment_mode_id' => '<payment-mode-xid>',
'date' => '2026-10-02',
'notes' => 'Purchased 20L diesel for generator',
],
]);
$result = json_decode($response->getBody()->getContents(), true);
echo print_r($result, true);
Response (200 OK)
{
"status": "success",
"expense_number": "EXP-19"
}
4. Pay Off Due Expense
When an expense was created in a warehouse with payment approval enabled (expense_status = "pending" and due_amount > 0), use this endpoint to record the disbursement once approved.
POST
/api/v1/public/expenses/{expense-xid}/paymentsScope: writeRequest Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
expense_id | String / Integer | Yes | Expense xid (or numeric ID for backward compatibility). |
payment_mode_id | String / Integer | Yes | Disbursement payment method xid (Cash / Bank). |
amount | Numeric | Yes | Amount paid (cannot exceed due_amount, min: 0.01). |
date | Date | Yes | Disbursement date (YYYY-MM-DD). |
Request Payload Example
{
"expense_id": "<expense-xid>",
"payment_mode_id": "<payment-mode-xid>",
"amount": 15000.00,
"date": "2026-10-02"
}
Code Samples
cURL
curl -X POST "https://app.tracepos.net/api/v1/public/expenses/<expense-xid>/payments" \
-H "X-Tracepos-Public-Key: <public-key>" \
-H "X-Tracepos-Secret-Key: <secret-key>" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"expense_id": "<expense-xid>",
"payment_mode_id": "<payment-mode-xid>",
"amount": 15000.00,
"date": "2026-10-02"
}'
Node.js (Axios)
const axios = require('axios');
async function payExpense(expenseXid, paymentModeXid, amount, date) {
const response = await axios.post(
`https://app.tracepos.net/api/v1/public/expenses/${expenseXid}/payments`,
{
expense_id: expenseXid,
payment_mode_id: paymentModeXid,
amount: amount,
date: date,
},
{
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 = {
"expense_id": "<expense-xid>",
"payment_mode_id": "<payment-mode-xid>",
"amount": 15000.00,
"date": "2026-10-02",
}
response = requests.post(
"https://app.tracepos.net/api/v1/public/expenses/<expense-xid>/payments",
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('expenses/<expense-xid>/payments', [
'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' => [
'expense_id' => '<expense-xid>',
'payment_mode_id' => '<payment-mode-xid>',
'amount' => 15000.00,
'date' => '2026-10-02',
],
]);
echo $response->getBody();
Response (200 OK)
{
"status": "success",
"new_due": 0
}
