Proxy Mode

A tenant whose orders live only in its own order system (OMS) can have the Customer Order service read them from there, instead of holding a copy. The service then acts as a middleman between the till and the external service, while the data is still reached through the Hii Retail APIs and front ends.

Configuration

Proxy mode is set up in the logistics proxy configuration service, under the service key customer-order: the address of your system and the credentials to call it, with HTTP Basic or OAuth 2.0 client credentials.

PUT https://logistics-proxy-config.retailsvc.com/api/v1/proxy-config?service=customer-order

{
  "type": "basic",
  "config": { "username": "hii-retail", "password": "s3cret" },
  "apiConfig": { "url": "https://oms.example.com" }
}

Proxy mode is on for a tenant once a configuration with an address is stored, and off again when the address is removed, within the 10 minutes a change takes to reach every instance. apiConfig.url is the base address that the endpoints in External Service Configuration are appended to, so https://oms.example.com receives GET https://oms.example.com/business-units/{businessUnitId}/customer-orders/{customerOrderId}.

See Proxy configuration for both authentication forms, what authUrl may be, how secrets are masked when read back, and when a change takes effect. It is the same configuration the other logistics services read, so a tenant that also proxies stock sets it up the same way.

Outgoing Events (PosLog)

When using the proxy approach, the external OMS must subscribe to PosLogs to receive updates about customer orders from the store -- for example, when an order is picked up by the customer.

PosLogs are delivered via WebHook through the Hii Retail ExternalEvents framework. Note that PosLogs are emitted for a variety of POS activities, including login, regular sales, and refunds, not only customer order events. The external system must filter the PosLog stream to identify the entries relevant to customer orders and take appropriate action based on those events.

note

When using the Events approach, dedicated customer order events are available via WebHook in addition to PosLogs, removing the need for filtering.

What proxy mode allows

While in proxy mode, the Customer Order service serves reads only. Anything that changes an order must go to the external service directly — Hii Retail is not the owner of the data and will not accept a write it cannot honour. Responses coming back from the external service are mapped to the Hii Retail API shape, so a caller sees the same contract either way.

The read endpoints that work in proxy mode:

Endpoint	What it answers
GET /api/v2/business-units/{businessUnitId}/customer-orders/{customerOrderId}	one order
GET /api/v2/business-units/{businessUnitId}/customer-orders:search	find orders

Everything else returns 405 Method Not Allowed while proxy mode is on.

When your system cannot answer

🛑 Proxy mode fails closed. Hii Retail holds no copy of the orders, so there is nothing to fall back to: if your system cannot answer, the caller gets an error.

Your system answers	The caller gets
2xx with a valid body	the order or the search result, in the Hii Retail shape
4xx	the same status and body, passed on (answer 404 for an unknown order)
5xx, or a body that does not match the contract	502 Bad Gateway
nothing within the time limit	504 Gateway Timeout

The same time limit applies to fetching an OAuth token from your identity provider; a token that cannot be fetched in time gives 502 Bad Gateway.

⚠ Use the v2 endpoints. The v1 order-read and order-search endpoints still work in proxy mode, but both are deprecated in the API reference. A new integration should not be built on them. Note also that search changed verb between versions — v1 search is a POST, v2 search is a GET.

⚠ Staging does not enforce the read-only rule. The 405 is applied in production but skipped in staging, so a write that succeeds in your test environment will be refused in production. Do not take a successful staging write as evidence that proxy mode permits it.