The API

One endpoint:

GET /api/v1/order-responses?businessUnitIds=BU1,BU2&itemIds=I1,I2

Both parameters are required and each needs at least one value. There is no "everything" form — asking for all confirmations across a tenant is deliberately not possible, because the request is answered by reading your system live and an unbounded query would be an unbounded load on it.

Each parameter accepts either a comma-separated list or the parameter repeated:

?businessUnitIds=BU1,BU2&itemIds=I1
?businessUnitIds=BU1&businessUnitIds=BU2&itemIds=I1

What comes back

Grouped by item, then by business unit, then broken down by shipment:

{
  "items": [
    {
      "itemId": "I1",
      "businessUnits": [
        {
          "businessUnitId": "BU1",
          "confirmedQuantity": 120,
          "shipments": [
            { "deliveryDateTime": "2026-06-20T10:00:00Z", "confirmedQuantity": 100 },
            { "deliveryDateTime": "2026-07-04T10:00:00Z", "confirmedQuantity": 20 }
          ]
        }
      ]
    }
  ]
}

The business-unit total is the sum of its shipments

confirmedQuantity on a business unit is always recomputed from its shipments — it is never taken from your system, even if your system supplies one.

That matters when the two disagree. If your system reports a total of 120 but lists shipments of 100 and 15, this endpoint answers 115, because the shipments are what it adds up. The disagreement is not reported as an error and nothing is logged for you to find, so a mismatch shows up only as a number that is quietly lower or higher than the one in your own system.

The practical consequence: treat the shipment breakdown as the authoritative part of your response. If a total matters to you, make sure your shipments add up to it.

Authorization is per tenant, not per business unit

🛑 businessUnitIds is a filter, not a permission boundary. The orr.order-response.read permission grants read access across the caller's whole tenant. Any caller holding it can query any business unit in that tenant, including ones they have no other access to.

This is deliberate, not an oversight — but it is the opposite of what several other Hii Retail endpoints do, where the business unit sits in the path and is checked. If you need per-store restriction, enforce it in the system that calls this endpoint. Passing fewer business units narrows the result; it does not narrow what the caller is allowed to see.

Tenant isolation is unaffected. The tenant comes from the verified bearer token, or from the Tenant-Id header for service-to-service callers whose token is not tenant-scoped — never from the path, query or body. A caller cannot read another tenant's confirmations.

Errors

Status	Meaning
400	a parameter is missing or empty — both are required, each with at least one value
401	the bearer token is missing or invalid
404	no system is registered for this tenant. See Connecting your system
502	your registered system was unreachable or returned an error

404 and an empty result are different answers

A 404 means "nothing is configured to answer this". An empty items array means "your system answered, and it has no confirmations for what you asked". The distinction is deliberate: a misconfigured tenant fails loudly rather than looking like a tenant with nothing on order.

502 means your system, not Hii Retail

Order Response has no data of its own to fall back on, so it cannot degrade gracefully — if your system is down, the request fails. This is the safer behaviour: the alternative would be answering from stale or absent data and letting you believe nothing is on order when the truth is that nobody could reach the system that knows.

Check your own system first when you see a 502.