Scope matrix

Authoritative mapping of API key scopes to routes.

TopicsReference

Every Seller API key carries a list of scopes. Each operation accepts a key that holds any one of the scopes listed for it; the first one listed is the preferred scope, the one to put on a new key. This page is the single answer to "which scope do I need": the two tables at the end are generated from the API reference (x-avrix-scopes on each operation), and a gate keeps the API reference equal to what the API accepts.

Authoritative sellable list: GET /allocations (sellable: true) — not /products or /catalog/snapshot alone.

Choosing scopes for a new key#

Request the preferred scope for each job your service does, and nothing else: least privilege per key.

JobPreferred scope
Read the catalog, prices, availability and allocationsseller:products:read
Read orders and key pull historyseller:orders:read
Place, hold, reserve, commit, cancel and recover orders; pull keysseller:orders:write (includes order reads and preview)
Price a cart without placing itseller:orders:preview
Reveal keys for a ready preorder or backorderseller:orders:fulfill
Revoke or regenerate a keyless fulfilmentseller:orders:manage
Ask a vendor for more stock; change an allocation's top-up settingsseller:allocations:write
Report refunds and chargebacks, return keys, freeze keys in a disputeseller:refunds:write
Read refund and chargeback statusseller:refunds:read
Read finance: balances, sales, invoices, statements, the settlement feedseller:finance:read
Export keys as a ZIP fileseller:keys:export
Manage API keys over the APIseller:keys:write
Register and manage webhook endpointsseller:webhooks:write (read-only: seller:webhooks:read)
Read promotions; accept, decline or answer themseller:promotions:read, seller:promotions:respond
Change your selling footprint and order presets; answer a vendor's access proposalseller:account:manage

GET /whoami, GET /access/proposals, GET /sandbox/certification, POST /geo/attest, GET /me/footprint and GET /me/integration-presets need no specific scope: any key that holds at least one Seller API scope can call them.

Legacy scope names#

Two scope names from the first version of the API are still accepted wherever they were, and will stay accepted. They are deprecated in this documentation: do not put them on a new key, and move to the preferred names when you next issue a key. Nothing is refused because a key holds them, and no date has been set to stop accepting them.

Legacy scopeWhere it is still acceptedUse instead
seller:keys:pullOrdering and key pulls; order reads; refund and dispute writes and refund reads; allocation writesseller:orders:write for orders, seller:orders:read for order reads, seller:refunds:write / seller:refunds:read for refunds, seller:allocations:write for allocation writes
seller:products:read on order reads and the settlement feedGET /orders, GET /orders/{orderId}, GET /transactions, GET /activityseller:orders:read for orders, seller:finance:read for GET /activity

seller:orders:write grants everything seller:keys:pull grants, so a key can swap one for the other without losing an operation. seller:keys:export is the exception: neither name grants a key export, which needs its own scope.

When a key lacks a scope#

A request whose key holds none of the operation's scopes is refused with 403. Nothing was changed.

  • On contract date 2026-12-01 and later (pinned with X-Avrix-Api-Version, or next), the code is INSUFFICIENT_SCOPE. details.requiredScopes lists every scope the operation accepts, preferred first (the same list as in the tables below), and details.missingScope names the preferred one. details.scopeMode is anyOf, or any for the operations that accept any Seller API scope.
  • On earlier contract dates and for requests that do not pin one, the code is FORBIDDEN with details.missingScope and details.requiredScopes as they have always been reported. Where an operation has since started accepting more scopes, that older list can be shorter than the tables below.

A key with no scopes at all also gets details.reason: "scopes_required"; there is no implicit default. Scopes cannot be added to an existing key: issue a new key with the scope, move your service to it, then revoke the old one.

Console base scopes#

Keys created in Settings → Integrations → API Keys pre-select exactly these base scopes (from BASE_SELLER_API_KEY_SCOPES):

ScopeDefault
seller:products:readOn
seller:orders:previewOn
seller:keys:pullOn
seller:keys:writeOn
seller:refunds:readOn
seller:refunds:writeOn
seller:promotions:readOn
seller:promotions:respondOn
seller:webhooks:readOn
seller:webhooks:writeOn

