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

Inventory & Price Adjustments API

Accurate retail and warehouse management requires handling non-sale physical inventory variations (breakage, spoilage, shrinkage, audit counts) and programmatic price updates (repricing campaigns, inflation adjustments, competitor matching).

The Adjustments API covers both Stock Adjustments (physical quantity alterations with automated ledger reconciliation) and Price Adjustments (retail price modifications with historical audit logs).


1. Stock Adjustments

Stock adjustments change on-hand inventory levels outside the standard sales/procurement pipeline.

List Stock Adjustments

Retrieve historical stock adjustments performed at the authorized warehouse.

GET/api/v1/public/stock-adjustmentsScope: read

Response (200 OK)

{
  "status": "success",
  "data": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 20,
    "total": 14,
    "data": [
      {
        "id": 14,
        "xid": "adj_8912ef34",
        "product_id": 45,
        "quantity": "5.00",
        "adjustment_type": "subtract",
        "notes": "Damaged goods in transit",
        "created_at": "2026-09-29T11:20:00.000000Z",
        "product": {
          "id": 45,
          "name": "Premium Basmati Rice 5kg",
          "item_code": "RICE-5KG-01"
        },
        "creator": {
          "id": 1,
          "name": "Warehouse Manager"
        }
      }
    ]
  }
}

Get Single Stock Adjustment

Retrieve details of a specific stock adjustment.

GET/api/v1/public/stock-adjustments/{stock-adjustment-xid}Scope: read

Path Parameters

ParameterTypeRequiredDescription
stock-adjustment-xidString / IntegerYesAdjustment Hash ID (xid). Positive numeric IDs are accepted for backward compatibility.

Response (200 OK)

{
  "status": "success",
  "data": {
    "id": 14,
    "xid": "adj_8912ef34",
    "warehouse_id": 1,
    "product_id": 45,
    "quantity": "5.00",
    "adjustment_type": "subtract",
    "notes": "Damaged goods in transit",
    "created_at": "2026-09-29T11:20:00.000000Z",
    "product": {
      "id": 45,
      "name": "Premium Basmati Rice 5kg",
      "item_code": "RICE-5KG-01"
    },
    "creator": {
      "id": 1,
      "name": "Warehouse Manager"
    }
  }
}

Record Stock Adjustment

Submit a physical stock count adjustment. Tracepos immediately recalculates warehouse stock levels and posts an automated journal entry between Inventory Asset (11700) and COGS / Inventory Loss (51100).

POST/api/v1/public/stock-adjustmentsScope: inventory

Request Parameters

ParameterTypeRequiredDescription
product_idString / IntegerYesProduct xid (or numeric ID for backward compatibility).
quantityNumericYesQuantity to add or subtract (min: 0.01).
adjustment_typeStringYes'add' (increase on-hand) or 'subtract' (decrease on-hand).
notesStringNoAudit reason (e.g. Physical audit recount, Water damage).
batch_numberString / IntegerNoProduct batch xid (or numeric ID) if adjusting tracked batch stock.
expiry_dateDate (YYYY-MM-DD)NoBatch expiry date.

Request Payload Example

{
  "product_id": "<product-xid>",
  "quantity": 2,
  "adjustment_type": "add"
}

Code Samples

cURL
curl -X POST "https://app.tracepos.net/api/v1/public/stock-adjustments" \
  -H "X-Tracepos-Public-Key: <public-key>" \
  -H "X-Tracepos-Secret-Key: <secret-key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "product_id": "<product-xid>",
    "quantity": 2,
    "adjustment_type": "add",
    "notes": "Physical inventory recount"
  }'
Node.js (Axios)
const axios = require('axios');

