Inventory Management

The inventory module tracks banking stationery and consumables — cheque books, deposit slips, teller rolls, branded materials, and other branch supplies. It provides purchase order workflows, stock level monitoring, and low-stock alerts.

Concepts

Concept	Description
Category	Grouping for inventory items (e.g., "Cheque Books", "Deposit Slips", "Teller Supplies")
Item	A specific inventory item with SKU, unit cost, and stock levels
Purchase Order	A request to procure items from a vendor
Stock Count	Physical inventory verification against system records
Vendor	Supplier of inventory items

List Inventory Items

GET /api/v1/inventory/items

cURL

curl "https://api.korastratum.com/api/v1/cba/inventory/items?category=cheque_books&low_stock=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: demo_bank"

Node.js

const items = await cbaRequest("GET", "/api/v1/inventory/items?category=cheque_books&low_stock=true", token);

Python

items = cba_request("GET", "/api/v1/inventory/items?category=cheque_books&low_stock=true", token)

Go

items, err := cbaRequest(ctx, "GET", "/api/v1/inventory/items?category=cheque_books&low_stock=true", token, nil)

Response:

{
  "items": [
    {
      "id": "item-uuid",
      "sku": "CHQ-50L-NGN",
      "name": "50-Leaf Cheque Book (NGN)",
      "category": "cheque_books",
      "unit_cost": 2500.00,
      "currency": "NGN",
      "quantity_on_hand": 45,
      "reorder_level": 100,
      "reorder_quantity": 500,
      "is_low_stock": true,
      "branch_id": "branch-uuid",
      "vendor_id": "vendor-uuid",
      "last_restocked_at": "2026-03-15T10:00:00Z"
    }
  ],
  "total": 1
}

Create a Purchase Order

POST /api/v1/inventory/purchase-orders

cURL

curl -X POST https://api.korastratum.com/api/v1/cba/inventory/purchase-orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: demo_bank" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_id": "vendor-uuid",
    "branch_id": "branch-uuid",
    "items": [
      {
        "item_id": "item-uuid",
        "quantity": 500,
        "unit_cost": 2500.00
      }
    ],
    "notes": "Quarterly cheque book restock",
    "requested_by": "user-uuid"
  }'

Node.js

const po = await cbaRequest("POST", "/api/v1/inventory/purchase-orders", token, {
  vendor_id: "vendor-uuid",
  branch_id: "branch-uuid",
  items: [{ item_id: "item-uuid", quantity: 500, unit_cost: 2500.0 }],
  notes: "Quarterly cheque book restock",
  requested_by: "user-uuid",
});

Python

po = cba_request("POST", "/api/v1/inventory/purchase-orders", token, {
    "vendor_id": "vendor-uuid",
    "branch_id": "branch-uuid",
    "items": [{"item_id": "item-uuid", "quantity": 500, "unit_cost": 2500.00}],
    "notes": "Quarterly cheque book restock",
    "requested_by": "user-uuid",
})

Go

po, err := cbaRequest(ctx, "POST", "/api/v1/inventory/purchase-orders", token, map[string]interface{}{
    "vendor_id":  "vendor-uuid",
    "branch_id":  "branch-uuid",
    "items":      []map[string]interface{}{{"item_id": "item-uuid", "quantity": 500, "unit_cost": 2500.0}},
    "notes":      "Quarterly cheque book restock",
    "requested_by": "user-uuid",
})

Purchase order statuses:

Status	Description
DRAFT	Created, not yet submitted
SUBMITTED	Submitted for approval
APPROVED	Approved by manager
ORDERED	Sent to vendor
RECEIVED	Items received and stocked
CANCELLED	Order cancelled

Receive Items

When a purchase order is delivered, receive the items into inventory:

POST /api/v1/inventory/items/receive

{
  "purchase_order_id": "po-uuid",
  "items": [
    {
      "item_id": "item-uuid",
      "quantity_received": 500,
      "condition": "GOOD"
    }
  ],
  "received_by": "user-uuid",
  "notes": "All items in good condition"
}

This updates quantity_on_hand and marks the purchase order as RECEIVED.

Dashboard Summary

Get an overview of inventory status across all branches.

GET /api/v1/inventory/dashboard/summary

Response:

{
  "total_items": 156,
  "total_value": 12500000.00,
  "currency": "NGN",
  "low_stock_count": 12,
  "out_of_stock_count": 3,
  "pending_orders": 5,
  "categories": [
    { "name": "cheque_books", "item_count": 24, "total_value": 3200000.00 },
    { "name": "deposit_slips", "item_count": 18, "total_value": 450000.00 },
    { "name": "teller_supplies", "item_count": 42, "total_value": 1800000.00 }
  ]
}

Low-Stock Alerts

GET /api/v1/inventory/alerts/low-stock

Returns items where quantity_on_hand is at or below reorder_level.

Response:

{
  "alerts": [
    {
      "item_id": "item-uuid",
      "sku": "CHQ-50L-NGN",
      "name": "50-Leaf Cheque Book (NGN)",
      "branch_name": "Head Office",
      "quantity_on_hand": 45,
      "reorder_level": 100,
      "suggested_order_quantity": 500,
      "vendor_name": "ABC Printing Ltd"
    }
  ],
  "total_alerts": 12
}

tip

Subscribe to the inventory.low_stock webhook event to get notified automatically when items drop below their reorder level, rather than polling this endpoint.

Next Steps

• Accounts — Customer account management.
• Webhooks — Subscribe to inventory events.
• Sandbox Testing — Test inventory flows in sandbox.