The base set still pre-selects the legacy seller:keys:pull. It grants the same operations as seller:orders:write: deselect it and select seller:orders:write (and seller:orders:read or seller:allocations:write where you need them) to use the preferred names.

The scope picker offers every scope in the tables below, including the preferred names (seller:orders:read, seller:orders:write, seller:allocations:write) and the opt-in scopes that are never pre-selected: seller:finance:read, seller:orders:fulfill, seller:orders:manage, seller:keys:export and seller:account:manage. Deselect anything your service does not need.

seller:account:manage and seller:keys:export are the scopes a legacy key does not receive. Keys issued before scoping existed were backfilled with everything available at the time; that reasoning does not extend to a surface added afterwards: one changes the footprint your sales are settled against, the other hands out a file of plaintext keys. Issue a key with the scope explicitly if you need it.

What each scope grants#

Generated from the API reference. "Preferred scope for" lists the operations where the scope is listed first; "Also accepted on" lists the operations that accept it as one of several.

ScopePreferred scope forAlso accepted on
seller:account:managePOST /access/proposals/{id}/accept, POST /access/proposals/{id}/decline, PUT /me/footprint, PUT /me/integration-presets, DELETE /me/integration-presetsnone
seller:allocations:writePATCH /allocations/{id}, POST /allocations/requests, POST /allocations/requests/{id}/cancelnone
seller:finance:readGET /activity, GET /finance/summary, GET /finance/api-sales, GET /finance/invoices, GET /finance/statements, GET /finance/ledger, GET /finance/api-sales/{transactionId}, GET /finance/invoices/{invoiceId}/reconciliation, GET /finance/invoices/{invoiceId}, GET /finance/invoices/{invoiceId}/document, GET /finance/payments, GET /finance/reports, GET /finance/reports/{reportId}, GET /finance/reports/{reportId}/linesGET /refunds, GET /disputes, GET /disputes/{freezeId}, GET /refunds/{refundId}, POST /refunds/preview, GET /returns, GET /returns/{returnRequestId}
seller:keys:exportPOST /keys/exportnone
seller:keys:pullnonePATCH /allocations/{id}, POST /allocations/requests, POST /allocations/requests/{id}/cancel, GET /transactions, POST /keys/pull, GET /keys/pulls, POST /keys/return, GET /refunds, POST /refunds, GET /orders, POST /orders, POST /orders/reserve, POST /orders/commit, POST /orders/reservations/{reservationId}/commit, POST /orders/preview, POST /orders/hold, DELETE /orders/hold, GET /orders/hold/{holdId}, DELETE /orders/hold/{holdId}, POST /disputes/freeze, POST /disputes/{freezeId}/release, GET /disputes, GET /disputes/{freezeId}, POST /orders/recover-keys, POST /orders/cancel, POST /orders/bulk, GET /orders/{orderId}, POST /orders/{orderId}/extend, POST /orders/reservations/{reservationId}/extend, GET /refunds/{refundId}, POST /refunds/preview, POST /chargebacks/resolve, GET /returns, POST /returns, GET /returns/{returnRequestId}, POST /returns/{returnRequestId}/reply, POST /returns/{returnRequestId}/cancel, POST /returns/{returnRequestId}/evidence, POST /orders/{orderId}/keys/{keyId}/replace, POST /orders/{orderId}/fulfill
seller:keys:readGET /keys, GET /api-keysnone
seller:keys:writePOST /keys, POST /api-keys, DELETE /keys/{id}, DELETE /api-keys/{id}, PATCH /keys/{id}/allowed-ips, PATCH /api-keys/{id}/allowed-ips, POST /keys/{id}/rotate, POST /api-keys/{id}/rotateGET /keys, GET /api-keys
seller:orders:fulfillPOST /orders/{orderId}/fulfillnone
seller:orders:managePOST /orders/fulfillments/{fulfillmentId}/revoke, POST /orders/fulfillments/{fulfillmentId}/regeneratenone
seller:orders:previewPOST /orders/previewnone
seller:orders:readGET /transactions, GET /keys/pulls, GET /orders, GET /orders/hold/{holdId}, GET /orders/{orderId}none
seller:orders:writePOST /keys/pull, POST /orders, POST /orders/reserve, POST /orders/commit, POST /orders/reservations/{reservationId}/commit, POST /orders/hold, DELETE /orders/hold, DELETE /orders/hold/{holdId}, POST /orders/recover-keys, POST /orders/cancel, POST /orders/bulk, POST /orders/{orderId}/extend, POST /orders/reservations/{reservationId}/extend, POST /orders/{orderId}/keys/{keyId}/replacePATCH /allocations/{id}, POST /allocations/requests, POST /allocations/requests/{id}/cancel, GET /transactions, GET /keys/pulls, POST /keys/return, GET /refunds, POST /refunds, GET /orders, POST /orders/preview, GET /orders/hold/{holdId}, POST /disputes/freeze, POST /disputes/{freezeId}/release, GET /disputes, GET /disputes/{freezeId}, GET /orders/{orderId}, GET /refunds/{refundId}, POST /refunds/preview, POST /chargebacks/resolve, GET /returns, POST /returns, GET /returns/{returnRequestId}, POST /returns/{returnRequestId}/reply, POST /returns/{returnRequestId}/cancel, POST /returns/{returnRequestId}/evidence, POST /orders/{orderId}/fulfill
seller:products:readGET /products, GET /products/lookup, GET /products/{productId}, GET /products/{productId}/pricing, GET /catalog/checksum, GET /catalog/changes, GET /catalog/snapshot, GET /partners, GET /partners/{connectionId}/offers, GET /partners/{connectionId}/agreements, GET /allocations, GET /allocations/{id}, GET /allocations/{id}/replenishments, GET /allocations/requests, GET /allocations/requests/{id}, GET /availability, GET /usage, GET /requests/{requestId}, GET /availability/changes, GET /availability/{skuCode}, GET /regions, GET /regions/{code}, GET /products/{productId}/media/download, GET /platforms, GET /integration/status, POST /catalog/exports, GET /catalog/exports/{exportId}GET /transactions, GET /keys/pulls, GET /orders, GET /orders/hold/{holdId}, GET /orders/{orderId}, GET /activity
seller:promotions:readGET /promotions/summary, GET /promotions/shares, GET /promotions/shares/{shareId}, GET /promotions/deals, GET /promotions/deals/{responseId}, GET /promotions/shares/{shareId}/discounts, GET /promotions/calendarnone
seller:promotions:respondPOST /promotions/shares/{shareId}/accept, POST /promotions/shares/{shareId}/decline, POST /promotions/deals/{responseId}/respondnone
seller:refunds:readGET /refunds, GET /disputes, GET /disputes/{freezeId}, GET /refunds/{refundId}, POST /refunds/preview, GET /returns, GET /returns/{returnRequestId}none
seller:refunds:writePOST /keys/return, POST /refunds, POST /disputes/freeze, POST /disputes/{freezeId}/release, POST /chargebacks/resolve, POST /returns, POST /returns/{returnRequestId}/reply, POST /returns/{returnRequestId}/cancel, POST /returns/{returnRequestId}/evidenceGET /refunds, GET /disputes, GET /disputes/{freezeId}, GET /refunds/{refundId}, POST /refunds/preview, GET /returns, GET /returns/{returnRequestId}
seller:webhooks:readGET /webhooks/event-types, GET /webhooks, GET /webhooks/{id}, GET /webhooks/{id}/deliveries/{deliveryId}, GET /webhooks/{id}/deliveries, GET /eventsnone
seller:webhooks:writePOST /webhooks, PATCH /webhooks/{id}, DELETE /webhooks/{id}, POST /webhooks/{id}/test, POST /webhooks/{id}/enable, POST /webhooks/{id}/disable, POST /webhooks/{id}/deliveries/{deliveryId}/retry, POST /webhooks/{id}/deliveries/replaynone
(any seller scope)GET /access/proposals, POST /geo/attest, GET /geo/attest/{attestId}, GET /whoami, GET /me/footprint, GET /me/integration-presets, GET /sandbox/certification, POST /sandbox/reset, POST /sandbox/allocations/requests/{requestId}/resolve, POST /sandbox/allocations/{allocationId}/stock-events, POST /sandbox/promotions/deals/{responseId}/window
(no key)GET /whoami-ip, GET /health, GET /geo/attest/{attestId}/pixel, POST /geo/attest/{attestId}/complete, POST /api/seller/oauth/token, GET /webhooks/egress-ips

