Synchronizing stock

STP does not have to be the master of stock. A synchronize stock operation sets the quantity for an item to an absolute value, which is what allows an external system — an ERP such as SAP or M3, or a warehouse system — to stay in control while Hii Retail services still have a stock quantity to work with.

This matters because several Hii Retail capabilities need a stock quantity regardless of who owns it: the POS showing availability, click and collect deciding whether an order can be fulfilled, and the nearby-store lookup that tells a customer where else an item is available.

Where the lookup proxy stops

The Query API can proxy a quantity lookup straight to an external system, which raises a fair question: if the ERP can answer "how many of this item", why synchronize at all?

The answer differs by capability, and the difference matters when scoping an integration. Three cases:

1. A proxy cannot serve anything driven by STP's events — this one is structural

🛑 A proxied lookup publishes nothing. It bypasses STP's transaction ledger entirely: no movement is processed, so no stock level update is published. Any Hii Retail feature that builds its own view from those events sees nothing at all for a proxy-only tenant — not stale data, nothing.

Stock Count is the case that matters. It subscribes to STP's stock level updates and keeps its own copy, because to plan a count it needs to know which items are expected to have stock. A store's assortment might be 100 000 items while only 10 000 are actually in stock, and a count should ask the store to count the 10 000, not walk the 100 000. That is a question about the whole set, and it is answered from the event stream — which a proxy does not produce.

No proxy contract fixes this, because the limitation is not about what the external system can answer. If stock count is in scope, the stock must be synchronized into STP.

2. Some questions need STP's movement history, not a quantity

transactions:search and the inventory reports read the transaction ledger — the suspicious-items report compares recent sales against an item's own reference-period average, and reports on durability dates and negative stock. Those are not stock-quantity questions, so a stock-quantity proxy has no equivalent to delegate to.

3. Nearby-store availability is reachable through the proxy — just not via the convenience endpoint

stock-quantities-closest is not proxied, but the capability is not blocked. The proxy forwards the request unchanged — same path, same body — so the external system implements the same contract, including businessUnitIds as a list. A caller can therefore answer "where else is this item available" by calling the proxied POST /stock-quantities for the stores it cares about, either with several business units in one call or one call per store.

What stock-quantities-closest adds, and a caller taking this route has to supply itself:

• which stores are nearby — the endpoint resolves that from Business Unit Management
• the IN_STOCK / LOW_STOCK / OUT_OF_STOCK status, derived from each store's low stock threshold; a proxied lookup returns quantities, and the caller applies its own thresholds

The batch/recall lookup is a different matter: it is keyed by batch and supplier rather than by item, so serving it through a proxy would need the external system to expose that query shape. It is not proxied today, and with a proxy configured it keeps answering from Hii Retail's own stock — meaningful only if that is being synchronized.

In short

	Lookup proxy	Synchronizing STP
"How many of item X?"	✅	✅
Availability across nearby stores	✅ caller resolves the stores and applies its own thresholds	✅ via stock-quantities-closest
Batch / recall lookup	❌ not proxied; needs a batch-keyed query	✅
Transaction search, inventory reports	❌ needs STP's movement history	✅
Stock Count	❌ structural — needs the event stream a proxy never produces	✅
Needs no stock data kept in Hii Retail	✅	❌

If quantity lookups are the only requirement, the proxy alone is a legitimate setup — including nearby-store availability, with the caller doing a little more work. Stock Count is the one that forces the decision, and it is usually in scope: it cannot be served by a proxy at any level of effort, so the stock has to be synchronized into STP as well, using one of the three models below.

Three ways to run it

Model	How it works	When to choose it
STP is master	One synchronization to establish the opening quantity, then STP processes every movement	New implementations, and any tenant without an external stock master
STP is synchronized	The external system owns the stock and pushes the quantity whenever it changes, or on a schedule	The external system is authoritative and already receives all movements
Combination	Synchronized periodically — nightly, for instance — and STP processes sales in between	The external system is authoritative but not real time, and the POS still needs an accurate quantity during the day
Mixed per store	Different models in different business units of the same tenant	Some stores are owned by Hii Retail and others by an external system — see below

The third model is usually the practical one. An ERP that updates stock in a nightly batch cannot tell the POS what is actually available at 15:00; STP processing PosLog sales between synchronizations can.

There is no "who is master" setting. Mastership is not configured anywhere — it emerges from which operations you send. A business unit that receives synchronize-stock operations is being mastered externally; one that does not is mastered by STP. That is what makes the models above patterns of use rather than modes to switch between, and it is why they can differ per business unit.

Mixing models within one tenant

Because synchronize-stocks is addressed per business unit — POST /business-units/{businessUnitId}/synchronize-stocks — a tenant does not have to choose one model for everything. Different business units can run different models at the same time.

