Stock Query API
Introduction
The Stock Query API is to be used by the POS (or other services) for fetching the stock quantity. The POS can use this API independent of the source being used.
The Stock Query API can serve stock from two different sources, and the caller does not need to know which:
- Hii Retail Stock service — the default. It can be master of the stock, be synchronized by an external master, or a combination of the two — see Synchronizing stock.
- An external system — the request is proxied to a customer's own system, such as an ERP. Configured per tenant; see below.
Reading stock quantities
| Endpoint | Purpose |
|---|---|
POST /stock-query/stock-quantities | Quantities for one or more items across one or more business units. The general-purpose lookup. |
GET /stock-query/business-units/{businessUnitId}/items:current-stock | Current stock for several items in one business unit. |
POST /stock-query/business-units/{businessUnitId}/stock-quantities-closest | Quantities in nearby business units — see below. |
POST /stock-query/items/batchNumber/{batchNumber}/businessPartnerId/{businessPartnerId} | Quantities for a specific batch from a specific supplier, across business units. |
Quantities are returned per stock type. SalesStock is the one that means
"available to sell".
Nearby business units
stock-quantities-closest answers the question a customer asks when an item is out of stock: where else can I get
it? Nearby business units are resolved from Business Unit Management (BUM), then quantities are fetched for those
business units.
Each result carries a stock status rather than only a number:
| Status | Meaning |
|---|---|
IN_STOCK | quantity is above the store's low stock threshold |
LOW_STOCK | quantity is positive but at or below the threshold |
OUT_OF_STOCK | nothing available |
Both the threshold and how many stores are considered are configured per business unit — see
Configuration. The threshold defaults to 0, which means every positive
quantity reports as IN_STOCK; the number of nearby stores defaults to 5.
Batch lookup
items/batchNumber/{batchNumber}/businessPartnerId/{businessPartnerId} finds where a specific batch is, and how
much of it remains. Its typical use is a recall — a supplier reports a problem with one batch and the business
needs to know which stores still hold it and how much.
Investigating stock history
| Endpoint | Purpose |
|---|---|
POST /stock-query/business-units/{businessUnitId}/transactions:search | Search the transaction ledger for a business unit |
GET /stock-query/document-types | List the document types available for the tenant, for use as a search filter |
transactions:search is the answer to "why is the quantity what it is?" Because stock is calculated from an
immutable ledger rather than stored as a number, every movement that contributed to the current quantity can be
retrieved — with its business date, its source document, its cost, and the resulting stock level. This is the first
place to look when a store disputes a quantity.
Inventory reports
| Endpoint | Purpose |
|---|---|
GET /inventory-reports/business-units/{businessUnitId}/suspicious-items | Items that need attention in one business unit |
The suspicious items report flags items whose stock looks wrong, without anyone having to go looking. Each flagged item carries one or more suspicion types:
| Suspicion | Meaning |
|---|---|
NEGATIVE_STOCK | the quantity has gone below zero — more was sold than the system believed existed |
DURABILITY | stock on hand carries a best-before or expiration date that is close or already passed |
SLOWED_SALES | sales over the last 3 days have dropped against the item's own reference-period average |
The report also returns the figures behind each flag — expectedDaysToSellOut, expectedExpiresIn,
averageSalesLast3Days, averageSalesReferencePeriod and a slowedSalesFactor — so a store can act on the reason
rather than only the flag. A slowedSalesFactor of 0.5, for example, means sales in the last three days are running
at half the reference average.
Serving stock from an external system
A tenant can have its stock quantities served from its own system instead of Hii Retail's — an ERP such as SAP or M3, or a warehouse system. The POS and every other caller keep using the same endpoint and the same contract; only the source behind it changes.
This is configured per tenant, so POS in tenant A can read from the Hii Retail Stock service while POS in tenant B reads from an external ERP:
What is proxied, and what is not
🛑 Only
POST /stock-query/stock-quantitiesis proxied. Every other endpoint on this page always serves Hii Retail's own data.
That distinction matters when planning an integration. With a proxy configured, a plain quantity lookup reaches your
system — but the nearby-store lookup, the batch lookup, transactions:search and the suspicious-items report continue
to answer from Hii Retail's stock. Those questions are set-based: they need the whole stock picture, not one item's
quantity, and a per-item proxy cannot supply it. If Hii Retail is not being synchronized, treat those endpoints as
unanswered rather than as a second opinion.
A harder limit applies beyond this API: Stock Count builds its own view from STP's published events, and a proxied lookup publishes nothing — so it sees nothing at all for a proxy-only tenant. See where the lookup proxy stops for which capabilities are affected and why.
Configuring it
Set the configuration through the logistics proxy configuration service:
| Endpoint | Purpose |
|---|---|
GET /api/v1/proxy-config | Read the proxy configuration for your tenant |
PUT /api/v1/proxy-config | Set or update it |
The configuration carries the base URL of your system, and credentials in one of two forms:
| Authentication | Fields |
|---|---|
| Basic | username, password |
| OAuth | client id, client secret, authorization URL |
Credentials are held in Google Secret Manager, never in the stock service's own configuration.
It fails open to Hii Retail
If no proxy configuration exists for a tenant, or the stored configuration cannot be read, the request is served from the Hii Retail Stock service instead and the fallback is logged. So a broken proxy configuration degrades to Hii Retail's own quantity rather than failing the call.
⚠ Whether that is the behaviour you want depends on your setup. If Hii Retail is being synchronized by your system the fallback is a slightly stale figure — usually preferable to an error at the till. If it is not synchronized, the fallback is a quantity with no relationship to your stock. Decide which case you are in before relying on it.
⚠ A proxied lookup is only as fresh as the system behind it. ERP systems often do not update stock in real time, so a proxy can return a quantity that is hours old. Where near-real-time accuracy at the till matters, the combination in Synchronizing stock — external master, with Hii Retail processing POS sales between synchronizations — usually serves the POS better than proxying.