Skip to main content

Incoming Events

The events approach allows external Order Management Systems (OMS) to push customer order data into Hii Retail. Instead of Hii Retail fetching data from the external system on demand (as in Proxy Mode), the external system sends order data to Hii Retail using a PUT endpoint.

Sending Customer Orders​

To submit or update a customer order, use the PUT endpoint documented in the API reference:

The request body schema is identical to the response schema used by the GET endpoint in the proxy approach, making it straightforward to adopt events if you are already familiar with the proxy integration.

Migration from Proxy​

When migrating from the proxy approach to events, the external system must send all existing customer orders to Hii Retail using the PUT endpoint. This ensures that Hii Retail has the complete and up-to-date order data for processing and synchronization with the POS.

Ideally, the migration can reuse the same synchronization logic used for ongoing event updates -- i.e., send all customer orders that have been updated and not yet synced.

Event Processing​

Incoming orders are emitted to PubSub for processing. This provides:

  • Automatic retries -- if processing fails, the message is automatically retried up to a configured number of times.
  • Eventual consistency -- the system guarantees that orders will be processed, even if temporary failures occur.

Ordering Guarantees​

The PubSub subscription is ordered, meaning events are processed in the sequence they were received. This ensures that order updates are applied in the correct chronological order.

Error Handling​

If the processing of an incoming event fails:

  1. The service retries the request automatically up to a configured number of times.
  2. If retries are exhausted, the message is moved to a Dead Letter Queue (DLQ) for further investigation and manual intervention if necessary.

When a DLQ message is retried manually:

  • If a newer message for the same customer order has already been processed, the retried DLQ message is ignored to prevent overwriting with outdated information.