Scopes per operation#

Generated from the API reference. A key that holds any one of the listed scopes is accepted; the preferred scope is in bold. "Any seller scope" means a key holding at least one Seller API scope; "No key" means the operation reads no key.

GroupOperationAccepted scopes (any one; preferred in bold)
AllocationsGET /allocationsseller:products:read
AllocationsGET /allocations/{id}seller:products:read
AllocationsPATCH /allocations/{id}seller:allocations:write, seller:orders:write, seller:keys:pull
AllocationsGET /allocations/{id}/replenishmentsseller:products:read
AllocationsGET /allocations/requestsseller:products:read
AllocationsPOST /allocations/requestsseller:allocations:write, seller:orders:write, seller:keys:pull
AllocationsGET /allocations/requests/{id}seller:products:read
AllocationsPOST /allocations/requests/{id}/cancelseller:allocations:write, seller:orders:write, seller:keys:pull
AllocationsGET /availabilityseller:products:read
AllocationsGET /availability/changesseller:products:read
AllocationsGET /availability/{skuCode}seller:products:read
CatalogGET /productsseller:products:read
CatalogGET /products/lookupseller:products:read
CatalogGET /products/{productId}seller:products:read
CatalogGET /products/{productId}/pricingseller:products:read
CatalogGET /catalog/checksumseller:products:read
CatalogGET /catalog/changesseller:products:read
CatalogGET /catalog/snapshotseller:products:read
CatalogGET /partners/{connectionId}/agreementsseller:products:read
CatalogGET /products/{productId}/media/downloadseller:products:read
CatalogPOST /catalog/exportsseller:products:read
CatalogGET /catalog/exports/{exportId}seller:products:read
FinanceGET /finance/summaryseller:finance:read
FinanceGET /finance/api-salesseller:finance:read
FinanceGET /finance/invoicesseller:finance:read
FinanceGET /finance/statementsseller:finance:read
FinanceGET /finance/ledgerseller:finance:read
FinanceGET /finance/api-sales/{transactionId}seller:finance:read
FinanceGET /finance/invoices/{invoiceId}/reconciliationseller:finance:read
FinanceGET /finance/invoices/{invoiceId}seller:finance:read
FinanceGET /finance/invoices/{invoiceId}/documentseller:finance:read
FinanceGET /finance/paymentsseller:finance:read
FinanceGET /finance/reportsseller:finance:read
FinanceGET /finance/reports/{reportId}seller:finance:read
FinanceGET /finance/reports/{reportId}/linesseller:finance:read
KeysPOST /keys/exportseller:keys:export
KeysPOST /keys/pullseller:orders:write, seller:keys:pull
KeysGET /keys/pullsseller:orders:read, seller:orders:write, seller:products:read, seller:keys:pull
OrdersGET /transactionsseller:orders:read, seller:orders:write, seller:products:read, seller:keys:pull
OrdersGET /ordersseller:orders:read, seller:orders:write, seller:products:read, seller:keys:pull
OrdersPOST /ordersseller:orders:write, seller:keys:pull
OrdersPOST /orders/reserveseller:orders:write, seller:keys:pull
OrdersPOST /orders/commitseller:orders:write, seller:keys:pull
OrdersPOST /orders/reservations/{reservationId}/commitseller:orders:write, seller:keys:pull
OrdersPOST /orders/previewseller:orders:preview, seller:orders:write, seller:keys:pull
OrdersPOST /orders/holdseller:orders:write, seller:keys:pull
OrdersDELETE /orders/holdseller:orders:write, seller:keys:pull
OrdersGET /orders/hold/{holdId}seller:orders:read, seller:orders:write, seller:products:read, seller:keys:pull
OrdersDELETE /orders/hold/{holdId}seller:orders:write, seller:keys:pull
OrdersPOST /orders/recover-keysseller:orders:write, seller:keys:pull
OrdersPOST /orders/cancelseller:orders:write, seller:keys:pull
OrdersPOST /orders/bulkseller:orders:write, seller:keys:pull
OrdersGET /orders/{orderId}seller:orders:read, seller:orders:write, seller:products:read, seller:keys:pull
OrdersPOST /orders/{orderId}/extendseller:orders:write, seller:keys:pull
OrdersPOST /orders/reservations/{reservationId}/extendseller:orders:write, seller:keys:pull
OrdersPOST /orders/fulfillments/{fulfillmentId}/revokeseller:orders:manage
OrdersPOST /orders/fulfillments/{fulfillmentId}/regenerateseller:orders:manage
OrdersPOST /orders/{orderId}/keys/{keyId}/replaceseller:orders:write, seller:keys:pull
OrdersPOST /orders/{orderId}/fulfillseller:orders:fulfill, seller:orders:write, seller:keys:pull
PartnersGET /partnersseller:products:read
PartnersGET /partners/{connectionId}/offersseller:products:read
PartnersGET /access/proposalsAny seller scope
PartnersPOST /access/proposals/{id}/acceptseller:account:manage
PartnersPOST /access/proposals/{id}/declineseller:account:manage
PromotionsGET /promotions/summaryseller:promotions:read
PromotionsGET /promotions/sharesseller:promotions:read
PromotionsGET /promotions/shares/{shareId}seller:promotions:read
PromotionsPOST /promotions/shares/{shareId}/acceptseller:promotions:respond
PromotionsPOST /promotions/shares/{shareId}/declineseller:promotions:respond
PromotionsGET /promotions/dealsseller:promotions:read
PromotionsGET /promotions/deals/{responseId}seller:promotions:read
PromotionsPOST /promotions/deals/{responseId}/respondseller:promotions:respond
PromotionsGET /promotions/shares/{shareId}/discountsseller:promotions:read
PromotionsGET /promotions/calendarseller:promotions:read
Reference dataGET /regionsseller:products:read
Reference dataGET /regions/{code}seller:products:read
Reference dataGET /platformsseller:products:read
RefundsPOST /keys/returnseller:refunds:write, seller:orders:write, seller:keys:pull
RefundsGET /refundsseller:refunds:read, seller:refunds:write, seller:finance:read, seller:orders:write, seller:keys:pull
RefundsPOST /refundsseller:refunds:write, seller:orders:write, seller:keys:pull
RefundsPOST /disputes/freezeseller:refunds:write, seller:orders:write, seller:keys:pull
RefundsPOST /disputes/{freezeId}/releaseseller:refunds:write, seller:orders:write, seller:keys:pull
RefundsGET /disputesseller:refunds:read, seller:refunds:write, seller:finance:read, seller:orders:write, seller:keys:pull
RefundsGET /disputes/{freezeId}seller:refunds:read, seller:refunds:write, seller:finance:read, seller:orders:write, seller:keys:pull
RefundsGET /refunds/{refundId}seller:refunds:read, seller:refunds:write, seller:finance:read, seller:orders:write, seller:keys:pull
RefundsPOST /refunds/previewseller:refunds:read, seller:refunds:write, seller:finance:read, seller:orders:write, seller:keys:pull
RefundsPOST /chargebacks/resolveseller:refunds:write, seller:orders:write, seller:keys:pull
RefundsGET /returnsseller:refunds:read, seller:refunds:write, seller:finance:read, seller:orders:write, seller:keys:pull
RefundsPOST /returnsseller:refunds:write, seller:orders:write, seller:keys:pull
RefundsGET /returns/{returnRequestId}seller:refunds:read, seller:refunds:write, seller:finance:read, seller:orders:write, seller:keys:pull
RefundsPOST /returns/{returnRequestId}/replyseller:refunds:write, seller:orders:write, seller:keys:pull
RefundsPOST /returns/{returnRequestId}/cancelseller:refunds:write, seller:orders:write, seller:keys:pull
RefundsPOST /returns/{returnRequestId}/evidenceseller:refunds:write, seller:orders:write, seller:keys:pull
SandboxGET /sandbox/certificationAny seller scope
SandboxPOST /sandbox/resetAny seller scope
SandboxPOST /sandbox/allocations/requests/{requestId}/resolveAny seller scope
SandboxPOST /sandbox/allocations/{allocationId}/stock-eventsAny seller scope
SandboxPOST /sandbox/promotions/deals/{responseId}/windowAny seller scope
Seller authGET /keysseller:keys:read, seller:keys:write
Seller authPOST /keysseller:keys:write
Seller authGET /api-keysseller:keys:read, seller:keys:write
Seller authPOST /api-keysseller:keys:write
Seller authDELETE /keys/{id}seller:keys:write
Seller authDELETE /api-keys/{id}seller:keys:write
Seller authPATCH /keys/{id}/allowed-ipsseller:keys:write
Seller authPATCH /api-keys/{id}/allowed-ipsseller:keys:write
Seller authPOST /keys/{id}/rotateseller:keys:write
Seller authPOST /api-keys/{id}/rotateseller:keys:write
Seller authPOST /api/seller/oauth/tokenNo key
Seller metaGET /whoami-ipNo key
Seller metaGET /healthNo key
Seller metaGET /usageseller:products:read
Seller metaGET /requests/{requestId}seller:products:read
Seller metaPOST /geo/attestAny seller scope
Seller metaGET /geo/attest/{attestId}Any seller scope
Seller metaGET /geo/attest/{attestId}/pixelNo key
Seller metaPOST /geo/attest/{attestId}/completeNo key
Seller metaGET /whoamiAny seller scope
Seller metaGET /activityseller:finance:read, seller:products:read
Seller metaGET /integration/statusseller:products:read
Seller metaGET /me/footprintAny seller scope
Seller metaPUT /me/footprintseller:account:manage
Seller metaGET /me/integration-presetsAny seller scope
Seller metaPUT /me/integration-presetsseller:account:manage
Seller metaDELETE /me/integration-presetsseller:account:manage
WebhooksGET /webhooks/event-typesseller:webhooks:read
WebhooksGET /webhooksseller:webhooks:read
WebhooksPOST /webhooksseller:webhooks:write
WebhooksGET /webhooks/{id}seller:webhooks:read
WebhooksPATCH /webhooks/{id}seller:webhooks:write
WebhooksDELETE /webhooks/{id}seller:webhooks:write
WebhooksPOST /webhooks/{id}/testseller:webhooks:write
WebhooksPOST /webhooks/{id}/enableseller:webhooks:write
WebhooksPOST /webhooks/{id}/disableseller:webhooks:write
WebhooksGET /webhooks/{id}/deliveries/{deliveryId}seller:webhooks:read
WebhooksPOST /webhooks/{id}/deliveries/{deliveryId}/retryseller:webhooks:write
WebhooksPOST /webhooks/{id}/deliveries/replayseller:webhooks:write
WebhooksGET /webhooks/{id}/deliveriesseller:webhooks:read
WebhooksGET /eventsseller:webhooks:read
WebhooksGET /webhooks/egress-ipsNo key

