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

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:

  1. Increments Physical Stock: Updates current_stock for each product line in the receiving warehouse.
  2. Creates Inventory Batches: Logs batch details for FIFO expiry and costing tracking.
  3. Posts Accounts Payable (A/P): Enters the liability into double-entry accounting (Debiting Inventory Asset 11700, Crediting Accounts Payable 21100).
  4. Dispatches Supplier Disbursements: If all_payments are 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: read

Query Parameters

ParameterTypeDefaultDescription
datesString-Date range filter in YYYY-MM-DD,YYYY-MM-DD format.
limitInteger20Results per page (max: 100).
pageInteger1Page 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: read

Path Parameters

ParameterTypeRequiredDescription
purchase-xidString / IntegerYesPurchase 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: write

Request Parameters

ParameterTypeRequiredDescription
user_idString / IntegerYesSupplier xid (or numeric ID for backward compatibility).
order_dateDate (YYYY-MM-DD)YesGoods receipt date (e.g. 2026-10-02).
product_itemsArrayYesArray of received stock items.
product_items[].product_idString / IntegerYesProduct xid (or numeric ID).
product_items[].quantityNumericYesUnits received into stock (min: 0.01).
product_items[].unit_priceNumericYesPurchase/landing unit cost price.
product_items[].tax_idString / IntegerNoApplied tax rule xid (or numeric ID).
invoice_numberStringNoSupplier's delivery note or tax invoice number.
all_paymentsArrayNoOutward payments made at time of intake.
all_payments[].amountNumericYes (if payment)Amount disbursed to supplier.
all_payments[].payment_mode_idString / IntegerYes (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"
}
Prev
Sales & Transactions API
Next
Inventory & Price Adjustments API