async function adjustStock(productId, quantity, type, notes) {
  const response = await axios.post(
    'https://app.tracepos.net/api/v1/public/stock-adjustments',
    {
      product_id: productId,
      quantity: quantity,
      adjustment_type: type,
      notes: notes,
    },
    {
      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 = {
    "product_id": "<product-xid>",
    "quantity": 2,
    "adjustment_type": "add",
    "notes": "Physical inventory recount",
}

response = requests.post(
    "https://app.tracepos.net/api/v1/public/stock-adjustments",
    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('stock-adjustments', [
    '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' => [
        'product_id'      => '<product-xid>',
        'quantity'        => 2,
        'adjustment_type' => 'add',
        'notes'           => 'Physical inventory recount',
    ],
]);

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

Response (200 OK)

{
  "status": "success",
  "adjustment_xid": "adj_8912ef34",
  "new_stock_level": 42.00
}

2. Price Adjustments

The Price Adjustment API lets POS management systems and eCommerce pricing engines update unit selling prices while maintaining an immutable audit history of price revisions.

List Price Adjustment Batches

GET/api/v1/public/price-adjustmentsScope: read

Response (200 OK)

{
  "status": "success",
  "data": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 20,
    "total": 8,
    "data": [
      {
        "id": 8,
        "xid": "padj_99182ab3",
        "invoice_number": "PRCADJ-00041",
        "date": "2026-09-25",
        "notes": "Price update via Public API",
        "creator": {
          "id": 1,
          "name": "Finance Admin"
        }
      }
    ]
  }
}

Get Single Price Adjustment Batch

GET/api/v1/public/price-adjustments/{price-adjustment-xid}Scope: read

Path Parameters

ParameterTypeRequiredDescription
price-adjustment-xidString / IntegerYesBatch Hash ID (xid). Positive numeric IDs are accepted for backward compatibility.

Response (200 OK)

{
  "status": "success",
  "data": {
    "id": 8,
    "xid": "padj_99182ab3",
    "invoice_number": "PRCADJ-00041",
    "date": "2026-09-25",
    "notes": "Price update via Public API",
    "creator": {
      "id": 1,
      "name": "Finance Admin"
    },
    "items": [
      {
        "id": 12,
        "adjustment_id": 8,
        "product_id": 45,
        "old_sale_price": "1400.00",
        "new_sale_price": "1500.00",
        "product": {
          "id": 45,
          "name": "Premium Basmati Rice 5kg",
          "item_code": "RICE-5KG-01"
        }
      }
    ]
  }
}

Update Product Price

Update a product's retail selling price for the authorized warehouse.

POST/api/v1/public/price-adjustmentsScope: inventory

Request Parameters

ParameterTypeRequiredDescription
product_idString / IntegerYesProduct xid (or numeric ID for backward compatibility).
new_sales_priceNumericYesNew selling price (must be zero or greater, min: 0.00).

Request Payload Example

{
  "product_id": "<product-xid>",
  "new_sales_price": 1500
}

Code Samples

cURL
curl -X POST "https://app.tracepos.net/api/v1/public/price-adjustments" \
  -H "X-Tracepos-Public-Key: <public-key>" \
  -H "X-Tracepos-Secret-Key: <secret-key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "product_id": "<product-xid>",
    "new_sales_price": 1500
  }'
Node.js (Axios)
const axios = require('axios');

async function updatePrice(productId, newPrice) {
  const response = await axios.post(
    'https://app.tracepos.net/api/v1/public/price-adjustments',
    {
      product_id: productId,
      new_sales_price: newPrice,
    },
    {
      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 = {
    "product_id": "<product-xid>",
    "new_sales_price": 1500,
}

response = requests.post(
    "https://app.tracepos.net/api/v1/public/price-adjustments",
    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('price-adjustments', [
    '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' => [
        'product_id'      => '<product-xid>',
        'new_sales_price' => 1500,
    ],
]);

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

Response (200 OK)

{
  "status": "success",
  "batch_invoice": "PRCADJ-00042",
  "new_price": 1500
}

Accounting & Inventory Integrity

Double-Entry Valuation

Whenever stock is added or subtracted via POST /stock-adjustments, the cost value of the movement ($\text{Cost} = \text{purchase_price} \times \text{quantity}$) is posted to the general ledger:

  • Add Stock (add):
    • Debit: 11700 Inventory Asset
    • Credit: 51100 Inventory Adjustment Gain
  • Subtract Stock (subtract):
    • Debit: 51100 Inventory Shrinkage & Loss (COGS)
    • Credit: 11700 Inventory Asset
Prev
Purchases & Procurement API
Next
Returns & Reversals API