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

Returns & Reversals API

The Returns module handles customer product returns (Sales Returns) and vendor product reversals (Purchase Returns).

Every return processed through the Tracepos API triggers an automated reconciliation cycle:

  • Restocks or Deducts Inventory: Adjusts physical warehouse on-hand levels.
  • Updates Party Ledgers: Reduces customer debt (A/R) or supplier liability (A/P).
  • Posts Balanced Accounting Reversals: Posts contra-revenue or contra-expense entries to the general ledger.

1. Sales Returns (Customer Refunds & Restock)

Process merchandise returned by a retail or wholesale customer.

List Sales Returns

Retrieve a paginated list of sales returns for the authorized warehouse.

GET/api/v1/public/sales-returnsScope: read

Query Parameters

ParameterTypeDefaultDescription
limitInteger20Items per page (max: 100).
pageInteger1Pagination page number.

Code Samples

cURL
curl -X GET "https://app.tracepos.net/api/v1/public/sales-returns?limit=20" \
  -H "X-Tracepos-Public-Key: <public-key>" \
  -H "X-Tracepos-Secret-Key: <secret-key>" \
  -H "Accept: application/json"
Node.js (Axios)
const axios = require('axios');

async function listSalesReturns() {
  const response = await axios.get('https://app.tracepos.net/api/v1/public/sales-returns', {
    params: { limit: 20 },
    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;
}
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/sales-returns",
    params={"limit": 20},
    headers=headers,
)
returns = 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('sales-returns', [
    'query' => ['limit' => 20],
    'headers' => [
        'X-Tracepos-Public-Key' => getenv('TRACEPOS_PUBLIC_KEY'),
        'X-Tracepos-Secret-Key' => getenv('TRACEPOS_SECRET_KEY'),
        'Accept'                => 'application/json',
    ],
]);

$returns = json_decode($response->getBody()->getContents(), true)['data'];

Response (200 OK)

{
  "status": "success",
  "data": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 20,
    "total": 6,
    "data": [
      {
        "id": 25,
        "xid": "xret_89410ef1",
        "unique_id": "ord_sret_89410ef",
        "invoice_number": "SRET-00012",
        "order_type": "sales-returns",
        "order_date": "2026-09-29",
        "total": 2750.00,
        "due_amount": 2750.00,
        "notes": "Customer returned unopened carton",
        "user": {
          "id": 105,
          "name": "Adeola Adeleke"
        }
      }
    ]
  }
}

Record Sales Return

Record items returned by a customer. This automatically increments physical warehouse stock and updates customer debt.

POST/api/v1/public/sales-returnsScope: write

Request Parameters

ParameterTypeRequiredDescription
user_idString / IntegerYesCustomer xid (or numeric ID).
order_dateDate (YYYY-MM-DD)YesReturn transaction date.
itemsArrayYesReturned items array (minimum 1 item).
items[].product_idString / IntegerYesProduct xid (or numeric ID).
items[].quantityNumericYesQuantity returned (min: 0.01).
items[].unit_priceNumericYesRefund price per unit.
notesStringNoReason for return.
invoice_numberStringNoOriginal sale invoice reference (e.g. SAL-00451).

Request Payload

{
  "user_id": "<customer-xid>",
  "order_date": "2026-09-30",
  "invoice_number": "SAL-00451",
  "notes": "Customer returned unopened carton",
  "items": [
    {
      "product_id": "<product-xid>",
      "quantity": 1,
      "unit_price": 2750.00
    }
  ]
}

Code Samples

cURL
curl -X POST "https://app.tracepos.net/api/v1/public/sales-returns" \
  -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": "<customer-xid>",
    "order_date": "2026-09-30",
    "invoice_number": "SAL-00451",
    "notes": "Customer returned unopened carton",
    "items": [
      {
        "product_id": "<product-xid>",
        "quantity": 1,
        "unit_price": 2750.00
      }
    ]
  }'
Node.js (Axios)
const axios = require('axios');

