Inventory API

The Inventory module tracks stock levels across warehouses and locations, manages incoming and outgoing transfers, and records inventory adjustments. It integrates with Purchase orders (incoming) and Sales orders (outgoing).

---

Endpoints

Method	Path	Description
GET	/api/inventory/products	List products with stock levels
GET	/api/inventory/products/:productId/stock	Get stock by location
GET	/api/inventory/transfers	List transfers (paginated)
POST	/api/inventory/transfers	Create a transfer
GET	/api/inventory/transfers/:id	Get a transfer
POST	/api/inventory/transfers/:id/validate	Validate (complete) a transfer
POST	/api/inventory/transfers/:id/cancel	Cancel a transfer
GET	/api/inventory/locations	List warehouse locations
POST	/api/inventory/adjustments	Post an inventory adjustment
GET	/api/inventory/moves	List stock moves

---

Stock Levels

List Products with Stock

GET /api/inventory/products?page=1&limit=20&belowReorder=true

Query Parameters

Parameter	Type	Description
belowReorder	boolean	Only show items below reorder point
warehouseId	string	Filter by warehouse
search	string	Search product name or SKU

Response

{
  "data": [
    {
      "productId": "018e5678-abcd-7000-8000-000000000001",
      "productName": "ECOSIRE Widget Pro",
      "sku": "WGT-PRO-001",
      "onHand": 142,
      "reserved": 30,
      "available": 112,
      "reorderPoint": 50,
      "uom": "units"
    }
  ],
  "meta": { "total": 86, "page": 1, "limit": 20, "totalPages": 5 }
}

Stock by Location

GET /api/inventory/products/018e5678-abcd-7000-8000-000000000001/stock

[
  { "locationId": "LOC-WH01-A1", "locationName": "Warehouse 01 / Shelf A1", "quantity": 80 },
  { "locationId": "LOC-WH02-B3", "locationName": "Warehouse 02 / Shelf B3", "quantity": 62 }
]

---

Transfers

Transfers represent the movement of stock between locations — receipts (incoming), deliveries (outgoing), or internal moves.

List Transfers

GET /api/inventory/transfers?type=receipt&status=ready&page=1&limit=20

Query Parameters

Parameter	Type	Description
type	receipt | delivery | internal	Transfer type
status	draft | ready | done | cancelled	Transfer status
from	ISO 8601	Scheduled date from
to	ISO 8601	Scheduled date to

Response

{
  "data": [
    {
      "id": "018edddd-abcd-7000-8000-000000000001",
      "reference": "WH/IN/00042",
      "type": "receipt",
      "status": "ready",
      "sourceLocation": "Suppliers",
      "destinationLocation": "WH/Stock",
      "scheduledDate": "2026-03-22T00:00:00Z",
      "moves": [
        {
          "productId": "018e5678-abcd-7000-8000-000000000001",
          "productName": "ECOSIRE Widget Pro",
          "demandQty": 100,
          "doneQty": 0
        }
      ]
    }
  ],
  "meta": { "total": 23, "page": 1, "limit": 20, "totalPages": 2 }
}

Create a Transfer

POST /api/inventory/transfers
Content-Type: application/json

{
  "type": "internal",
  "sourceLocationId": "LOC-WH01-A1",
  "destinationLocationId": "LOC-WH02-B3",
  "scheduledDate": "2026-03-25T09:00:00Z",
  "moves": [
    {
      "productId": "018e5678-abcd-7000-8000-000000000001",
      "demandQty": 20
    }
  ]
}

Validate a Transfer

Marks all move lines as done using demand quantities. Pass doneQty overrides to record partial completion.

POST /api/inventory/transfers/018edddd-abcd-7000-8000-000000000001/validate
Content-Type: application/json

{
  "moves": [
    { "productId": "018e5678-abcd-7000-8000-000000000001", "doneQty": 95 }
  ]
}

---

Inventory Adjustment

Correct stock discrepancies found during a physical count.

POST /api/inventory/adjustments
Content-Type: application/json

{
  "locationId": "LOC-WH01-A1",
  "date": "2026-03-20T00:00:00Z",
  "reason": "Physical count discrepancy",
  "lines": [
    {
      "productId": "018e5678-abcd-7000-8000-000000000001",
      "theoreticalQty": 80,
      "realQty": 77,
      "difference": -3
    }
  ]
}

---

Status Codes

Code	Scenario
200	Get or list succeeded
201	Transfer or adjustment created
400	Transfer already validated or cancelled
404	Transfer or product not found
422	doneQty exceeds demandQty or negative quantity