Where the data comes from
Customer Order sits in the middle of a loop. Orders arrive from three directions, the store reports back what it did, the till reports what the customer paid, and the outside world is told the result.
This page is the map. It exists because the single most common integration mistake is assuming Customer Order is the place you send an order to — it usually is not.
The whole loop
┌──────────────────────────────────┐
Hii Checkout ───▶│ Unified Basket Manager │──┐
(POS) │ basket → checkout │ │
└──────────────────────────────────┘ │
│ PUT …/customer-order:sync
Webshop ────────▶ Unified Basket Manager ──────────────┤ (the same door for all three)
│
OMS / ERP ─────────────────────────────────────────────┘
│
▼
┌──────────────────────────┐
picking progress │ │ the store's share
◀────────────────────────────────────── │ Customer Order │ ──────────────────▶ Click and Collect
(order picked, ready) │ │ to be picked
│ │
what the customer paid │ │ order updated
─────────────────────────────────────▶ │ │ ──────────────────▶ OMS / ERP
(till transactions) │ │
│ │ receipt for a
│ │ ──────────────────▶ warehouse shipment
└──────────────────────────┘
Getting an order in
🛑 There is one entry point, and three ways to reach it.
PUT /business-units/{businessUnitId}/customer-order:sync
on the Customer Order External API. Whichever route an order takes, it arrives through this endpoint.
| Where the order starts | How it reaches Customer Order |
|---|---|
| A colleague at the till (Hii Checkout) | the basket is built in Unified Basket Manager and checked out; UBM calls the endpoint |
| A webshop | likewise through Unified Basket Manager |
| An OMS or ERP | calls the endpoint directly |
So if you are integrating a webshop or a POS, your integration is with Unified Basket Manager, not with this service. You build a basket, you check it out, and a customer order appears. Only a system that already owns complete orders — an OMS or an ERP — talks to Customer Order directly.
The request body is the same shape as what a GET returns, so a system already reading orders from Hii Retail can send them with the mapping it already has.
⚠ An order sent twice is not two orders. The endpoint is a sync: send the same order id again with newer content and the existing order is updated. This is what makes a bulk migration safe — resend everything and nothing duplicates.
What the store tells us back
When an order is to be collected in a store, the picking itself happens in Click and Collect. Customer Order hands over the store's share of the order and then listens.
| Direction | What moves |
|---|---|
| out | the fulfillments a store has to pick |
| in | picking progress — the order has been picked and is ready for the customer |
This is why an order can change state without anyone calling this service: a picker on a shop floor moved it. If you are polling for status, that is what you are waiting for.
What the till tells us back
When the customer arrives, three things happen at the counter, and only the last of them reaches Customer Order.
First the colleague finds the order. They search for it by whatever the customer can produce — an order code, a name. This is a read: nothing is written and no event is published, so an integration watching for activity will see none.
Then the customer pays what is left. Often most of the money arrived when the order was placed, so what is due at the counter is the remainder — sometimes nothing at all. Payment is the till's business, not this service's.
Then the receipt comes back. The sale becomes a transaction, and Customer Order subscribes to the transaction stream. Every receipt in the estate flows past; the ones that do not belong to a customer order are dropped, and the ones that do update their order.
🛑 The receipt is what completes an order — not the picking. Until the transaction arrives, the order has been picked but not handed over. An integration that treats "picked" as "done" is one step ahead of reality on every order, and will report goods as collected that are still sitting on a shelf.
What we publish
Order updates — for an OMS or ERP
The stream to subscribe to if you own orders elsewhere and need to know what stores did with them. It carries the same schema you send on the way in, so the mapping works in both directions.
It carries changes that happened here — an order created at a till or a webshop through the basket, a store picking it, a colleague handing it over. It does not carry your own updates back to you. See what is published, and what is not.
Delivered as a WebHook through the Hii Retail External Events framework. See Outgoing Events.
A receipt for a warehouse shipment
🔑 The one that surprises people, and the reason it exists is worth understanding.
When an order ships from a warehouse, no till was ever involved — so there is no receipt, and without one the customer cannot return the goods in a shop or have their purchase found by a colleague.
So when the OMS or ERP reports the shipment as fulfilled, Customer Order generates the receipt itself. The purchase then exists in the receipt store exactly as if it had been bought over a counter:
- a return or a complaint can be handled in any store, not only the one that shipped it
- the receipt is searchable the same way as a store pickup
Nothing is asked of you to make this happen beyond reporting the shipment. It is worth knowing about because it explains why a warehouse order appears in receipt data at all — and it is one of the things the events approach gives you that proxy mode cannot. See Features enabled by events.
Related
- Incoming Events — the
PUT, ordering guarantees and error handling - Outgoing Events — choosing between order updates and PosLog
- Proxy Mode — the alternative, where Hii Retail stores no orders at all