Hii Customer Order

What is the Hii Customer Order service

The Hii Customer Order Service acts as the intermediary between an external Order Management System (OMS) and in-store systems such as Point of Sale (POS) or other applications involved in handling customer orders. Its primary role is to ensure seamless communication and synchronization of order data between these systems.

The service retrieves updated customer orders from the OMS using RESTful APIs. Once an order is processed in-store—for example, when a customer picks up their order—the service publishes an asynchronous webhook event back to the OMS, providing real-time updates on order status. This ensures both systems remain in sync and reflect the most current information throughout the order lifecycle.

Note: The OMS is not required for store-to-store customer orders. This means a customer order can be created in one store and fulfilled by another—such as when an item is sold out in the current store, and the order is placed for pickup at another store that has the item in stock. Such customer orders could be fully handled by HiiRetail only.

Customer Order Distribution and System Ownership

When a customer places an order, it is distributed to multiple backend systems to support different parts of the fulfillment process. These systems typically include:

• Order Management System (OMS) – Central coordination point for customer orders.

• Warehouse Management System (WMS) – Handles inventory and fulfillment for orders shipped from warehouses.

• Enterprise Resource Planning (ERP) – Manages financials, item management, and accounting across the business.

• Hii Customer Order Service – Interfaces with in-store systems like POS for store-based fulfillment.

Fulfillment Routing Logic

The Hii Customer Order Service ensures that customer orders are fulfilled accurately and efficiently by routing each part of the order to the correct operational system based on its fulfillment method. This logic enforces exclusive ownership at the shipment level, meaning that only one system (store or warehouse) is responsible for fulfilling each individual shipment, and access to the same shipment is explicitly locked for all other systems.

Single Fulfillment Scenario

For customer orders containing a single fulfillment method, ownership is determined as follows:

• Warehouse Fulfillment (Ship to Home):

  • The Warehouse Management System (WMS) owns the shipment.
  • The order or shipment is locked for all in-store systems (e.g., POS, Hii Customer Order Service).
  • This prevents stores from accidentally preparing or releasing the items.

• In-Store Pickup:

  • The Hii Customer Order Service and the designated store own the shipment.
  • The shipment is locked for the warehouse, ensuring that it is not packed or shipped from the WMS.
  • Only the specified store can prepare and deliver the items.

Multi-Fulfillment Scenario (Split Fulfillment)

In cases where a customer order contains multiple shipments with different fulfillment types (e.g., a hybrid of "ship to home" and "store pickup"), the system handles each shipment independently:

• Each shipment is assigned to a single fulfillment location and method at creation time.
• Ownership is defined per shipment, not per order.

For example:

• Shipment A is to be shipped from a warehouse to the customer’s home.
• Shipment B is to be picked up from Store 123.

Ownership rules apply as follows:

• Shipment A:
  • Owned by the WMS.
  • Locked for in-store systems — no store can process or deliver this shipment.
• Shipment B:
  • Owned by Store 123 through the Hii Customer Order Service.
  • Locked for both the WMS and all other stores (e.g., Store 456 cannot deliver Shipment B).
  • This ensures the right store with the available inventory handles the order.

Why This Matters

This fulfillment routing logic ensures:

• No duplication or conflict in processing a shipment.
• Fulfillment accountability is clearly assigned to one system per shipment.
• Data consistency and traceability across order lifecycles.
• Operational clarity for staff—ensuring they only act on shipments they are responsible for.

By strictly enforcing shipment-level ownership and system locking, the Hii Customer Order Service prevents fulfillment errors, such as double-shipping, premature delivery, or cross-store mix-ups, thereby enhancing customer satisfaction and system integrity.

Supported in-store operations

1. Buy online, return in store (BORIS)

   • Allows customers to return or request refunds for items in physical stores, even if the items were ordered online and shipped from the warehouse.
   • This is possible because shipment data from the warehouse is imported into the Hii Customer Order service, allowing store staff to retrieve a copy of the purchase.

2. Create Customer Order

   • The system gets a customer order from the OMS or Basket Manager, for instance, created by the customer using the webshop.
   • or by creating a customer order using the POS, for instance, if the item is sold out in the store, and the customer wants to get the item shipped to their home address or pick it up from another nearby store.

3. In-store Order Notification

   • Display notifications for in-store users when a new customer order is placed and needs to be prepared or packed.
   • Ensures that ordered items are reserved and not sold before the customer picks them up.

4. Pack Order in Store

   • Allows store personnel to mark a customer order as packed and ready for pickup.
   • The system sends an event to the OMS indicating the customer order is ready for pickup. The OMS can notify the customer by sending an SMS or email.

5. Search Customer Orders

   • Enables store staff to search for customer orders associated with their store for processing or customer service.

6. Deliver Order (Full or Partial)

   • Supports delivering the entire customer order or specific items within it to the customer upon pickup.
   • The system sends an event to the OMS indicating the full or partial order has been picked up by the customer.

System Robustness and Operational Guarantees

The Hii Customer Order Service is designed with multiple layers of robustness to ensure reliable, consistent, and fault-tolerant handling of customer orders across distributed systems.

1. Guaranteed Message Delivery (At-Least-Once Semantics)
   All asynchronous messages exchanged between systems follow at-least-once delivery guarantees:

   • Messages are stored and retried until acknowledged by the target system.
   • Retry logic ensures transient issues (e.g., network failures, downstream unavailability) do not result in lost events.
   • This approach ensures every customer order message is eventually processed, even under temporary failure conditions.

