The Seller API carries four version markers:
- URL version:
/api/seller/v1/*is the canonical public route family for the current major contract (including finance under/api/seller/v1/finance/*). Every unversioned/api/seller/<segment>/*path redirects (307, method and body kept) to its/v1/form — the URL a doc shows is the URL that responds. Five segments,access,chargebacks,disputes,geoandme, redirect only for requests pinned to2026-12-01(ornext); on earlier dates they are served in place by the same handler./api/seller/oauth/tokenand/api/seller/whoami-ipare served unversioned as well as under/v1/. - Date contract header: every response includes
X-Avrix-Api-Versioncarrying the effective contract date for that request. A request that sends no header is served the stamped default,2026-09-01. Send the same header on a request to pin a date:2026-04-29can still be pinned, and2026-10-01and2026-12-01are opt-in pins that are never applied to an unpinned request (see Supported contract dates). Unsupported values return400 UNSUPPORTED_API_VERSION. This header is the authoritative version marker. The OpenAPI document'sinfo.versionis the stamped default (2026-09-01), the same date the SDKs pin, andinfo.x-avrix-contract-dateslists the default, every supported date and the opt-in ones. Both are checked against the dates in code on every change. - Legacy major marker (deprecated): every response also includes
X-Api-Version: 1. It is deprecated — still emitted for compatibility and never bumped; do not build logic on it. - Webhook event version: every webhook delivery includes
eventVersionin the JSON body andX-Avrix-Event-Versionin headers.
Precedence: URL family (/v1) scopes the route surface; X-Avrix-Api-Version (date
contract) governs field-level compatibility within that surface; X-Api-Version carries no
compatibility meaning. When markers appear to disagree, the date contract wins.
OAuth routes use /api/seller/oauth/* (no /v1/ segment) but still emit both version headers.
Every change to the API, and every documentation correction an integrator should know about, is an
entry in the Changelog. Each entry is labelled with its type and says who
must act, so the entries that can affect a running integration (Breaking, Changed behaviour,
Deprecated) can be found without reading the rest. This page sets the rules those entries follow.
Response version headers (both are intentional)#
| Header | Meaning | Pin? |
|---|---|---|
X-Api-Version | Deprecated legacy major marker (1) | No — informational only, never bumped |
X-Avrix-Api-Version | Date contract (e.g. 2026-09-01) | Yes — use this for compatibility and changelogs |
Do not treat X-Api-Version: 1 as a substitute for the date contract.
Request Header#
Partners may send:
X-Avrix-Api-Version: 2026-09-01
A value that is not in the table below answers 400 UNSUPPORTED_API_VERSION; it never changes
behavior silently. Omit the header and the request is served the stamped default.
next is accepted with sandbox and production keys alike and resolves to the newest supported
date, opt-in dates included. Use it in sandbox to rehearse an upcoming contract. Pin an explicit
date in production: what next resolves to moves on the day a new date ships.
Supported contract dates#
| Date | Status | Behavior differences |
|---|---|---|
2026-04-29 | Supported pin. Was the stamped default until 2026-09-01 UTC | Launch contract. POST /orders/bulk with omitted strict allows partial success. |
2026-09-01 | Stamped default for unpinned requests since 2026-09-01 UTC; also a supported pin | POST /orders/bulk defaults omitted strict to true (whole-cart atomicity; send strict: false explicitly to opt back into partial success). No other behavior changes. |
2026-10-01 | Supported pin (opt-in; not a stamped default) | Order responses and POST /orders/recover-keys return typed key objects in keys ({ id, type, key, url, expiresAt, redemption }) instead of plaintext strings. keyIds is unchanged. Webhooks are not affected. |
2026-12-01 | Supported pin (opt-in; not a stamped default) | Everything on 2026-10-01, plus: a missing or malformed Idempotency-Key answers 400 IDEMPOTENCY_KEY_REQUIRED instead of 400 BAD_REQUEST; a key without the scope an operation needs answers 403 INSUFFICIENT_SCOPE instead of 403 FORBIDDEN; every orderReadableId on an order response equals orderId; order reads are not cached; answering a promotion share or deal again with the answer it already has returns 200 and a different answer 409 CONFLICT instead of 400 BAD_REQUEST; a webhook delivery replay never clones a replay or a test delivery; a list refuses an unreadable cursor with 422; a change-feed position beyond retention answers 409 CATALOG_RESYNC_REQUIRED; GET /allocations?sellableOnly=true fills each page; GET /events serves the event log (one row per event, filterable by eventType, resourceType and resourceId) instead of webhook delivery rows; a malformed X-Request-Id answers 400 INVALID_REQUEST_ID; GET /requests/{requestId} answers 404 for an id nothing recorded; API-key management is counted in the general rate-limit class; a database failure on product detail, pricing or the catalog snapshot answers 504/503 with Retry-After or a generic 500; the five unversioned segments above redirect to /v1/; a promotion whose state forbids the call (expired, started, withdrawn, not accepted) answers 409 CONFLICT with details.reason instead of 400, a deal of another company 404, and a promotion read that fails 503 or 504; an accepted share's discount table is served outside its window with meta.active: false; sellable and blockedReason on GET /products/{productId}/pricing are the order path's answer for each country; the media download answers on the standard error body, with 404 PRODUCT_NOT_SHARED for a product not shared with you and the Seller API 401 without a key, and ends its archive with a manifest; POST /catalog/exports refuses a body it cannot use with 422; GET /finance/statements refuses an unknown format and answers an infrastructure failure with 503 or 504; the reconciliation of an invoice without a settlement answers 409 CONFLICT instead of 404; PUT /me/footprint answers with the footprint as stored and refuses unknown country and currency codes; keyDisposition on POST /refunds and POST /keys/return gives the real outcome (held, mixed); a partial refund leaves the order fulfilled; POST /keys/return ends dispute freezes; POST /keys/pull and POST /keys/export bind the previewed price; POST /allocations/requests answers 201 instead of 200 for a request it files; PATCH /allocations/{id} refuses a revoked allocation with 409 CONFLICT (details.reason: allocation_revoked) instead of saving a trigger that cannot fire; a failed JSON POST /oauth/token carries the RFC 6749 code in error, and a JSON token request that sends client credentials both in the body and with HTTP Basic answers 422; POST /orders/preview on a paused allocation answers 400 BAD_REQUEST as POST /orders does instead of 404 ALLOCATION_INACTIVE; GET /partners without status also lists terminating connections and pending connection requests; a test send to a disabled webhook endpoint is sent instead of refused with 400; POST /webhooks/{id}/enable refuses a body that is not a JSON object with 422; a company registers at most 16 webhook endpoints (409 WEBHOOK_ENDPOINT_LIMIT_REACHED); an Idempotency-Key reused with the same body on another path parameter (PATCH /allocations/{id}, POST /orders/{orderId}/keys/{keyId}/replace) answers 409 IDEMPOTENCY_KEY_MISMATCH instead of replaying the first answer. Corrections that change what an existing request gets back are released on this date only; the Changelog labels each one. |
next | Alias | Resolves to the newest supported date, opt-in dates included (currently 2026-12-01), for rehearsing an upcoming contract. |
Responses echo the effective date in the X-Avrix-Api-Version header — and
POST /orders/bulk additionally echoes meta.contractDate + meta.strict in
the body — so a client can assert which behavior profile served each call.
Unpinned requests have been served the 2026-09-01 contract since
2026-09-01 (UTC); pin 2026-04-29 if you depend on partial-success bulk
carts.
Contract dates are cumulative: a later date keeps the behaviour of every earlier one. 2026-10-01
and 2026-12-01 never become the default by themselves: an unpinned request stays on 2026-09-01
until a cutover is announced here and in the Changelog.
Forward compatibility (required)#
Clients MUST:
- Ignore unknown JSON fields in responses and webhook payloads.
- Ignore unknown enum values they do not understand (do not fail closed solely because a new enum member appeared).
Avrix may add optional fields and new enum members without bumping the major URL family. Strict parsers that reject unknowns will break on additive releases.
Naming conventions#
Every name in the Seller API means one thing, and every concept has one name. Where the API grew
a second name for a concept, or one name for two concepts, the convention below gives the name to
use. The older name keeps working: it stays on the wire with the same value, the API reference
marks it deprecated, and the Active deprecations table lists it. Within
v1 nothing is renamed or removed; removing an older name needs a new major contract, and none is
scheduled.
Money#
- An amount is an integer in the minor units of the currency named beside it, and
currencyExponentsays how many minor-unit digits that currency has (2 for EUR, 0 for JPY, 3 for KWD). See Money fields. - An amount's name ends in
Minor:unitPriceMinor,totalMinor,grossMinor. The amount of a per-currency bucket isamountMinor. - A name ending in
Cents, and the barecentsof a per-currency bucket, is an older name of the same value. Every success response and every webhook event that carries one also carries itsMinorname (unitPriceCentsandunitPriceMinor,centsandamountMinor). Read theMinorname. totalNetRevenueonGET /finance/summaryreports is the one amount in major units (a decimal).totalNetRevenueMinorcarries the same total in minor units, withcurrencyExponent.- Request fields keep their names: send
expectedUnitPriceCentsas before. CSV exports keep their column names.
Ids#
| Concept | Name | Not to be confused with |
|---|---|---|
| An order | orderId | orderReference, your own id for the sale |
One key pull, a row of GET /keys/pulls | keyPullId (id is its older name) | transactionId |
| A sale row of the finance feed | transactionId, the id POST /orders returns in transactionIds[] and GET /finance/api-sales/{transactionId} reads; a key pull row names the sale it produced as transactionId | keyPullId |
| A game key (one delivered code) | keyId, keyIds[] | apiKeyId |
| An API key (a credential) | apiKeyId on api_key.* events, id on /api-keys | keyId |
| The number Avrix gives an invoice | platformInvoiceNumber | supplierInvoiceNumber |
| The number on the Content Owner's own invoice document | supplierInvoiceNumber (null when they use none) | platformInvoiceNumber |
invoiceNumber keeps the value it always had on each surface: the platform number on
GET /finance/invoices, and on invoice.issued and invoice.paid the supplier number when there
is one, otherwise the platform number. Read platformInvoiceNumber or supplierInvoiceNumber
instead; both carry the same value on the list and on the events.
Status values#
A refund has one vocabulary: pending, completed, chargeback_open, chargeback_lost,
chargeback_won. GET /refunds uses it for status, and a finance sale row uses it for
refundStatus (null when nothing took the sale back). adjustmentStatus on the same row keeps
the ledger's own values (refund_pending, refunded, ...). pending is declared but not produced
today: a refund is recorded complete in the request that asks for it. Handle it anyway.
Paths#
- A collection is a plural noun:
/orders,/refunds,/api-keys. - An action on one resource names that resource's id in the path, under the resource's own name,
and ends in the action's verb:
POST /orders/reservations/{reservationId}/commit,DELETE /orders/hold/{holdId}. A body that also names the resource must name the same one, or the request is refused with422 VALIDATION_FAILED. /keyspaths act on game keys (/keys/pull,/keys/return,/keys/pulls). API keys are managed under/api-keys.
| Path | Older path, same handler |
|---|---|
GET /keys/pulls | GET /transactions |
GET /api-keys, POST /api-keys | GET /keys, POST /keys |
DELETE /api-keys/{id} | DELETE /keys/{id} |
POST /api-keys/{id}/rotate | POST /keys/{id}/rotate |
PATCH /api-keys/{id}/allowed-ips | PATCH /keys/{id}/allowed-ips |
DELETE /orders/hold/{holdId} | DELETE /orders/hold with holdId in the body |
POST /orders/reservations/{reservationId}/commit | POST /orders/commit with reservationId in the body |
POST /orders/reservations/{reservationId}/extend | POST /orders/{orderId}/extend, whose orderId is a reservation id |
Each pair runs the same handler: same scopes, rate limit, Idempotency-Key rule, responses and
errors. The one addition is the 422 for a body id that disagrees with the path id.
Operation ids#
- An operation id is a verb then a noun, in camelCase:
listfor a page of a collection,getfor one resource,create,updateanddelete, or the action's own verb (commit,extend,release,rotate). Examples:listKeyPulls,createApiKey,commitReservation. - An operation id never changes, because generated SDK method names come from it. A new path gets a new operation id; the older path keeps its own, so both SDK methods keep working.
Breaking Change Policy#
Avrix does not release any of the following without a versioned rollout, compatibility mode, or migration notice:
- New mandatory request fields.
- Removed or renamed response fields.
- Removed enum values or webhook event names.
- Changed webhook payload meaning.
- Stricter commercial metadata enforcement for existing production keys.
Changes to an existing request ship behind the next contract date#
A change that alters what an existing, unchanged request gets back ships only for requests on
the next contract date (today 2026-12-01) and later. Requests that send an earlier date, and
unpinned requests, keep exactly the behaviour they have. This covers:
- a new refusal of a request that is accepted today;
- a changed HTTP status or error
codefor the same request; - a changed field: its value, type or shape, or a field that is removed or renamed.
What ships for every caller at once, because a client written to the forward compatibility rules is not affected: new operations, new optional request fields and parameters, new response fields, new enum values, new webhook events and new response headers.
A rename starts as an alias: the new name is added, the old one keeps working and is marked deprecated, and nothing is removed until a sunset date is published (see Deprecation communication).
Every such change has a changelog entry labelled Changed behaviour or Breaking that names the
contract date and says who must act. A check on each change to the API reference compares it with
the previous version and refuses a breaking difference without that entry. When the reference was
wrong and the API already behaved the new way, the entry says so and names each corrected operation
on a Reference correction line instead: the API did not change, but a client generated from the
old reference may have to.
Recent breaking changes#
| Change | Effective | Migration |
|---|---|---|
POST /orders — orderReference is now required (non-empty, max 255). | Pre-GA (v1) | Send your store order id on every create-order call. Duplicate-order detection and replay scoping key off orderReference + allocation, so an order without one cannot be de-duplicated server-side. POST /orders/preview, POST /orders/reserve and POST /keys/pull are unchanged. Requests omitting it now return 422 VALIDATION_FAILED. |
A missing or malformed Idempotency-Key answers 400 IDEMPOTENCY_KEY_REQUIRED instead of 400 BAD_REQUEST on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Match on IDEMPOTENCY_KEY_REQUIRED for this refusal; details.idempotency says key_missing or key_invalid. Earlier dates and unpinned requests are unchanged. |
GET /orders?status= with a value the environment's order listing cannot serve yet (any value other than fulfilled, returned, refunded until durable-order reads are on) answers 422 VALIDATION_FAILED instead of an empty 200 page on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Handle the 422 (details.issues[0].allowedValues lists the values that can be served), or look the order up by orderReference. Earlier dates and unpinned requests are unchanged. See Order lifecycle. |
A request whose key lacks the scope the operation needs answers 403 INSUFFICIENT_SCOPE instead of 403 FORBIDDEN on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Match on INSUFFICIENT_SCOPE as well as FORBIDDEN; details.requiredScopes lists every scope the operation accepts and details.scopeMode says whether one of them is needed. Earlier dates and unpinned requests are unchanged. See the error reference. |
Every orderReadableId on an order response holds the same value as orderId, and a GET /orders list row's orderId is the order's one id in both read models, on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Store and compare orderId. An orderReadableId saved before this release still resolves on GET /orders/{orderId}; compare stored ids on orderReference if they predate it. Earlier dates and unpinned requests are unchanged. |
GET /orders is sent with Cache-Control: private, no-store instead of private, max-age=60 on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Expect each order read to reach the API and count against the orders rate limit. Earlier dates and unpinned requests are unchanged. |
Answering a promotion that already has an answer (POST /promotions/shares/{shareId}/accept, .../decline, POST /promotions/deals/{responseId}/respond): the same answer again returns 200 with the promotion's status, a different answer returns 409 CONFLICT with details.currentStatus, instead of 400 BAD_REQUEST for both, on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Treat the 200 as success (a retry of a call that worked). On 409, read details.currentStatus: the promotion keeps the answer it has. Earlier dates and unpinned requests are unchanged. See Promotions. |
POST /webhooks/{id}/deliveries/replay leaves out deliveries that are themselves replays or test deliveries on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Nothing, unless you relied on replaying a replay: replay the original delivery instead (its window still holds it). Earlier dates and unpinned requests clone every matching delivery, as before. |
A paged list answers 422 VALIDATION_FAILED (details.issues[].field is cursor) for a cursor it cannot read, instead of serving the first page, on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Send back only meta.nextCursor values the same list returned. Earlier dates and unpinned requests are unchanged. See Lists and pagination. |
GET /catalog/changes and GET /availability/changes answer 409 CATALOG_RESYNC_REQUIRED (details.reason: retention_expired) for a cursor or since older than the feed's retention, instead of a page that silently skips the deleted rows, on contract dates >= 2026-12-01. GET /catalog/changes also refuses a limit that is not a whole number from 1 to 5000, and both feeds give their 422 the details.issues[] form. | Opt-in: only requests pinned to 2026-12-01 (or next) | On the 409, take a fresh GET /catalog/snapshot and continue from its meta.changesCursor and meta.availabilityCursor. Earlier dates and unpinned requests are unchanged. See the error reference. |
GET /allocations?sellableOnly=true fills each page with sellable allocations up to limit, instead of filtering one page after it is cut, on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Nothing to change if you loop on meta.hasMore. A client that counted short or empty pages gets full ones. Earlier dates and unpinned requests are unchanged. |
GET /events lists events from your event log, one row per event whether or not an endpoint subscribes (id, eventType, occurredAt, resourceType, resourceId, payload), instead of one row per webhook delivery (endpointId, status, attempts), on contract dates >= 2026-12-01; eventType, resourceType and resourceId filter it. | Opt-in: only requests pinned to 2026-12-01 (or next) | Read delivery status from GET /webhooks/{id}/deliveries. Deduplicate events on id, the same value webhook deliveries carry as eventLogId. Earlier dates and unpinned requests keep the delivery rows and ignore the filters. See Event log. |
An X-Request-Id request header that is not 8 to 128 characters from A-Z, a-z, 0-9, _, ., : and - answers 400 INVALID_REQUEST_ID before anything runs, on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Send a UUID or ULID, or omit the header and log the id the response returns. Earlier dates and unpinned requests echo any value, as before. See the error reference. |
GET /requests/{requestId} answers 404 NOT_FOUND (details.lookupRequestId, details.retentionDays) for an id nothing recorded, instead of 200 with empty lists, on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Treat the 404 as "no record of this id in 90 days". Earlier dates answer 200 with coverage: "none". See Monitoring and support. |
API-key management (GET and POST /keys, DELETE /keys/{id}, POST /keys/{id}/rotate, PATCH /keys/{id}/allowed-ips) is counted in the general rate-limit class instead of orders on contract dates >= 2026-12-01: its X-RateLimit-* numbers are those of general and it no longer shares the checkout budget. | Opt-in: only requests pinned to 2026-12-01 (or next) | Nothing, unless you paced key management from the orders numbers: read X-RateLimit-Bucket. Earlier dates and unpinned requests are unchanged. See Rate limits. |
GET /products/{productId}, GET /products/{productId}/pricing and GET /catalog/snapshot answer a database timeout with 504 HOT_PATH_TIMEOUT and an unavailable dependency with 503 SERVICE_UNAVAILABLE (both with Retry-After), and any other failure with a generic 500 INTERNAL_ERROR message, instead of 500 INTERNAL_ERROR with the repository's message, on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Retry 503 and 504 after Retry-After, as on every other route. Earlier dates keep the 500. |
/api/seller/access/*, /api/seller/chargebacks/*, /api/seller/disputes/*, /api/seller/geo/* and /api/seller/me/* (no /v1/) redirect with 307 to their /v1/ form, like every other unversioned path, for requests that send X-Avrix-Api-Version: 2026-12-01 (or next). | Opt-in: only requests pinned to 2026-12-01 (or next) | Call the /v1/ paths. A client that does not follow redirects must. Earlier dates and unpinned requests are served in place. |
A promotion whose state forbids the call answers 409 CONFLICT with details.reason instead of 400 BAD_REQUEST: answering an expired, started, past-deadline or withdrawn share or deal (SHARE_EXPIRED, PROMOTION_STARTED, RESPONSE_DEADLINE_PASSED, PROMOTION_WITHDRAWN), or reading the discount table of a share that is not accepted (NOT_ACCEPTED). Answering a deal of another company answers 404 instead of 400. A failed read on deal detail, deal respond, the discount table or the summary's deals answers 503 / 504 with Retry-After instead of 400, 500 or a 200 with zero deal counts. On contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Treat 409 as "the offer's state changed": read it again (details.currentStatus). Retry 503 and 504 after Retry-After. Earlier dates and unpinned requests are unchanged. See Promotions. |
GET /promotions/shares/{shareId}/discounts returns an accepted share's rows before and after its window too, with meta.active: false, instead of an empty data, on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Apply the rows only while meta.active is true. Earlier dates and unpinned requests are unchanged. See Promotions. |
sellable and blockedReason on every price of GET /products/{productId}/pricing are the order path's answer for that SKU in that country (footprint, agreement currencies and territory, the SKU's territory and region locks, catalog price, priced currency), instead of whether the price's currency is allowed for the country, on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Expect more sellable: false, with any of the order path's refusal codes in blockedReason; hide those countries or show the reason. Earlier dates and unpinned requests are unchanged. See Pricing. |
GET and HEAD /products/{productId}/media/download answer errors on the standard error body instead of { code, message, requestId }, 404 PRODUCT_NOT_SHARED instead of NOT_FOUND for a product that exists but is not shared with you, and the Seller API 401 (with X-Request-Id) instead of a console-session error or a bare 401 without an API key; the archive ends with avrix-media-manifest.json (complete, entries[]), on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Read code from the standard body and treat PRODUCT_NOT_SHARED as "remove from your listing". Check complete before trusting an archive and skip the manifest entry when unpacking. Earlier dates and unpinned requests are unchanged. See the error reference. |
POST /catalog/exports refuses a body that is not a JSON object, has a key other than pricing, or a pricing other than "territory", with 422 VALIDATION_FAILED, instead of ignoring it, on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Send no body, {} or { "pricing": "territory" }. Earlier dates and unpinned requests ignore a body they cannot use. |
GET /finance/statements answers 422 VALIDATION_FAILED for a format other than json or csv (field format) and for a bad limit (field limit), and 503 or 504 with Retry-After for an infrastructure failure instead of 500, on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Send format=json or format=csv; retry a 503 or 504 after Retry-After. Earlier dates and unpinned requests serve JSON for an unknown format, as before. |
GET /finance/invoices/{invoiceId}/reconciliation for an issued invoice you owe that has no settlement answers 409 CONFLICT (details.reason: RECONCILIATION_NOT_AVAILABLE, details.invoicePath) instead of 404, on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Ask for the file only when the invoice has reconciliationAvailable: true; read the invoice at details.invoicePath. Earlier dates and unpinned requests answer 404. See the error reference. |
PUT /me/footprint answers with the footprint as stored (duplicates removed, sorted) instead of echoing the request, and refuses a code that names no country or current currency with 422 VALIDATION_FAILED, on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Compare the answer to your request as sets; send only real ISO 3166-1 and ISO 4217 codes. Earlier dates and unpinned requests get the echo and store any code of the right length. |
keyDisposition on POST /refunds and POST /keys/return is quarantined, held (keys sold under revenue share stay with you) or mixed, instead of always quarantined, on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Keep held keys in your records; on mixed, read refunds[].keyDisposition. Earlier dates and unpinned requests are unchanged. See Refunds and key returns. |
After POST /refunds, an order's status follows its keys (refunded once every key is refunded, fulfilled after a partial refund), instead of the orderReference you send turning refunded at the first refunded key, on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Read refunds[] on the order to see partial refunds. Earlier dates and unpinned requests are unchanged. See Refunds and key returns. |
POST /keys/return ends any dispute freeze on its keys (key.unfrozen, resolution refunded), as POST /refunds does, on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Nothing, unless you release the freeze yourself afterwards: it has already ended. Earlier dates and unpinned requests are unchanged. |
POST /keys/pull reads priceCommitmentToken, and POST /keys/export reads priceCommitmentToken, expectedUnitPriceCents and expectedWholesaleUnitPriceCents, with the rules of POST /orders, instead of ignoring them, on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Send a current token from POST /orders/preview, or leave the field out. Earlier dates and unpinned requests ignore the fields. |
POST /allocations/requests answers 201 Created instead of 200 OK when it files a request or grants it at once, on contract dates >= 2026-12-01. The body is the same. | Opt-in: only requests pinned to 2026-12-01 (or next) | Treat any 2xx as success. Refusals are unchanged. Earlier dates and unpinned requests keep 200. |
PATCH /allocations/{id} on a revoked allocation answers 409 CONFLICT with details.reason: allocation_revoked instead of saving the top-up trigger, on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Do not set a trigger on a revoked allocation; GET /allocations/{id} shows its status. Earlier dates and unpinned requests save it, and it never fires (effective.mode: off). |
A failed JSON POST /oauth/token request carries the RFC 6749 error code in error (invalid_client, invalid_request, unsupported_grant_type, ...) instead of the message, and a JSON request that sends the client credentials both in the body (client_secret) and in an Authorization: Basic header answers 422 VALIDATION_FAILED (invalid_request) instead of reading the body and ignoring the header, on contract dates >= 2026-12-01. Form-encoded token requests behave this way on every date. | Opt-in: only requests pinned to 2026-12-01 (or next) | Read the message from message or error_description, and branch on code or the RFC 6749 error. Send the client credentials one way. Earlier dates and unpinned requests are unchanged. POST /oauth/token reads the date from X-Avrix-Api-Version but does not validate it: an unsupported value is served the stamped default instead of 400 UNSUPPORTED_API_VERSION. See OAuth tokens. |
POST /orders/preview on a paused or otherwise inactive allocation answers 400 BAD_REQUEST with the message and details (orderStage: allocation, allocationResolve: NO_ACTIVE_ALLOCATION) that POST /orders returns, instead of 404 ALLOCATION_INACTIVE, on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Match the 400 and details.allocationResolve as you do for POST /orders; details.previewError and details.allocationStatus are kept. Earlier dates and unpinned requests keep the 404. |
GET /partners without status lists connections with status terminating (notice given, still live) and connection requests with status pending (connectionId is the request id; connectionRequest is set) besides active, suspended and terminated connections, on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Skip rows whose status is pending where you need a tradeable connection, and treat terminating like active until terminationEffectiveAt. status selects exactly the rows you want on every date. Earlier dates and unpinned requests are unchanged. See Partner onboarding. |
POST /webhooks/{id}/test on a disabled endpoint queues one test delivery (202) instead of answering 400 BAD_REQUEST, on contract dates >= 2026-12-01. The endpoint stays disabled; the test is not retried and does not count toward its health. | Opt-in: only requests pinned to 2026-12-01 (or next) | Use it to check a fixed receiver before POST /webhooks/{id}/enable. A client that treated the 400 as "endpoint disabled" reads status from GET /webhooks/{id} instead. Earlier dates and unpinned requests are unchanged. See Webhooks. |
POST /webhooks/{id}/enable answers 422 VALIDATION_FAILED for a body that is not a JSON object, instead of ignoring it, on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Send no body, {}, or {"replayFrom": "<date-time>"}. Earlier dates and unpinned requests ignore a body that is not JSON, as before. |
POST /webhooks answers 409 WEBHOOK_ENDPOINT_LIMIT_REACHED when the company already has 16 webhook endpoints (active and disabled; per key for a sandbox key), on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Subscribe one endpoint to more events (wildcards such as order.* or *) instead of adding endpoints, or delete unused ones. Endpoints above the limit keep working. Earlier dates and unpinned requests have no limit. See the error reference. |
Sandbox keys only: X-Avrix-Sandbox-Simulate with a value the operation does not honour (a misspelling, or a value that belongs to another operation) answers 422 SANDBOX_SIMULATE_UNKNOWN before any work, instead of being ignored, on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Send one of the values in details.honoured, or drop the header. Production keys and earlier dates ignore the header as before. See the error reference. |
Sandbox keys only: X-Avrix-Sandbox-Simulate is honoured on more operations: rate_limit, internal_error and service_unavailable on every write (including POST /orders/cancel, /orders/recover-keys, /keys/export, /keys/return, /refunds and /chargebacks/resolve, which ignored the header), and buyer_verification_required on the checkout calls, on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Nothing, unless your sandbox tests send the header on every call: send it only on the calls you mean to fail. Production keys and earlier dates honour what they did. See Sandbox. |
Sandbox keys on the shared sandbox only: PUT /me/footprint and PATCH /allocations/{id} answer 422 SANDBOX_ISOLATED_ENVIRONMENT_REQUIRED instead of changing data every store on the shared sandbox reads, on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Rehearse these writes in your store's isolated sandbox environment. Production keys, isolated environments and earlier dates are unchanged. See the error reference. |
PATCH /allocations/{id} and POST /orders/{orderId}/keys/{keyId}/replace compare the path parameters, as well as the body, with an earlier use of the same Idempotency-Key: the same key and body on another allocation or key answers 409 IDEMPOTENCY_KEY_MISMATCH instead of replaying the first answer (a 200 for a target that was never changed), on contract dates >= 2026-12-01. | Opt-in: only requests pinned to 2026-12-01 (or next) | Use one key per target, and retry with the same X-Avrix-Api-Version you first sent. Earlier dates and unpinned requests are unchanged. See Idempotency. |
keys on POST /orders, /orders/bulk, /orders/commit, /orders/{orderId}/fulfill, /orders/{orderId}/keys/{keyId}/replace, /keys/pull and /orders/recover-keys become typed key objects on contract dates >= 2026-10-01. | Opt-in: only requests pinned to 2026-10-01 (or next) | Read keys[i].key (text), keys[i].url (link, image, file) and keys[i].redemption. Stay on 2026-09-01 to keep string[]. |
POST /orders/bulk — omitted strict defaults to true on contract dates >= 2026-09-01. | The stamped default for unpinned requests since 2026-09-01 UTC; pinning 2026-04-29 keeps partial success | Send strict explicitly (recommended: true) and the default never affects you. Clients that rely on partial-success carts must send strict: false, or pin 2026-04-29 until migrating. |
Deprecation Communication#
Avrix publishes changelog / guide entries before removing fields. The Active deprecations table lists a Sunset date when a removal is scheduled. Avrix has not published a minimum notice period between that entry and the sunset; the date in the table and in the entry is the commitment.
Response headers. One registry lists every deprecated operation, query parameter and request
header, the same set the API reference marks deprecated, and a planned change of the contract
date served to unpinned requests. An entry sends headers only once a date is set for it:
Deprecation: @<Unix seconds>(RFC 9745), the date the deprecation took effect, withLink: <page>; rel="deprecation";Sunset: <HTTP-date>(RFC 8594) when a removal date is scheduled, withLink: <page>; rel="sunset".
A request carries them only when it uses the deprecated operation, parameter or header. For a
change of the default contract date, only requests that send no X-Avrix-Api-Version carry them:
a pinned request's contract does not move. No date is set today, so no response carries these
headers. A date is set only after the changelog entry naming it is published. All three header
names are already in Access-Control-Expose-Headers, and the API reference declares Deprecation
and Sunset as response header components.
The same mechanism covers contract dates: when a pinned X-Avrix-Api-Version value is scheduled
for removal, responses pinned to that date carry Deprecation: true, Sunset: <HTTP-date> and
Link: <…/versioning>; rel="deprecation". Requests on a current date never see them.
When a concrete sunset is scheduled for a field or route, Avrix will:
- Document the change and sunset date on this page and in the Changelog.
- Announce it as a
platform.noticewebhook event (categorydeprecation). - Start sending
DeprecationandSunseton the affected responses. - Keep
X-Avrix-Api-Versionas the stable version signal until then.
Subscribe to changes. Two channels deliver changes without anyone re-reading this site:
- the Changelog as an RSS feed,
https://docs.avrix.io/changelog.xml, one item per dated entry, for a feed reader or a channel integration; - the
platform.noticewebhook event, sent to every endpoint subscribed to it when Avrix announces a contract change, a deprecation, a change of the default contract date, the switch of rate limits to enforced or planned maintenance. Addplatform.noticeto an endpoint'seventsto receive it. See Event reference.
Active deprecations#
| Surface | Deprecated | Replacement | First notice | Sunset |
|---|---|---|---|---|
GET /products, GET /catalog/snapshot, GET /products/{id} — product status field | Legacy 4-state lifecycle rollup (draft / active / discontinued / archived). Still emitted, now derived from the lifecycle dimensions (values unchanged). | launchPhase (draft / announced / pre_order / available), tradingState (open / paused / discontinued), isArchived (boolean) on the same responses | 2026-08-03 | Not scheduled — headers stay off per policy above |
GET /products/{id} — release status field | Legacy release status string. | Release-level launchPhase / tradingState (effective values: override inheritance + date auto-advance) | 2026-08-03 | Not scheduled |
GET /products — status query parameter | Filters on the derived legacy rollup; visible products always match active. | Client-side filtering on launchPhase / tradingState / isArchived | 2026-08-03 | Not scheduled |
Webhook product.updated / product.delisted — productStatus field | Legacy rollup in webhook payloads (derived; values unchanged). | launchPhase / tradingState / isArchived in the same payloads | 2026-08-03 | Not scheduled |
GET /products/{id} release pricing[], GET /products/{id}/pricing release prices[] | The release-level list price. A sale charges the SKU price. | skus[].prices[] on the same responses | 2026-10-06 | Kept for one API version |
Webhook event order.returned | Older name of order.cancelled; still delivered to endpoints that subscribe to it, with the same payload and eventLogId. | order.cancelled | 2026-11-13 | Not scheduled |
Money fields named ...Cents (and the bare cents) on success responses and webhook events | Older names of the same values. | The ...Minor name beside each one (unitPriceMinor, totalMinor, amountMinor, ...); see Naming conventions | 2026-11-13 | Not scheduled |
GET /finance/summary reports — totalNetRevenue | The one amount in major units. | totalNetRevenueMinor with currencyExponent | 2026-11-13 | Not scheduled |
GET /transactions and its id, readableId fields | Older name of the key pull list; id is the key pull id, readableId is not an order id. | GET /keys/pulls; keyPullId, transactionId (the sale row), orderReference | 2026-11-13 | Not scheduled |
GET /keys, POST /keys, DELETE /keys/{id}, POST /keys/{id}/rotate, PATCH /keys/{id}/allowed-ips | Older paths of API key management. | The same paths under /api-keys | 2026-11-13 | Not scheduled |
DELETE /orders/hold, POST /orders/commit, POST /orders/{orderId}/extend | Action paths that name their target in the body, or a reservation as orderId. | DELETE /orders/hold/{holdId}, POST /orders/reservations/{reservationId}/commit, POST /orders/reservations/{reservationId}/extend | 2026-11-13 | Not scheduled |
GET /finance/invoices invoiceNumber; invoice.issued / invoice.paid invoiceNumber | One name, two numbers: the platform number on the list, the supplier number (when there is one) on the events. Values unchanged. | platformInvoiceNumber, supplierInvoiceNumber | 2026-11-13 | Not scheduled |
api_key.created / api_key.rotated / api_key.revoked — keyId | keyId names a game key everywhere else. | apiKeyId | 2026-11-13 | Not scheduled |
Error code SRP_MISMATCH_FOR_CURRENCY and details.floorMinor | No longer returned: a country is sold in the one currency it is priced in. Kept in the spec so existing clients keep parsing. | CURRENCY_NOT_PRICED_FOR_COUNTRY | 2026-10-09 | Not scheduled |
GET /products, GET /catalog/checksum — publisherCompanyId query parameter | Older spelling of the vendor filter. Still accepted; a request that uses only it gets X-Avrix-Deprecated-Parameter, and sending both with different values answers 422. | partner | 2026-11-13 | Not scheduled |
POST /keys/return | Takes refunded keys out of circulation without recording a refund or chargeback reference. Still works. | POST /refunds | 2026-11-13 | Not scheduled |
refundPolicy.keyRevealForfeitsRefund on product and allocation reads | Its name reads the opposite of what it means; the value is unchanged. | refundPolicy.revealedKeysRefundable | 2026-11-13 | Not scheduled |
Compatibility Modes#
Per-key compatibility mode is the preferred migration control. Old keys can remain on a previous behavior profile while new keys default to strict commercial metadata and contract authority gates. Compatibility mode must never bypass:
- Authentication, scopes, environment matching, or IP allowlists.
- Contract authority final checks.
- Idempotency for commercial mutations.
- PII redaction.
- Returned-key quarantine.
Webhook Payloads#
Webhook handlers should store and dedupe by eventLogId, the event's own id, the same on every endpoint, retry and replay; eventId identifies one delivery. eventVersion tells handlers which payload schema they received. Webhook deliveries carry no contract date: new events and new optional fields reach them as additive changes, and an endpoint receives only the event names it subscribes to. For that reason a change to when an existing event is sent ships as a new event instead: allocation.running_low (once per crossing of the allocation's own threshold) sits beside allocation.low_stock, which keeps its fixed 10% and its repeats. Webhook delivery is at-least-once and not globally ordered; process events idempotently and reconcile using API reads when a handler was down.
Catalog delta feed (GET /catalog/changes)#
Start from the snapshot's meta.changesCursor and pass it as cursor; since (exclusive
ISO-8601) is still accepted for compatibility. Each row is added, updated, or removed
(tombstone) and carries changedFields[] so you refetch only changed facets. Page with limit
(default 500, max 5000), store meta.nextCursor after every page and poll again while
meta.hasMore is true (Lists and pagination). Pair with
/catalog/snapshot and periodic /catalog/checksum; if checksum drifts or your cursor is older
than the published retention window, cold-start. See
Catalog and allocations.