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, what you can see and do from the API, and what empty responses usually mean.
Who needs this#
Integrators seeing empty /partners or empty catalog snapshots, commercial contacts setting up the
first vendor relationship, and stores that want to follow their vendor relationships from their own
tooling.
TL;DR#
- Sellability needs four gates: BMA → share → allocation → territory pricing.
- Setting up a vendor relationship happens in the Avrix Console: finding vendors, requesting a connection, signing agreements and accepting title offers. The API reads every step of it and starts once an agreement is active.
- Over the API you can follow your connection requests (
GET /partners), read the agreed terms (GET /partners/{connectionId}/agreements), list title offers, and answer access proposals (more countries or another currency) with POST /access/proposals/{id}/accept or/decline. - 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 | An active Business Model Agreement with the vendor (and the master agreement, 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 request from the Console Network area: you request a connection
to a vendor, or the vendor invites you. Pending requests are on Network → Partners → Pending
requests (
/network/partners?tab=pending). - Both sides complete the MCA and 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 steps 3 to 6 are complete, Seller API catalog and order routes correctly return empty lists or hard 4xx refusals. That is expected, not a broken key.
What you can do over the API#
Each decision in a vendor relationship either has an API operation or is made in the console. The console is the only place for anything that signs or negotiates on your company's behalf.
| Decision | Over the API | In the console |
|---|---|---|
| Find a vendor and request a connection | Follow the request: GET /partners (status=pending) and the connection.request_decided event | Send, remind, withdraw |
| Answer a vendor's invitation | Follow it: GET /partners (connectionRequest.waitingOn is seller) | Accept or decline |
| Sign or change an agreement (MCA, BMA) | Read the agreed terms: GET /partners/{connectionId}/agreements | Sign, negotiate, renew, terminate |
| Accept or decline a title offer | List: GET /partners/{connectionId}/offers | Accept or decline |
| Accept or decline an access proposal (more countries, another currency) | POST /access/proposals/{id}/accept and /decline | Accept or decline |
| Ask for more keys on an allocation | POST /allocations/requests | Same |
API inspection#
List partners#
GET /api/seller/v1/partners
Authorization: Bearer <key>
Requires seller:products:read (see Scope matrix).
Each connection row includes the connection identifiers, the vendor's public profile fields and a
read-only contracts summary (activeBmaTypes, mcaStatus, catalogShareMode,
sharesSuspended) for pre-pull diagnostics. catalogShareMode is all when the agreement was
signed as Full catalog and selected for hand-picked titles; the shared SKUs are what you can sell
in both cases.
publisherCompanyId identifies the vendor. Pass it as partner to filter GET /products and
GET /catalog/checksum; it is a slug-safe company id of at most 32 characters, not a UUID, and
connectionId is not accepted there. The publisher* field names are kept for compatibility; they
describe the vendor.
Statuses. A connection is active, suspended, terminating (notice given; still live until
terminationEffectiveAt) or terminated. A connection request is pending or rejected.
status narrows the list to the values you name, on every contract date:
GET /api/seller/v1/partners?status=pending,rejected
Without status, contract dates before 2026-12-01 list active, suspended and terminated
rows, exactly as before. On 2026-12-01 and later the default also lists terminating connections
and pending requests. rejected rows are listed only when you ask for them.
| Symptom | Likely cause |
|---|---|
Empty data[] on a production key | No active connection yet, or the wrong company or key. Ask for status=pending to see requests still waiting for an answer |
Empty data[] on a sandbox key | Check GET /whoami: no sandboxCatalog block means sandbox is not enabled for your key; sandboxCatalog.tenantReady: false means the shared sandbox catalog is not ready yet. Retry later or contact Avrix support. Settings → Integrations → API Keys → Sandbox developer tools runs the golden path for the key |
| Partners present, empty catalog | Shares missing, shares suspended, or lifecycle gates hiding products |
| Catalog present, preview fails | Allocation / territory / trading-state gates; see the readiness guide |
Connection requests#
A request to connect, whether you sent it or the vendor invited you, is a row on GET /partners
with status pending or rejected and a connectionRequest object:
| Field | Meaning |
|---|---|
connectionRequest.requestId | The request id. Until the vendor approves, it is also the row's connectionId |
connectionRequest.initiatedBy | seller (you asked) or vendor (the vendor invited you) |
connectionRequest.waitingOn | Whose answer a pending request waits for; null once rejected |
connectionRequest.requestedAt, decidedAt | When it was sent and when it was rejected |
connectionRequest.reviewNote | The note the vendor left when rejecting |
connectionRequest.consoleUrl | The console page where you follow or answer it |
A request row has no connection yet: its contracts summary is empty, and
GET /partners/{connectionId}/offers and /agreements answer 404 for its id. When the vendor
approves, the row is replaced by the connection row, which has its own connectionId. Key your
records on publisherCompanyId to follow a vendor from request to connection. A vendor can appear
twice: a terminated connection and a new request.
Requests are sent, reminded, withdrawn and answered in the console. A vendor's draft invitation is not visible until the vendor sends it.
Agreed terms#
GET /api/seller/v1/partners/{connectionId}/agreements
Authorization: Bearer <key>
Requires seller:products:read. Lists the agreements in force on the connection (active,
terminating) or suspended (paused): the master agreement (mca) first, then each business-model
agreement (api, revenue_share, wholesale, pre_order). Each row has the dates
(effectiveFrom, expiresAt, terminationEffectiveAt), renewalPolicy, the territory orders
are checked against, your sellerRevenueSharePercent, the settlement terms (paymentCurrency,
paymentTermsDays, reportingFrequency, reportingDeadlineDays), the sale-currency rule
(permittedSaleCurrencies; per-currency detail is on GET /whoami) and a consoleUrl to the
agreement and its signed document. Agreements still being negotiated or waiting for a signature are
not listed; contracts.pendingBmaTypes on GET /partners counts them.
Read it again when contract.activated, contract.amendment_accepted, contract.expiring,
contract.expired or contract.terminated arrives.
Title offers#
Titles the vendor has offered under an active agreement, which you have not accepted or declined yet, are not part of your catalog:
GET /api/seller/v1/partners/{connectionId}/offers
Authorization: Bearer <key>
The list is read only. Accept or decline each offer in the console; an accepted title then arrives
as a share, on GET /catalog/changes and in GET /products.
Access proposals#
A vendor can propose to widen what you may sell on an existing connection: more countries, or another currency. Nothing changes until you accept. Unlike title offers, you answer access proposals over the API.
| Method | Path | Scope | Purpose |
|---|---|---|---|
GET | /api/seller/v1/access/proposals | Any seller scope | Proposals waiting for your answer, oldest first |
POST | /api/seller/v1/access/proposals/{id}/accept | seller:account:manage | Accept; applies now or at effectiveFrom |
POST | /api/seller/v1/access/proposals/{id}/decline | seller:account:manage | Decline; the vendor is told |
Both answers require an Idempotency-Key header and take no body. seller:account:manage is not
in the default scope set of a console-created key; add it to the key that answers. The same
proposals are listed per vendor on GET /whoami under accessByPublisher[].proposals, next to the
territory and currencies in force.
POST /api/seller/v1/access/proposals/3f6b2c1a-9d4e-4b7a-8c2d-5e1f0a9b8c7d/accept
Authorization: Bearer <key>
Idempotency-Key: 0c7e6b1e-2f3a-4d5b-9c8d-7e6f5a4b3c2d
{
"data": {
"id": "3f6b2c1a-9d4e-4b7a-8c2d-5e1f0a9b8c7d",
"status": "accepted",
"effectiveFrom": null
}
}
Subscribe to access.proposal_created to learn of a new proposal without polling;
contract.amendment_accepted follows when an accepted proposal applies. A refusal keeps the generic
top-level code and names the reason in details.accessCode; the
error reference lists every value and what to do. A proposal that
was already answered or withdrawn answers 409 with details.accessCode AMENDMENT_NOT_PROPOSED;
a retry with the same Idempotency-Key replays the first answer instead. The sandbox has no access
proposal to answer yet, so handle these refusals from the table rather than by rehearsal.
Allocation requests#
When an allocation runs out, you can ask the Content Owner for more. An allocation is named by its
id from GET /allocations; request bodies call it allocationId (grantId is the older name for
the same id and still works).
| Method | Path | Purpose |
|---|---|---|
GET | /api/seller/v1/allocations/requests | List requests you submitted |
POST | /api/seller/v1/allocations/requests | Request more keys for an allocation |
GET | /api/seller/v1/allocations/requests/{id} | Read one request and its state |
POST | /api/seller/v1/allocations/requests/{id}/cancel | Withdraw a request that is still pending |
The Content Owner decides each request, unless their rules approve it automatically; the answer's
state says which. See Catalog and allocations.
Events#
| Event | When |
|---|---|
contract.activated | An agreement became active: the connection can trade |
contract.amendment_accepted | A change to an agreement took effect, including an accepted access proposal |
contract.expiring, contract.expired, contract.terminated | An agreement nears its end date, passed it, or ended after notice |
connection.suspended, connection.reactivated, connection.ended | The connection was paused, resumed or closed |
access.proposal_created | A vendor proposed more countries or another currency |
connection.request_decided | A vendor approved or rejected a connection request you sent |
Knowing the answer to your connection request. connection.request_decided fires once when the
vendor decides on a request your company sent. decision: "approved" carries the new
connectionId: the connection now exists, and its agreements still need signing in the console;
contract.activated follows when an agreement becomes active and the connection can trade.
decision: "rejected" carries the vendor's reviewNote. Nothing fires for a vendor's invitation,
which you answer yourself, or for a request you withdraw. Without a webhook, poll
GET /partners?status=pending,rejected, or read the event from GET /events on contract date
2026-12-01 and later.
No event fires for a title offer; poll GET /partners/{connectionId}/offers. See the
Event reference.
Readiness after a connection#
GET /whoami: confirmcompanyanddata.key.environment. ThenGET /integration/status(seller:products:read):readyToSell, and thehintof any gate not yetsatisfied.GET /partners: at least oneactiveconnection.GET /catalog/snapshotorGET /products: shared SKUs appear.GET /allocations:sellable: truefor SKUs you intend to check out.POST /orders/previewwith a realcountryCode: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 vendors.
- Production API access may require Avrix approval (
PRODUCTION_ACCESS_NOT_APPROVED) even when a BMA exists; see Authentication and Go-live.
Code samples#
List your vendor connections. Each row's contracts tells you whether the agreement is active and
how the catalog is shared.
curl -s -X GET "https://api.avrix.io/api/seller/v1/partners?limit=50" \
-H "Authorization: Bearer $AVRIX_API_KEY"Ask a vendor for more keys on an allocation. allocationId is the allocation's id from
GET /allocations (grantId, its older name, is still accepted); declaredForecast is
optional. The vendor decides; the request does not raise the ceiling by itself.
curl -s -X POST "https://api.avrix.io/api/seller/v1/allocations/requests" \
-H "Authorization: Bearer $AVRIX_API_KEY" \
-H "Idempotency-Key: allocation-request-3f1c2a9e" \
-H "Content-Type: application/json" \
-d '{
"allocationId": "3f1c2a9e-8b7d-4c6e-9a10-5d2e7b4f8c21",
"requestedQuantity": 100,
"declaredForecast": 250
}'