Skip to main content

Data sources

STP needs two different kinds of input, and they behave differently:

  • Movements — things that change the quantity. Sales, deliveries, counts, corrections, transfers.
  • Item master data — things that change how a movement is interpreted. Whether the item is stock handled at all, which costing method applies, what it costs to buy, and whether it is a bundle of other items.

Most of both arrives automatically from other Hii Retail services. The Input API exists for movements that originate somewhere else.

One switch governs all of it. Every ingress on this page except the Input API is gated by the tenant setting Do enable PosLog processing. Despite the name it controls every feed from a Hii Retail service — sales, goods received, stock counts, corrections, store transfers, and item master data from PnP. With it disabled the Input API is the only way in, which is what you want while an external system still owns the stock. See Configuration.

Movements from other Hii Retail services​

STP subscribes to the public events of the services that own each business process. Nothing needs to be configured per integration — if the source service is in use, its movements reach STP.

SourceEventBecomes
POS, via the transaction servicetxr.public.output.transactions.v1sales and returns
Goods Receivedgrc.public.event.goods-received.v1receipt of a delivery
Stock Countstc.public.event.stock-count-completed.v1a counted quantity, and the resulting gain/loss
Stock Correctionsscr.public.event.stock-correction.v1a correction (damage, waste, etc.)
Store Transferstr.public.event.store-transfer-requested.v1stock reserved for an outgoing transfer
Store Transferstr.public.event.store-transfer-completed.v1the transfer leaving the sending store

Sales — subscribing to PosLog​

Sales reach STP as PosLog transactions published by the transaction service. STP reads the item lines and converts each one into a stock movement.

Two things are worth knowing if you are reconciling POS data against stock:

  • Only item lines that move stock are processed. Sale, SaleForDelivery and Return lines become transactions. Lines with a status of Canceled are skipped, and line types that do not represent an item movement — deposits, tenders, discounts — are ignored.
  • A return does not go back into sales stock. A Sale reduces SalesStock; a Return increases Returned, which is a separate stock type. Returned goods have to be inspected and put back deliberately. See The stock model.

Note: all lines of one receipt share the receipt's transaction time (endDateTime) — the moment the receipt was closed — rather than the time each individual line was scanned. That is the official time of the sale.

Item master data from PnP​

Item master data comes from Product, Price and Promotion (PnP), which is the master for items across Hii Retail. STP keeps a local copy so that processing a sale does not depend on a live lookup.

WhatWhere it comes from in PnPUsed for
Whether and how the item is stock handledthe Stp.StockHandlingType, Stp.StockHandlingMethod and Stp.UseAverageWeightedCostPrice additional properties on the itemdeciding whether to calculate stock, which batch to draw down, and how to cost the movement
Purchase pricethe item's PURCHASE price specificationcosting a movement when nothing else supplies a cost
Item linksthe item's STRUCTURE item linksexpanding bundles into their components

If an item is not yet known locally, STP looks it up in PnP on demand and caches the result. If PnP has no such item either, behaviour depends on the Use default values if item is unknown setting: with it enabled the movement is still processed using defaults, so the quantity stays correct; with it disabled the movement is not stock handled.

Note: only items of type STOCK can be stock handled, and an item's purchase price is what makes cost calculation possible. An item with no purchase price and no other cost source produces movements with a cost of 0 — see Cost calculations.

Master data is always business-unit scoped​

Stock is calculated per business unit, so item master data has to be too. PnP resolves that for you. An item or a price defined globally, or on a business unit group, is published with the full list of business units it applies to — including every store that inherits it. STP stores one entry per business unit, so a store always has its own effective item configuration and its own purchase price, however that configuration was defined upstream.

There is therefore no separate "global" item state to reason about, and no inheritance for a consumer to resolve.

Because additional properties are dynamic, an external system can set any of the Stp.* properties on an item without a change to the PnP schema — which is what makes stock configuration possible for tenants whose item data is maintained outside Hii Retail.

Prices are always the currently valid one​

A PURCHASE price specification in PnP carries a validity period, and a price can be created in advance to take effect on a future date. STP only ever holds the price that is in effect now: PnP marks the currently valid price as current, and publishes a fresh message when a future price becomes active. So a price change scheduled for next month arrives twice — once when it is created, which STP ignores, and again when it takes effect, which is when STP adopts it.

That means the purchase price STP applies to a movement is the price valid at the time the movement is processed.

Input API​

The Input API accepts movements that do not already arrive from another Hii Retail service — typically from an external ERP, a warehouse system, or a customer integration.

EndpointOperation
POST /business-units/{businessUnitId}/synchronize-stocksSet an absolute quantity
POST /business-units/{businessUnitId}/stock-countsCounted quantity, with gain/loss calculated
POST /business-units/{businessUnitId}/stock-correctionsDamage, waste, or other adjustment
POST /business-units/{businessUnitId}/goods-receivedReceipt of a delivery
POST /business-units/{businessUnitId}/purchase-ordersOrder placed with a supplier
POST /business-units/{businessUnitId}/order-responsesSupplier's confirmation of what will be delivered
POST /business-units/{businessUnitId}/supplier-returnsGoods returned to the supplier
POST /business-units/{businessUnitId}/receiptsSales and returns
POST /business-units/{businessUnitId}/reservationsStock set aside for a customer
POST /business-units/{businessUnitId}/depreciationsAdjust the cost of remaining stock
POST /business-units/{businessUnitId}/stock-transactionsGeneric transaction
POST /stock-transfersTransfer from one business unit to another
POST /transfers-receivedReceipt of a transfer at the destination

See Operations for what each one means to the stock.

The Input API is for movements only. Item master data — stock-handling settings, purchase prices, item links — is maintained in PnP, which is the master for items across Hii Retail and reaches every consuming service rather than only stock. See Item master data from PnP above.

Return