Proxy Mode

When requested by a tenant, the Customer Order service can be configured to proxy incoming requests to a specified URL. This allows the service to act as a middleman between the tenant and the external service, while still providing the ability to access the data through HiiRetail APIs and Frontends.

Configuration

To enable the proxy mode, the tenant must connect the HiiRetail team and provide the URL of the external service. The team will then set up the tenant to use the proxy mode. After the proxy mode is enabled, the tenant will be able to configure the authentication method for the external service. At this point, the tenant will be able to access the Customer Order service through the HiiRetail API while the service will proxy the requests to the configured external service.

External service that is being proxied must be able to handle the requests from the Customer Order service. To learn more about the format that the external service must implement, please refer to the External Service Configuration documentation.

Authentication

While in proxy mode, the Customer Order wil authenticate the requsts to the external service using the configured authentication method. To set up the authentication, an admin user on the tenant's side must provide the necessary credential by using the PUT: /api/v1/proxy-config endpoint.

Proxy mode currently supports the following authentication methods:

• Basic Authentication

{
  "type": "basic",
  "config": {
    "username": "admin",
    "password": "password"
  }
}

• OAuth2

{
  "type": "oauth2",
  "config": {
    "clientId": "client_id",
    "clientSecret": "client",
    "authUrl": "https://example.com/token"
  }
}

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.

⚠ 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.