Configuration
Goods Received has little configuration of its own. What it does have is a small set of prerequisites that live in other services, and every one of them produces a confusing symptom when it is missing. This page is what to set up, and what a given symptom points at.
Scope: what is set where
| Thing | Scope | Consequence |
|---|---|---|
| Reason codes | Resolved per business unit, set at tenant, group or store level | Set them once for the tenant and every store inherits them; set them on a group or a store where it should differ. A store that resolves to no codes cannot record any difference |
| Store identity (GLN) | Per business unit | Only affects GS1 imports that identify parties by GLN |
| Permissions | Per user or service account | Reading, creating, approving and importing are separately grantable |
| The delivery-date limit | Fixed | Not configurable — see Rules that are not configurable |
There is no tenant-wide switch that turns any of this on or off, and no setting that changes how quantities are calculated. Goods Received behaves the same way for every tenant; what varies is the reference data it has to work with.
Reason codes
Every difference between the expected and the approved quantity has to be explained by a reason code, so reason codes are what make receiving usable at all.
They are maintained in Customer Controlled Configuration as configuration kind rco.reason-codes.v1, and Goods
Received picks up changes as they are made — there is nothing to re-import.
Two conditions have to hold for a code to be usable in receiving:
- It must include the
GoodsReceivedgroup. Reason codes are shared with other processes; a code without this group is ignored here, however it is spelled. - It must be active (
Activated).
Reason codes are resolved per store, through the configuration hierarchy. Set them where it fits: for the whole tenant, for a group of business units, or for one store. Each store receives with the codes it resolves to: its own, or the ones it inherits from the nearest level above it. Setting the codes once at tenant level is the usual way to give a whole estate the same set.
A code that is deactivated stops being usable for new adjustments. Adjustments already recorded against it keep it, so history stays explainable; published events continue to carry the code id.
⚠ The set of codes is the customer's, not Hii Retail's. There is no built-in default list. A tenant that has not configured any reason codes has a working receiving flow only for deliveries that arrive exactly as expected — the moment staff need to record a shortage, they cannot save it. Set reason codes up as part of onboarding, before the first store goes live.
Choosing codes
Codes are free-form ids with a display name, so they can match the customer's existing loss and discrepancy categories. One option on a code changes how receiving offers it:
| Option | Effect in receiving |
|---|---|
| Negative quantity by default | Marks the code as a shortage reason. Set to false, it is a surplus reason. Left unset, it can be used for either |
The other options a reason code can carry in the configuration service (comment required, reference number required, manual entry required, minimum and maximum amount) belong to the shared reason-code configuration and are not applied when goods are received.
🛑 Configure codes for both directions. The sign option decides which situations a code is offered for, so a store whose codes are all marked negative cannot record an over-delivery at all — staff will find no selectable reason and be unable to confirm the line. Every estate receives more than it expected sometimes; make sure at least one surplus reason exists.
Two further practical points:
- A code can be used only once per line. Splitting a difference across causes needs two different codes. If staff routinely need to record the same cause twice on one line, that is a sign the code is too coarse.
- Codes end up in downstream reporting. They are published on every event, so whoever consumes Goods Received events will report on these ids. Agree them with the people who will read the reports, not only with store operations.
Store identity for GS1 imports
Only relevant if the sending system identifies parties by GLN.
Register each store's GLN against its business unit in Business Unit Management. An unregistered GLN fails the import. Sending the Hii Retail business unit id in the document instead removes the dependency entirely — see Identifying the store.
Permissions
| Permission | Allows |
|---|---|
grc.delivery.read | Listing and reading deliveries and their lines |
grc.delivery.create | Creating deliveries and adding lines, including ad-hoc deliveries |
grc.delivery.update | Changing a delivery's header — date, comment, transport and customs amounts |
grc.delivery.approve | Setting adjustments and approving |
grc.delivery.import | Importing a GS1 despatch advice |
Approving is separate from creating on purpose: recording what a delivery should contain and confirming what actually arrived are different responsibilities, and many customers split them between roles.
A service account for an external system needs grc.delivery.import and nothing else. Granting it approval rights
would let the sending system approve its own deliveries, which defeats the point of receiving.
Rules that are not configurable
| Rule | Applies to |
|---|---|
| A delivery date more than 14 days in the past is rejected | Deliveries created in the store, header-first |
| Approved quantity must equal expected plus the adjustment | Everywhere |
| A non-zero adjustment must be explained by reason codes summing to it | Everywhere |
| A reason code must be configured for that store | Everywhere |
The 14-day limit is a deliberate guard on hand-entered dates, where a mistyped year is easy and expensive. It does not apply to the one-call ad-hoc endpoint or to GS1 imports, whose dates come from a system rather than a keyboard.
Symptom → what to check
| Symptom | Check |
|---|---|
| Staff cannot save a shortage or surplus | The reason codes that store resolves to — active, and with the GoodsReceived group |
| A reason code exists in configuration but not in the app | It is missing the GoodsReceived group, or it is not active |
| Shortages can be recorded but surpluses cannot (or the reverse) | Every configured code is marked for the other direction. See Reason codes |
| A code cannot be selected a second time on the same line | Expected — one code per line. Use a second code |
| GS1 import fails with "business unit not found" | The GLN is not registered in Business Unit Management |
| GS1 import fails with "invalid GS1" | The document does not satisfy the profile |
GS1 import returns 202 but no delivery appears | An item could not be resolved, or the document was missing a field caught late. Confirming an import landed |
| A delivery is stuck showing as saving | Its processingStatus. Asynchronous writes |
| A delivery created in the store is rejected on the date | The delivery date is more than 14 days old |
| Adjustment rejected as an invalid quantity | Approved must equal expected plus adjusted, and reason codes must sum to adjusted |
| Consumers see the wrong quantity after a correction | The consumer is mixing delta and level. Delta versus level |