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

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
in	substitutes — items the picker supplied in place of ones the shelf could not; each becomes a new line on the order

When the store gets its share depends on how the goods leave the store. A collection (PICKUP_IN_STORE) is handed to the store at once, paid or not, because the customer pays when collecting. A home delivery from a store (HOME_DELIVERY_FROM_STORE) is handed over only once it is fully paid, whether the payment arrives in a sync or at a till, so nobody packs a parcel that has not been paid for. A delivery from the warehouse never goes to a store.

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. It is also why an order can gain lines after it was created. See Substitutions add order lines.

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

One receipt is written per shipment, however many times the shipment is reported afterwards. It applies only to HOME_DELIVERY_FROM_WAREHOUSE fulfillments.

What it needs from you. Report the shipment as FULFILLED, in a sync or with :setStatus, on an order that carries:

• the payment: tenders covering the shipment, because a receipt without a payment cannot be written
• an item category and a tax group on every line (itemCategoryId, taxableGroupId)

A shipment reported without them is refused in the response. 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