2. Message Ordering and Replay Integrity
   To maintain the consistency and correctness of order states, the service ensures proper message ordering, especially during replays:

   • Each event includes metadata (e.g., timestamps, version counters) that allow the system to determine the correct processing sequence.
   • In case of replay, older events are validated against the current system state to prevent regressions (e.g., avoiding a “packed” state being overwritten by a replayed “created” event).
   • Replay operations apply only if the event is newer or relevant to the current order status.

3. Real-Time Alerting on Critical Queues (DLQ Monitoring)
   Failures in asynchronous message handling are isolated using Dead Letter Queues (DLQ):

   • Any message that fails after multiple retries is moved to the DLQ.
   • The DLQ is continuously monitored, and real-time alerts are triggered if entries appear in the queue.
   • Alerts include details about the failed message, its origin, and error cause, enabling rapid investigation and resolution.

4. Time-Based Monitoring and Alerting
   To prevent undetected delays or silent failures, the system includes timeout tracking and aging alerts:

   • Each message or operation has a defined acceptable processing time.
   • If a message is not processed within its allowed timeframe, the system flags it for review and generates an alert.
   • This allows early detection of stuck workflows, misrouted events, or slowdowns in external systems.

5. Auto-Healing and Manual Recovery Support
   In addition to automated retries and replays, the system supports manual replay of events from the DLQ or archived logs:

   • Events can be replayed without duplication, thanks to idempotent processing logic.
   • This ensures that once the root cause of a failure is fixed, affected orders can be recovered without customer impact.

Operational Error Handling and Alerting

The Hii Customer Order Service includes a comprehensive operational error-handling framework designed to minimize disruption and ensure a smooth order lifecycle. Building on its resilient architecture and guarantees (e.g., message durability, replay capability, and real-time alerts), this section illustrates how the system behaves under real-world conditions and how issues are managed when they arise.

Error Classification and Routing

• Errors are classified as transient (e.g., network issues, timeout) or persistent (e.g., invalid data format, unresolvable downstream failures).
• Transient errors are automatically retried based on preconfigured policies. Persistent errors are rerouted to the Dead Letter Queue (DLQ), where they trigger alerts for manual investigation.
• Errors are logged with full context, including correlation IDs and system status at the time of failure, to aid in troubleshooting and resolution.

Figure: Error handling for processing of asynchronous messages

Error Handling and Alerting in Real World Examples

Let's look at how error handling and alerting work in the specific scenario of a customer placing an online order for home delivery from a warehouse.

The Normal Flow:

1. Customer check out their online basket.
2. An order is created in the Order Management System (OMS).
3. The order details are sent from the OMS to the HiiRetail Customer Order Service and Warehouse Management System (WMS) for picking and packing.
4. Warehouse staff start picking the items. This update is sent from OMS/WMS to HiiRetail Customer Order Service where the status for each item is updated reflecting this update.
5. Warehouse staff finish picking and ship the items. Another update is sent from OMS/WMS to HiiRetail Customer Order Service with this information.
6. The order is now considered fulfilled and the HiiRetail Customer Order Service finalizes the transaction and subsequently generates a POSLog (a financial record for the transaction used by ERP and HiiRetail for potential returns).

What Happens When Things Go Wrong?

Here are a few scenarios and how error handling and alerting would come into play:

Scenario 1: The Order Can't Reach the HiiRetail Customer Order Service

• The Error: After the order is created in OMS, there's a temporary network problem, and the message containing the order details cannot be sent to the HiiRetail Customer Order Service.
• Error Handling: OMS is likely set up to retry sending the order message several times over a short period. It might also store the message temporarily so it can try again later when the network is stable. It will most likely also log the fact that there was a sending error.
• Alerting: If, after multiple retries, the OMS still cannot send the order to HiiRetail Customer Order Service, this is a bigger problem. The system should then preferably trigger an alert (e.g., send an email or show a critical warning on a monitoring dashboard) to the technical team.
• Why this works: The retries handle brief glitches without needing human help. The alert ensures that if the problem is persistent (like a system being down), someone is notified to fix it before customers' orders are lost.

Scenario 2: The POSLog Generation Fails

• The Error: After receiving the "picking complete" update, HiiRetail Customer Order Service tries to finalize the transaction and create the POSLog file needed for in-store returns. However, there's an issue, perhaps with the data format or the system that stores the POSLogs, and the generation fails.
• Error Handling: HiiRetail Customer Order Service would log the specific error details (what went wrong during generation). It might also mark the order internally as "Finalization Failed" so it can be easily identified. It might retry the generation process a few times if the error seems temporary.
• Alerting: Since the POSLog is crucial for customer returns and potential payment captures, a failure to generate it is important. If the retry attempts fail, or if multiple orders fail POSLog generation, an alert would be sent to the technical team. This alert would ideally include details about the specific order(s) affected and the type of error encountered.
• Why this works: Logging provides the details needed for troubleshooting. Marking the order helps track affected customers. Alerting ensures that the technical team knows that customers might not be able to return these specific orders in-store until the issue is resolved and the POSLogs are manually generated or the system is fixed.

These operational examples highlight how the Hii Customer Order Service applies its robustness guarantees in live scenarios, combining automatic recovery with proactive alerting to maintain business continuity and customer satisfaction.