Building on it
Inventory ledger
All routes are under /v1/merchants/{merchantId} and resolve the merchant through the caller's scope: a merchant outside
the caller's subtree is a 404. Humans act by role (read: every role; write catalog/stock: Admin, Owner, Manager,
Stockkeeper); API keys need catalog:read|write, inventory:read|write. Money is whole kobo (long);
quantities are decimals with up to 3 places.
Catalog#
- Product (name, unit,
taxClassStandard=7.5% VAT / Exempt / ZeroRated,trackStock) → Variants (the sellable unit:sku,barcode?,priceKobo,costKobo?). A simple product has one variant. SKU (stored uppercase) and barcode are unique per merchant; the same values at another merchant are fine. Items are deactivated, never deleted (sales history). PUT …/variants/{id}/prices/{branchId}sets a per-branch price;DELETEremoves it.GET …/products?q=matches a name fragment, an exact SKU or an exact barcode.GET …/lookup?barcode=resolves one scan.
Delta feed — GET …/catalog?branchId=&cursor=&limit=#
Keyset feed ordered by (updatedAt, id); the cursor is opaque, keep what you are given. First call has no cursor and returns
active items only; keep calling with the returned cursor while hasMore. Later calls return only what changed, and anything
deactivated arrives as deleted: true. An unchanged feed hands the same cursor back. Prices are resolved for branchId;
onHandHint is advisory (it does not bump the feed — refresh it with the stock endpoint).
(The plan said ETag; a cursor is strictly better for paging a delta.)
Terminal profile — /v1/terminal/* (terminal session token only)#
Merchant and branch come from the token, never the URL. GET catalog (same feed, lean fields: no cost/description/admin flags),
GET lookup?barcode=, GET stock/{variantId}. A terminal token is refused everywhere else, and humans/keys are refused here.
Inventory — the ledger#
StockMovement is append-only (a database trigger rejects UPDATE/DELETE); a StockLevel is a cache of it. Every change
goes through IStockLedger, which per movement runs ONE atomic UPDATE … SET "OnHand" = "OnHand" + @qty … RETURNING (row-locked,
so concurrent callers queue and no update is lost), computes the weighted-average cost in the same statement, and appends the
ledger row with the returned balanceAfter in the same transaction. Invariant, asserted in tests: OnHand == SUM(Qty).
- Batches are all-or-nothing and applied in a fixed (variant, branch) order, so opposite-order batches cannot deadlock.
- Removing stock below zero is refused (
409 insufficient_stock) except for paid sales (Phase 4) and physical counts, where the goods/the count are the truth; those may go negative and are valued at zero (shown asnegativeUnits). - Average cost: receipts at cost c →
(onHand·avg + qty·c)/(onHand+qty); if on-hand was ≤ 0 the average restarts at c; outgoing stock leaves at the current average and never changes it; a receipt with no stated cost uses the variant's default cost.
| endpoint | notes |
|---|---|
POST inventory/receipts |
lines {variantId, quantity>0, unitCostKobo?}; one variant once per receipt |
POST inventory/adjustments |
signed quantityDelta; a note is required when removing |
PUT inventory/reorder-levels |
per branch+variant; drives levels?lowOnly=true |
GET inventory/levels · movements · valuation |
paged; valuation = Σ round(onHand×avg) per branch, detail=true for lines |
POST inventory/transfers → /{id}/receive | /cancel |
send removes stock from the source immediately (in transit); receive may record a shortfall (quantityReceived < sent); cancel returns it. The destination's average moves by what arrived, at the cost it left with |
POST inventory/counts → /{id}/lines → /post | /cancel |
snapshot expected qty, record counted, post applies counted − expected as a delta so sales during the count survive; uncounted lines are untouched |
Transfers and counts are state machines guarded by Postgres xmin as an optimistic-concurrency token: of N concurrent
receivers/posters exactly one wins (the status change is saved before any stock moves), the rest get 409.
Not here yet#
Sales and returns (Phase 4) will call the ledger with Reason=Sale/Return, AllowNegative=true. No purchasing/suppliers, no
variant-level units of measure conversions, no serial/lot tracking, no stock.low webhook (Phase 7 outbox).