GET /health reads a key when one is sent but does not require it. POST /geo/attest/{attestId}/complete and GET /geo/attest/{attestId}/pixel are called from the buyer's checkout page and secured by the attestation id. POST /api/seller/oauth/token takes the key's client credentials instead of a Bearer key. GET /sandbox/certification also needs a sandbox key (a production key answers 422 SANDBOX_KEY_REQUIRED).

Every production key needs an IP allowlist or a trusted workload binding. A production key with neither is refused with 403 ALLOWLIST_REQUIRED while whoami.capabilities.requireProductionAllowlistEnabled is true. Once you configure entries, requests from other addresses are rejected with 403 IP_NOT_ALLOWED.

Finance base path: Canonical /api/seller/v1/finance/.... Same host and Authorization: Bearer as the rest of the Seller API. Unversioned /api/seller/finance/... redirects to /v1/.

Key lifecycle (expiry, create-then-retire vs in-place rotate, ~60s revocation): Authentication.

See also Integration recipes and Sandbox for 403 triage.

  • Quickstart — create a key with the right scopes before your first order
  • Authentication — credentials, expiry, rotation
  • IP allowlist — egress IP restrictions per key, and when an empty list is refused
  • Integration recipes — scopes and call order per flow
  • Error playbook — INSUFFICIENT_SCOPE and FORBIDDEN (missing scope), IP_NOT_ALLOWED, and recovery actions

What links here

Published guides that link to this page.

Search docs

Search documentation…