Skip to main content

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.

Which integration fits depends on where your orders already live. A webshop or a till integrates with Unified Basket Manager: it checks out a basket, and the order appears in Customer Order. A system that already owns complete orders, such as an OMS or ERP, uses events if Hii Retail may keep a copy, which is the fuller integration, and proxy mode only if the orders must stay in that system alone.

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.

ProxyEvents
DirectionHii Retail reads from your OMS on demandyour OMS pushes orders to Hii Retail
Where orders liveonly in your OMSyour OMS, plus a copy in Hii Retail
Read performanceyour system's response timeHii Retail's
Searchforwarded to your OMS, which answers itfull search, answered by Hii Retail
Orders created at the tillnot possiblesupported
Conflict handlingyours to implementhandled 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:

  1. 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.
  2. 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.
  3. Integrating here instead of with the basket. If you are a webshop or a POS, see above.
  4. 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​

A tenant can have the service work in proxy mode, set up in the logistics proxy configuration. 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.