How it works

A correction passes through Stock Corrections in one hop. The service checks the reason, stamps the correction, and publishes it. Everything that happens as a result happens somewhere else.

  Inventory app ─┐
                 ├──►  Stock Corrections API  ──►  scr.public.event.stock-correction.v1
  Your system  ──┘              │                              │
     (REST)                     │                              ├──►  Stock Transaction Processing
                                │                              │        (applies it to the balance)
                                ▼                              │
             Customer Controlled Configuration (CCC)           ├──►  External Events
                     (is this reason code                      │        (your system, outside the platform)
                      valid for corrections?)                  │
                                                               └──►  audit store

Step by step:

1. A correction arrives — from the app or from your own system — naming a business unit, an item, a signed quantity and a reason code.
2. The reason code is checked against the business unit's configuration. A code that cannot be used — unknown, not configured for stock corrections, or deactivated — is rejected with an error, and nothing is published. See Reason codes.
3. The correction is stamped with a stockCorrectionId, the identity of the user whose token made the call, and a time — the caller's, if it sent one, otherwise the moment the call arrived. A retried request that repeats its Correlation-Id and time gets the same id, so everything downstream recognises it as the same correction. See Retrying safely.
4. One event is published per correction, to a public topic. There is no batching: one call, one event.

Who applies the correction to stock

This is the question that decides what you build, and the answer depends on which system is the stock master for that business unit.

If the stock master is…	Then…
Hii Retail — Stock Transaction Processing keeps the balance	STP consumes the event and moves the quantity. Nothing further is needed from you.
Your own system — an ERP or warehouse system owns the number	Your system consumes the event, through External Events, and applies the correction itself.

Both can be true within one tenant, for different business units. A chain commonly runs its physical stores on Hii Retail stock and its webshop business unit on an ERP; corrections raised in a store flow to STP, corrections raised against the webshop unit flow out to the ERP. The event is the same in both cases — Stock Corrections does not know or care who is listening.

🛑 Stock Corrections publishes regardless. It does not check that anything applied the correction, and it does not stop publishing when an external system is master. If you have both STP and your own system consuming corrections for the same business unit, both will apply them and the stock figure will be adjusted twice. One consumer per business unit.

When Stock Transaction Processing is master

STP treats a correction as an ordinary stock movement against sellable stock, or against returned stock when the correction names it. See Events for the exact mapping.

⚠ STP has a master switch that also gates corrections. The tenant-level setting Do enable PosLog processing gates every ingress from Hii Retail services into STP — sales, goods received, stock counts, store transfers and corrections alike. With it off, Stock Corrections still accepts the call and still publishes the event, but STP ignores it and the balance does not move. If corrections appear to vanish for a tenant, check that setting before looking anywhere else.

What it deliberately does not do

Knowing the boundary saves more integration time than anything else on this page.

Not provided	What to do instead
No stored history, no query endpoint	Subscribe to the event and keep your own record. The event carries every field the API received.
No reversal or cancellation	Send an opposite correction. A correction of -5 booked in error is undone by a correction of +5, with its own reason code. Both stay in the record, which is what an auditor wants.
No approval workflow	A correction takes effect the moment it is accepted. If your business needs a second pair of eyes, that gate belongs in the system that calls this API.
No value or cost	Corrections carry quantity only. When STP is master it derives the value from the item's cost — see cost calculations.
No stock balance to read	Read the quantity from whichever system is master — the STP query API when that is Hii Retail.
No bulk endpoint	Send one call per item. Each becomes its own correction with its own id and reason.

Corrections and stock counts

Both change the number on purpose, and choosing the wrong one loses information.

• A stock count asserts a level: there are 12 on the shelf. It replaces the quantity, and any difference is absorbed without a stated cause.
• A correction states a delta and a cause: 3 were broken. The quantity moves by exactly that much, and the reason survives into reporting.

Use a count after recounting a shelf, and a correction whenever you know what happened to the stock. If your staff routinely count to fix a number they could have explained, the reason-code data is where you will notice — the shrinkage will show up as unexplained count variance instead.