Hub Gateway API

The Hub Gateway (/api/hub/*) is the API HomeiCloud B2B exposes to Homei Hub (the distributor storefront). It lets a Hub distributor browse the B2B catalog, apply to list products, read live inventory, quote delivery, and place, track, or cancel dropship orders — without ever learning which fulfillment provider ships the goods.

Base URL

https://<your-b2b-host>/api/hub

Endpoints

Conventions

• Money is always integer minor units (US cents). currency is "USD".
• Dimensions are millimetres (*Mm) and grams (weightGrams); null where undeclared.
• Caching: gateway responses set cache-control: no-store — always read live, never cache stale price or stock.
• Stock (available): an integer sellable count, or null for an untracked (unlimited) variant. inStock is the boolean buyers care about.
• variant.id is the stable sellable key. Hub keys pricing, cart, inventory, and orders off the B2B variant.id; it is never recycled or regenerated. On the order endpoints this same id is passed as orderKey.
• Publish gate. A product is only visible/orderable when it is active, has qcStatus = passed, comes from an approved supplier, and has a priced primary variant. Items that fall out of the gate simply stop being returned — there is no explicit "removed" event, so consumers must reconcile on each read.

Error model

Errors return a JSON body with an error string and the relevant HTTP status. Some 4xx responses include an extra field listing the offending keys (e.g. unknown, unavailable, untracked, unauthorized, shortItems, unpriced, expected).

Idempotency

• Orders are idempotent on reference: a repeat POST re-reads the existing order group and returns it rather than double-creating.
• Applications, withdrawals, and cancellations are idempotent — safe to retry.

Continue to Authentication to start making requests.