Goods Received

Introduction

Goods Received records what a store was told it would get, what actually arrived, and the difference between the two. A delivery note enters the service — usually pushed from a supplier's or warehouse's system — the store verifies the goods against it, and on approval the service publishes the approved quantities so that stock, accounting and dispatch systems can act on them.

The service does not decide stock levels itself. It is the point where a physical arrival becomes a trusted number, and it hands that number to Stock services and to any external subscriber.

  Supplier / warehouse / ERP                Hii Retail                       Consumers
  ─────────────────────────────             ──────────────────────           ─────────────────────────
  GS1 despatch advice (XML) ──────┐
                                  │         ┌────────────────┐
  Created in the store ───────────┼──────►  │ expected qty   │──────────────►  Stock services
  (paper note, or none)           │         │ approved qty   │               (stock levels, cost)
                                  │         │ adjustments    │
  Completed store transfer ───────┘         │ + reason codes │──────────────►  External Events
  (from another store)                      └────────────────┘               (your own systems)
                                                   ▲
                                                   │
                                     item master data (PnP),
                                     store identity (Business Unit
                                     Management), reason codes (CCC)

Everything Goods Received publishes describes one delivery at one store. It never aggregates across stores and never states a stock level — it states how much of an item was accepted on a given delivery.

What a delivery note is

A delivery note tracks a shipment of item lines, optionally organised in containers, from a shipper to a receiving store.

Concept	What it is
Delivery	One shipment to one store, identified by the shipper's delivery note number
Line	One item on that delivery, with an expected quantity and a price
Container	A physical logistic unit (pallet, cage, box) holding lines. Containers can nest
Shipper	Who sent it — another store, or an external supplier or warehouse
Adjustment	A difference between expected and approved quantity, with a reason code

A delivery can be approved whole, line by line, or container by container, and can be corrected after approval. Each approval publishes an event.

If you want to…

…then read
Send deliveries into Hii Retail from an ERP, OMS or WMS	GS1 import, then the GS1 field reference
Know where deliveries come from and what else the service depends on	Data sources
Understand the states a delivery moves through, and what "approved" means	Delivery lifecycle
Get the arithmetic right — expected, approved, adjusted, delta	Quantities and adjustments
Prepare a tenant so receiving works at all	Configuration
Build a UI or a back-office integration against the API	API
Subscribe to what Goods Received publishes	External Events

Two very different audiences

The API serves two kinds of caller, and mixing them up is the most common source of confusion:

Caller	Uses	Character
External systems — ERP, OMS, WMS, supplier portals	The GS1 import endpoint	Machine-to-machine, file-based, one call per delivery note
Hii Retail front ends — the store app and back office	The delivery, line, adjustment and submit endpoints	Interactive, one call per user action

An external system that wants to feed deliveries in should use GS1 import and nothing else. The business-unit-addressed endpoints exist to support a user interface: they are individually small, they assume a signed-in user, and their shape follows the screens rather than a document.

🛑 Every write in this service is asynchronous. Creating, updating, adjusting and submitting all return 202 Accepted — the request has been taken, not applied. The change becomes visible on the read endpoints a moment later, and a processingStatus field tells you where it is. See Delivery lifecycle before you build anything that writes and then immediately reads.