async function processSalesReturn(returnData) {
  const response = await axios.post(
    'https://app.tracepos.net/api/v1/public/sales-returns',
    returnData,
    {
      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": "<customer-xid>",
    "order_date": "2026-09-30",
    "invoice_number": "SAL-00451",
    "notes": "Customer returned unopened carton",
    "items": [
        {
            "product_id": "<product-xid>",
            "quantity": 1,
            "unit_price": 2750.00,
        }
    ],
}

response = requests.post(
    "https://app.tracepos.net/api/v1/public/sales-returns",
    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('sales-returns', [
    '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'        => '<customer-xid>',
        'order_date'     => '2026-09-30',
        'invoice_number' => 'SAL-00451',
        'notes'          => 'Customer returned unopened carton',
        'items'          => [
            ['product_id' => '<product-xid>', 'quantity' => 1, 'unit_price' => 2750.00],
        ],
    ],
]);

$result = json_decode($response->getBody()->getContents(), true);
echo print_r($result, true);

Response (200 OK)

{
  "status": "success",
  "return_xid": "xret_89410ef1",
  "invoice_number": "SRET-00013"
}

2. Purchase Returns (Supplier Stock Return)

Return substandard, damaged, or excess inventory back to a vendor. This decrements warehouse stock and credits your accounts payable ledger.

List Purchase Returns

Retrieve a paginated history of purchase returns for the authorized warehouse.

GET/api/v1/public/purchase-returnsScope: read

Query Parameters

ParameterTypeDefaultDescription
limitInteger20Items per page (max: 100).
pageInteger1Pagination page number.

Code Samples

cURL
curl -X GET "https://app.tracepos.net/api/v1/public/purchase-returns?limit=20" \
  -H "X-Tracepos-Public-Key: <public-key>" \
  -H "X-Tracepos-Secret-Key: <secret-key>" \
  -H "Accept: application/json"
Node.js (Axios)
const axios = require('axios');

async function listPurchaseReturns() {
  const response = await axios.get('https://app.tracepos.net/api/v1/public/purchase-returns', {
    params: { limit: 20 },
    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;
}
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/purchase-returns",
    params={"limit": 20},
    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->get('purchase-returns', [
    'query' => ['limit' => 20],
    'headers' => [
        'X-Tracepos-Public-Key' => getenv('TRACEPOS_PUBLIC_KEY'),
        'X-Tracepos-Secret-Key' => getenv('TRACEPOS_SECRET_KEY'),
        'Accept'                => 'application/json',
    ],
]);

$returns = json_decode($response->getBody()->getContents(), true)['data'];

Response (200 OK)

{
  "status": "success",
  "data": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 20,
    "total": 3,
    "data": [
      {
        "id": 18,
        "xid": "pret_38927bc4",
        "unique_id": "ord_pret_38927bc",
        "invoice_number": "PRET-00008",
        "order_type": "purchase-returns",
        "order_date": "2026-09-30",
        "total": 25000.00,
        "due_amount": 25000.00,
        "user": {
          "id": 201,
          "name": "Dangote Sugar Refinery Plc"
        }
      }
    ]
  }
}

Record Purchase Return

POST/api/v1/public/purchase-returnsScope: write

Request Parameters

ParameterTypeRequiredDescription
user_idString / IntegerYesSupplier xid (or numeric ID).
order_dateDate (YYYY-MM-DD)YesReturn dispatch date.
itemsArrayYesReturned stock array (minimum 1 item).
items[].product_idString / IntegerYesProduct xid (or numeric ID).
items[].quantityNumericYesQuantity returned to supplier (min: 0.01).
items[].unit_priceNumericYesCredit cost price agreed with vendor.

Request Payload

{
  "user_id": "<supplier-xid>",
  "order_date": "2026-09-30",
  "items": [
    {
      "product_id": "<product-xid>",
      "quantity": 10,
      "unit_price": 2500.00
    }
  ]
}

Code Samples

cURL
curl -X POST "https://app.tracepos.net/api/v1/public/purchase-returns" \
  -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-09-30",
    "items": [
      {
        "product_id": "<product-xid>",
        "quantity": 10,
        "unit_price": 2500.00
      }
    ]
  }'
Node.js (Axios)
const axios = require('axios');

async function processPurchaseReturn(payload) {
  const response = await axios.post(
    'https://app.tracepos.net/api/v1/public/purchase-returns',
    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-09-30",
    "items": [
        {
            "product_id": "<product-xid>",
            "quantity": 10,
            "unit_price": 2500.00,
        }
    ],
}

response = requests.post(
    "https://app.tracepos.net/api/v1/public/purchase-returns",
    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('purchase-returns', [
    '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-09-30',
        'items'      => [
            ['product_id' => '<product-xid>', 'quantity' => 10, 'unit_price' => 2500.00],
        ],
    ],
]);

$result = json_decode($response->getBody()->getContents(), true);
echo print_r($result, true);

Response (200 OK)

{
  "status": "success",
  "return_xid": "pret_38927bc4",
  "invoice_number": "PRET-00008"
}

Return Ledger Rules

  1. Sales Return Accounting:
    • Debit: 41200 Sales Returns (Contra-Revenue)
    • Credit: 11500 Accounts Receivable (or Cash drawer if immediately refunded)
    • Inventory Restock: Stock is incremented in product_details for the receiving warehouse.
  2. Purchase Return Accounting:
    • Debit: 21100 Accounts Payable (reducing supplier debt)
    • Credit: 11700 Inventory Asset (or 51200 Purchase Returns)
    • Stock Reduction: Stock is decremented in product_details for the dispatching warehouse.
Prev
Inventory & Price Adjustments API