A common shape: Hii Retail is master for the physical stores, while the webshop is a business unit whose stock an ERP owns.

	Physical stores	Webshop business unit
Master	Hii Retail (STP)	the ERP
Stock counts and corrections	performed in Hii Retail	performed in the ERP
Sales during the day	processed by STP in real time	processed by STP in real time
Synchronization	opening quantity only	periodic, from the ERP

The webshop's quantity is therefore synchronized from the ERP and then kept current by STP as orders are fulfilled through the day. Because a synchronize-stock operation asserts an absolute quantity, the next synchronization overrides whatever STP had arrived at — which is exactly the intent when the ERP is the authority.

One system owns the absolute quantity — but counting can still happen in Hii Retail

The rule is narrower than it first appears. Movements are deltas and can flow from anywhere; what needs a single owner is the absolute assertion — a stock count or a synchronize-stock operation, both of which state what the quantity is rather than how it changed.

So a store can still use Hii Retail's stock count module for an externally mastered business unit. Counting is a floor-level activity, and the app that supports it does not have to be the system that owns the number. Stock Count publishes stc.public.event.stock-count-completed.v1, which is available through External Events — so an ERP can subscribe, do its own processing, and assert the resulting quantity back to Hii Retail through synchronize-stocks. The count is performed in Hii Retail; the arithmetic remains the ERP's.

Both systems will see that count. STP subscribes to the same event, so it applies the count itself as well, and the ERP's later assertion overrides it. The final quantity is the ERP's, which is the intent — but STP's ledger now holds two adjustments where one physical event occurred: its own count gain or loss, and the ERP-driven correction that partly reverses it.

That does not need reconciling, because of the rule below.

Whoever owns the quantity owns the accounting derived from it

For an externally mastered business unit, the stock accounting belongs to the external system too. Shrinkage, the value of the count loss, cost of goods sold — take those from the ERP, which is the system that decides what the quantity is. STP's role for that business unit is to keep an accurate operational quantity between assertions, so the POS, click and collect, and availability lookups have something current to work with.

Read that way, the two ledger entries are not a discrepancy to explain: they are STP tracking its way to a number the ERP owns.

🛑 Do not feed STP's processed-transaction costs into accounting for an externally mastered business unit. Every movement STP publishes carries a costAmount derived from its own batch and purchase-price model — which is not the ERP's costing, and the ERP's assertions are published with STP's costs attached to them. An accounting system consuming both sources for the same business unit will double count.

Pick one source of financial truth per business unit — the same one that owns the quantity. In the mixed model above that is Hii Retail for the physical stores and the ERP for the webshop.

STP's transaction ledger stays useful for the externally mastered business unit even so — transactions:search still answers why did this quantity change, which is an operational question rather than a financial one.

Import is enabled per tenant and covers every operation, so it is not possible to admit sales while excluding counts, nor to vary it per business unit — see the Do enable PosLog processing setting in Configuration. That shapes the practical pattern for an externally mastered business unit:

Let every movement flow into Hii Retail in real time, and let the external system assert its quantity on its own cadence. Real-time movements keep the POS accurate between assertions; the assertion corrects any drift. Prefer asserting only the items that changed, frequently, over sweeping the whole catalogue nightly — every synchronization is a transaction, and re-asserting an unchanged quantity writes a zero-delta movement per item.

The same reasoning applies to corrections: whichever system owns the absolute quantity should be the one that concludes what a correction makes it.

How synchronization behaves

A synchronize stock operation carries the absolute quantity the external system believes is correct. STP converts that into the delta needed to reach it, and records that delta as a transaction — so the audit trail shows both the correction and its size, and no history is lost.

Because it is an absolute assertion rather than a delta, the same ordering consideration applies as for a stock count: see Delayed transactions.

Practical notes for an integration

• Synchronize the items that changed, not the whole catalogue, once the opening quantity is established. Every synchronization is a transaction, and re-asserting an unchanged quantity produces a zero-delta movement.
• Decide what happens to the Hii Retail feeds during the transition. The Do enable PosLog processing setting is the master switch for every ingress 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, so a synchronized tenant is unaffected by activity elsewhere in Hii Retail. Turning it on while the external system also reports the same movements through synchronization is fine — the synchronization corrects any drift — but turning it on and not synchronizing means the two systems diverge.
• Costs still need a source. Synchronization sets a quantity; it does not by itself supply a purchase price. If gross-profit reporting is expected, make sure the items carry a purchase price in PnP — see Cost calculations.
• Sequence matters at go-live. Establish the opening quantity first, then enable POS processing. The reverse order means sales are applied to a quantity that is about to be overwritten.

Reading the stock back

Whatever the model, the Query API is the single way for the POS and other services to read stock, so they do not need to know which system is master.

---

Return