Customer Order Service
Introduction
This service handles Customer Orders as part of Hii Retail. How you integrate with it depends on where the orders already live, and that is usually decided for you rather than chosen.
Which situation are you in?
You have an existing OMS that owns your orders, and you want to keep it that way. Then the question is only whether Hii Retail should hold a copy. If it should not, use proxy mode: Hii Retail reads from your system on demand and stores nothing. If it should, use events: you push orders in, and Hii Retail keeps a local copy it can serve and search quickly.
You are building a webshop, or selling from a till. 🛑 Then your integration is not with this service at all. Both routes go through the Unified Basket Manager — you build a basket, check it out, and a customer order appears here. See where the data comes from.
Proxy and events are not two equally-weighted product options. Events is the fuller integration and everything below assumes it unless stated; proxy exists for the case where an external system must remain the only home of the data.
| Proxy | Events | |
|---|---|---|
| Direction | Hii Retail reads from your OMS on demand | your OMS pushes orders to Hii Retail |
| Where orders live | only in your OMS | your OMS, plus a copy in Hii Retail |
| Read performance | your system's response time | Hii Retail's |
| Search | forwarded to your OMS, which answers it | full search, answered by Hii Retail |
| Orders created at the till | not possible | supported |
| Conflict handling | yours to implement | handled here |
⚠ Both are configured per tenant, and moving from proxy to events later means sending your existing orders in once — see Incoming Events.
🛑 What integrations most often get wrong
Four mistakes, in the order they tend to bite:
- Assuming an accepted update was applied. Not every update is allowed — an order or fulfillment that is already fulfilled or cancelled is closed to further change. Check the response.
- Treating "picked" as "done". An order is complete when the customer has paid and taken it, not when a picker finished. See where the data comes from.
- Integrating here instead of with the basket. If you are a webshop or a POS, see above.
- Expecting to read the customer's name or phone number back. Personal data lives in the User Profile Service; this service holds an identifier.
Proxy
The service can be configured to work in a proxy mode per each tenant's request. When in this mode, you are able to access only the read endpoints of the service, and the requests are proxied to the configured URL. Learn more about the proxy mode:
Events
The events approach allows external systems to push customer order data into Hii Retail via a PUT endpoint. Orders are stored within Hii Retail, and outgoing events are emitted when order status changes (e.g., picked up in store). Learn more about the events approach:
Additional Features with Events
The events approach unlocks several features that are not available with the proxy approach. These may be relevant if you are evaluating which integration to adopt.
Conflicts
Conflicts can occur when the POS and the external OMS act on the same order simultaneously (e.g., handing out an order while it is being cancelled). This applies to both integration approaches.
Performance
The choice of integration approach has implications for GET endpoint performance and the overall user experience at the POS.