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: readQuery Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | Integer | 20 | Items per page (max: 100). |
page | Integer | 1 | Pagination 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: writeRequest Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
user_id | String / Integer | Yes | Customer xid (or numeric ID). |
order_date | Date (YYYY-MM-DD) | Yes | Return transaction date. |
items | Array | Yes | Returned items array (minimum 1 item). |
items[].product_id | String / Integer | Yes | Product xid (or numeric ID). |
items[].quantity | Numeric | Yes | Quantity returned (min: 0.01). |
items[].unit_price | Numeric | Yes | Refund price per unit. |
notes | String | No | Reason for return. |
invoice_number | String | No | Original 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: readQuery Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | Integer | 20 | Items per page (max: 100). |
page | Integer | 1 | Pagination 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: writeRequest Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
user_id | String / Integer | Yes | Supplier xid (or numeric ID). |
order_date | Date (YYYY-MM-DD) | Yes | Return dispatch date. |
items | Array | Yes | Returned stock array (minimum 1 item). |
items[].product_id | String / Integer | Yes | Product xid (or numeric ID). |
items[].quantity | Numeric | Yes | Quantity returned to supplier (min: 0.01). |
items[].unit_price | Numeric | Yes | Credit 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
- Sales Return Accounting:
- Debit:
41200Sales Returns (Contra-Revenue) - Credit:
11500Accounts Receivable (or Cash drawer if immediately refunded) - Inventory Restock: Stock is incremented in
product_detailsfor the receiving warehouse.
- Debit:
- Purchase Return Accounting:
- Debit:
21100Accounts Payable (reducing supplier debt) - Credit:
11700Inventory Asset (or51200Purchase Returns) - Stock Reduction: Stock is decremented in
product_detailsfor the dispatching warehouse.
- Debit:
