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

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 as pending liabilities crediting Accounts Payable (21100). Once approved, an external disbursement or manager records payment via POST /expenses/{id}/payments to 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: read

Code 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: read

Query Parameters

ParameterTypeDefaultDescription
datesString-Filter by date range YYYY-MM-DD,YYYY-MM-DD.
expense_statusStringallFilter by approval status: approved, pending.
limitInteger20Results per page (max: 100).
pageInteger1Page 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: write

Request Parameters

ParameterTypeRequiredDescription
expense_category_idInteger / StringYesCategory ID or Hash ID (e.g. 1).
amountNumericYesExpense amount (min: 0.01).
dateDateYesExpense date (YYYY-MM-DD).
payment_mode_idInteger / StringNoPayment method ID (required if warehouse is auto-approved).
notesStringNoNarrative 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: write

Request Parameters

ParameterTypeRequiredDescription
expense_idString / IntegerYesExpense xid (or numeric ID for backward compatibility).
payment_mode_idString / IntegerYesDisbursement payment method xid (Cash / Bank).
amountNumericYesAmount paid (cannot exceed due_amount, min: 0.01).
dateDateYesDisbursement 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
}
Prev
Payments & Settlements API
Next
Double-Entry Accounting Architecture