Before catalog sync or checkout can succeed, your seller company needs a live commercial path with at least one vendor. This page covers how that path is established, how to inspect it from the API, and what empty responses usually mean.
Who needs this#
Integrators seeing empty /partners or empty catalog snapshots, and commercial contacts setting up
the first vendor relationship.
TL;DR#
- Sellability needs four gates: BMA → share → allocation → territory pricing.
- Agreements and shares are created in the Avrix Console (or by the vendor); the API reads the
result via
GET /partners, catalog, and allocation routes. - Empty partners on a production key usually means no active connection yet — not an auth bug.
- Sandbox keys use a shared sandbox catalog with magic SKUs; do not expect sandbox partner rows on a live key (and the reverse).
The four gates (reminder)#
| Gate | You need |
|---|---|
| BMA | Active business master agreement with the vendor (MCA where required) |
| Share | Vendor shared SKUs into your catalog + orders scope |
| Allocation | Capacity on those SKUs (GET /allocations → sellable: true) |
| Territory pricing | Valid price for the buyer’s country on the API model |
See How Avrix works and Sellable SKU readiness for the full permission model.
Console path (human)#
Typical first connection:
- Your seller company and the vendor company exist in Avrix.
- One party sends a connection / agreement request from the Console Network area.
- Both sides complete MCA / BMA acknowledgements until the agreement is active.
- The vendor shares catalog SKUs (scope must include catalog + orders for sellability).
- The vendor (or your ops flow) creates an allocation with capacity.
- Territory / regional pricing is in place for countries you will sell into.
Until step 3–6 complete, Seller API catalog and order routes correctly return empty lists or hard 4xx refusals — that is expected, not a broken key.
API inspection#
List partners#
GET /api/seller/v1/partners
Authorization: Bearer <key>
Requires a products / catalog read scope (see Scope matrix).
Each row includes connection identifiers, publisher-facing fields, and a read-only contracts
summary (activeBmaTypes, mcaStatus, catalogShareMode, sharesSuspended) for pre-pull
diagnostics.
| Symptom | Likely cause |
|---|---|
Empty data[] on a production key | No active BMA connection yet, or wrong company / key |
Empty data[] on a sandbox key | Shared sandbox catalog not provisioned on that deployment — contact Avrix or check Console sandbox status |
| Partners present, empty catalog | Shares missing, shares suspended, or lifecycle gates hiding products |
| Catalog present, preview fails | Allocation / territory / trading-state gates — see readiness guide |
Allocation requests#
When a grant ceiling is exhausted, you can ask for more capacity:
| Method | Path | Purpose |
|---|---|---|
GET | /api/seller/v1/allocations/requests | List requests you submitted |
POST | /api/seller/v1/allocations/requests | Request more keys for a grant |
Vendors still approve capacity — the API records the request; it does not auto-raise the ceiling.
Readiness after a connection#
- GET /whoami — confirm company, environment,
integrationReadiness. GET /partners— at least one connected vendor.- GET /catalog/snapshot or GET /products — shared SKUs appear.
- GET /allocations —
sellable: truefor SKUs you intend to checkout. - POST /orders/preview with a real
countryCode—canFulfilltrue before you charge a buyer.
Environment pitfalls#
- Sandbox vs production keys select different tenants. A production key will not see sandbox magic SKUs; a sandbox key will not see your live BMA partners.
- Production API access may require Avrix approval (PRODUCTION_ACCESS_NOT_APPROVED) even when a BMA exists — see Authentication and Go-live.