Partner onboarding

How BMA, share, allocation, and territory pricing become live — and how to inspect them from partners, catalog, and allocations APIs.

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)#

GateYou need
BMAAn active Business Model Agreement with the vendor (and the master agreement, MCA, where required)
ShareVendor shared SKUs into your catalog + orders scope
AllocationCapacity on those SKUs (GET /allocations → sellable: true)
Territory pricingValid 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:

  1. Your seller company and the vendor company exist in Avrix.
  2. 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).
  3. Both sides complete the MCA and BMA acknowledgements until the agreement is active.
  4. The vendor shares catalog SKUs (scope must include catalog + orders for sellability).
  5. The vendor (or your ops flow) creates an allocation with capacity.
  6. 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.

DecisionOver the APIIn the console
Find a vendor and request a connectionFollow the request: GET /partners (status=pending) and the connection.request_decided eventSend, remind, withdraw
Answer a vendor's invitationFollow it: GET /partners (connectionRequest.waitingOn is seller)Accept or decline
Sign or change an agreement (MCA, BMA)Read the agreed terms: GET /partners/{connectionId}/agreementsSign, negotiate, renew, terminate
Accept or decline a title offerList: GET /partners/{connectionId}/offersAccept or decline
Accept or decline an access proposal (more countries, another currency)POST /access/proposals/{id}/accept and /declineAccept or decline
Ask for more keys on an allocationPOST /allocations/requestsSame

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.

SymptomLikely cause
Empty data[] on a production keyNo 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 keyCheck 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 catalogShares missing, shares suspended, or lifecycle gates hiding products
Catalog present, preview failsAllocation / 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:

FieldMeaning
connectionRequest.requestIdThe request id. Until the vendor approves, it is also the row's connectionId
connectionRequest.initiatedByseller (you asked) or vendor (the vendor invited you)
connectionRequest.waitingOnWhose answer a pending request waits for; null once rejected
connectionRequest.requestedAt, decidedAtWhen it was sent and when it was rejected
connectionRequest.reviewNoteThe note the vendor left when rejecting
connectionRequest.consoleUrlThe 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.

MethodPathScopePurpose
GET/api/seller/v1/access/proposalsAny seller scopeProposals waiting for your answer, oldest first
POST/api/seller/v1/access/proposals/{id}/acceptseller:account:manageAccept; applies now or at effectiveFrom
POST/api/seller/v1/access/proposals/{id}/declineseller:account:manageDecline; 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
JSON
{
  "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).

MethodPathPurpose
GET/api/seller/v1/allocations/requestsList requests you submitted
POST/api/seller/v1/allocations/requestsRequest 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}/cancelWithdraw 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#

EventWhen
contract.activatedAn agreement became active: the connection can trade
contract.amendment_acceptedA change to an agreement took effect, including an accepted access proposal
contract.expiring, contract.expired, contract.terminatedAn agreement nears its end date, passed it, or ended after notice
connection.suspended, connection.reactivated, connection.endedThe connection was paused, resumed or closed
access.proposal_createdA vendor proposed more countries or another currency
connection.request_decidedA 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#

  1. GET /whoami: confirm company and data.key.environment. Then GET /integration/status (seller:products:read): readyToSell, and the hint of any gate not yet satisfied.
  2. GET /partners: at least one active connection.
  3. GET /catalog/snapshot or GET /products: shared SKUs appear.
  4. GET /allocations: sellable: true for SKUs you intend to check out.
  5. POST /orders/preview with a real countryCode: canFulfill true 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
}'

What links here

Published guides that link to this page.

Search docs

Search documentation…