Changelog

Dated documentation and contract changes for Seller API integrators.

TopicsReference

Every change to the Seller API, and every documentation correction an integrator should know about. The rules the entries follow are on the Versioning and compatibility page, which also lists deprecation and sunset dates; both are kept in step when a field or route is scheduled for removal.

Latest update: the October 2026 update sums up this release: what to check, and what you can now use.

Subscribe: this changelog is also an RSS feed, https://docs.avrix.io/changelog.xml, with one item per dated entry below. Announcements also arrive as the platform.notice webhook event on endpoints that subscribe to it.

How to read an entry. From 2026-11-12 on, every entry heading starts with its type, and every entry ends with who must act:

TypeMeaningCan it affect a running integration?
BreakingAn existing request stops working as it did. Released only behind a contract date, which the heading namesYes, once you pin that date
Changed behaviourAn existing request gets a different status, error code or field. Released only behind a contract date, which the heading namesYes, once you pin that date
DeprecatedStill works, with a replacement and, when scheduled, a sunset dateNot until the sunset
AddedNew operation, field, parameter, event or headerNo
FixedThe API, the reference, an SDK or the Postman collection did not do what the documentation said, and now doesOnly where the entry says
DocumentationA guide said something wrong or unclear; the API did not changeNo

A Fixed entry that corrects the API reference to what the API already did names the corrected operations on a Reference correction line: the API did not change, but a client generated from the earlier reference may have to.


2026-11-13#

Added: sandbox controls that act as the Content Owner#

  • POST /sandbox/allocations/requests/{requestId}/resolve: the sandbox vendor approves or declines your pending allocation request, so allocation.request_decided (and allocation.updated on approval) can be rehearsed. Approvals need your store's isolated sandbox environment and follow the production stock rule; rehearse them on SANDBOX-ALLOC-REQUEST-001.
  • POST /sandbox/allocations/{allocationId}/stock-events: sends allocation.low_stock or allocation.depleted for one of your allocations without selling anything.
  • POST /sandbox/promotions/deals/{responseId}/window: starts or ends a deal now, with promotion.started or promotion.ended for an approved deal. Isolated environments only.
  • POST /sandbox/reset: puts your isolated environment back in a known state (scenarios expired, pending allocation requests cancelled, footprint restored, pools topped up, rehearsal fixtures re-armed). Orders, sold keys, refunds and finance records are kept.
  • All four are sandbox-only: a production key answers 422 SANDBOX_KEY_REQUIRED and nothing is read or changed; a control that would change data every store on the shared sandbox reads answers 422 SANDBOX_ISOLATED_ENVIRONMENT_REQUIRED there. Idempotency-Key is optional.
  • Who must act: nobody. Use them to rehearse vendor-driven flows. See Sandbox.

Added: sandbox rehearsal fixtures#

  • Four magic SKUs: SANDBOX-PROMO-001 (a live deal, an upcoming deal, a pending deal and a pending event share), SANDBOX-REFUND-EXPIRED-001 (refund window of 0 days, so POST /refunds answers 422 REFUND_WINDOW_EXPIRED), SANDBOX-REDEEMED-001 (keys marked redeemed right after delivery, so a refund or return answers 409 KEY_NOT_RETURNABLE) and SANDBOX-ALLOC-REQUEST-001 (an allocation of 5 over 30 keys, so an approved request fits). The whoami response lists them under sandboxCatalog.
  • In isolated environments, one pending access proposal from the sandbox vendor, so GET /access/proposals and the accept and decline calls have data.
  • The sandbox selling footprint and catalog prices are unchanged. An isolated environment built before today lists the new fixtures in POST /sandbox/reset's data.missingFixtures until Avrix repairs it.
  • Who must act: nobody. A test that asserts the exact number of sandbox magic SKUs sees four more.

Added: GET /geo/attest/{attestId} and buyer_verification_required#

  • GET /geo/attest/{attestId} reads where a buyer network confirmation stands (pending, completed, consumed, expired, store_server), for the key that minted it only. No buyer data is returned. Any seller scope.
  • X-Avrix-Sandbox-Simulate: buyer_verification_required (sandbox keys, contract date 2026-12-01) makes a checkout call behave as if the Content Owner required the confirmation, so 422 CONSUMER_GEO_ATTEST_REQUIRED and the attest path can be rehearsed on the hosted sandbox.
  • Who must act: nobody. Stores whose Content Owners require the confirmation can poll the new read instead of waiting a fixed time. See Territory.

Added: notCovered on the sandbox certification report#

  • GET /sandbox/certification returns data.notCovered: the areas the 28 cases do not certify (promotions, finance_statements, key_management, allocation_requests, partner_access), each with the reason and where to rehearse it.
  • Who must act: nobody. Read it before treating a full pass as complete coverage. See Certification.

Changed behaviour (contract date 2026-12-01 only, sandbox keys only): X-Avrix-Sandbox-Simulate refuses a value the operation does not honour, and is honoured on every write#

  • 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, with details.honoured, instead of being ignored.
  • Every write honours rate_limit, internal_error and service_unavailable, answered before any work. This includes POST /orders/cancel, /orders/recover-keys, /keys/export, /keys/return, /refunds and /chargebacks/resolve, which ignored the header.
  • Each operation's X-Avrix-Sandbox-Simulate parameter in the API reference lists exactly the values it honours (SandboxSimulateWrite and SandboxSimulateCheckout are new parameter components).
  • Production keys ignore the header on every date. Earlier contract dates keep what each operation honoured.
  • Who must act: sandbox test suites that pin 2026-12-01 and send the header on every call: send it only on the calls you mean to fail, with a value from details.honoured.

Changed behaviour (contract date 2026-12-01 only, shared sandbox only): footprint and allocation settings are refused there#

  • PUT /me/footprint and PATCH /allocations/{id} with a sandbox key on the shared sandbox answer 422 SANDBOX_ISOLATED_ENVIRONMENT_REQUIRED, because they change what every store on the shared sandbox sees. Nothing is changed.
  • Production keys, isolated sandbox environments and earlier contract dates are unchanged.
  • Who must act: sandbox tests on the shared sandbox that pin 2026-12-01 and set the footprint or an allocation's top-up: run them once your store has its isolated environment.

Fixed: sandbox pre-order deliveries reach only the key that placed the order#

  • On the shared sandbox, the keys and webhooks of a pre-order delivered at release (order.fulfilled, allocation.updated) now go to the endpoints of the API key that placed the pre-order, and the order id they carry is that key's order. A sandbox webhook sent while a request is handled goes to the calling key's endpoints when the event names no key.
  • Production is unchanged.
  • Who must act: nobody.

Documentation: certification case 4 asks for the sellable set#

  • The reason on case 4 of GET /sandbox/certification now says what to show: your sellable set is the catalog joined to allocations with sellable: true, with SANDBOX-NOSHARE-001 left out. It no longer asks you to show allocation-only SKUs. The case is decided as before.
  • Who must act: nobody.

Changed behaviour (contract date 2026-12-01 only): a promotion you can no longer answer answers 409#

  • On contract date 2026-12-01 and later, answering a share or a deal whose state no longer allows it answers 409 CONFLICT with details.reason instead of 400 BAD_REQUEST: SHARE_EXPIRED, PROMOTION_STARTED or RESPONSE_DEADLINE_PASSED (too late; the offer is now expired, named in details.currentStatus) and PROMOTION_WITHDRAWN (the vendor withdrew the deal). GET /promotions/shares/{shareId}/discounts for a share you have not accepted answers 409 CONFLICT with details.reason: NOT_ACCEPTED and details.currentStatus.
  • POST /promotions/deals/{responseId}/respond for a deal offered to another company answers 404 NOT_FOUND, the same as an unknown id, instead of 400.
  • A storage failure on GET /promotions/deals/{responseId}, POST /promotions/deals/{responseId}/respond and GET /promotions/shares/{shareId}/discounts answers 503 SERVICE_UNAVAILABLE or 504 HOT_PATH_TIMEOUT with Retry-After (or a 500 without the database text), like every other read. GET /promotions/summary fails the same way when the deals cannot be read, instead of answering 200 with zero deal counts.
  • Earlier contract dates keep their answers.
  • Who must act: integrations that pin 2026-12-01 and branch on 400 from these operations: treat 409 with details.reason as "the offer's state changed; read it again", and retry 503 and 504 after Retry-After.

Changed behaviour (contract date 2026-12-01 only): an accepted share's discount table is served outside its window#

  • On contract date 2026-12-01 and later, GET /promotions/shares/{shareId}/discounts returns the rows of an accepted share before and after its window too, with meta.active: false. Earlier dates answer an empty data outside the window, as before.
  • Who must act: integrations that pin 2026-12-01 and apply every row they receive: apply the rows only while meta.active is true.

Added: promotion events#

  • Eight webhook events follow a promotion from offer to end: promotion.offered, promotion.changed, promotion.accepted, promotion.declined, promotion.withdrawn, promotion.expired, promotion.started and promotion.ended. Each names the offer by sourceType and sourceId (the share id or the deal response id) and carries its status, window and respondBy. An answer given in the console sends the same event as one given over the API. They are in your event log with resourceType: promotion and in the Event reference.
  • An endpoint receives only the event names in its events, so none of them reaches an existing endpoint until you add it.
  • Who must act: nobody. Subscribe to them to replace polling the promotion lists.

Added: promotion list filters, sort and answer deadlines#

  • GET /promotions/shares and GET /promotions/deals take from and to (offers whose window overlaps), updatedSince (offers that changed since) and sort (-offeredAt, the default and the order they always had, offeredAt, -updatedAt, updatedAt). GET /promotions/shares also takes vendor, and status=vendor_withdrawn.
  • Shares and deals carry respond_by (the last instant an answer is taken: the answer deadline or the start, whichever is earlier) and updated_at. Share and deal products carry price_effect; deal products carry product_id. Discount rows carry skuId and priceEffect. The summary counts expired (shares and deals) and vendor_withdrawn (shares).
  • GET /promotions/calendar takes from, to, skuId, productId, sourceId, vendor and window (live, upcoming, ended), and its entries carry name, vendorCompanyId and productId. Without the new parameters it answers as before.
  • Who must act: nobody.

Added: promotions on catalogue prices#

  • skus[].prices[] on GET /products/{productId} and GET /products/{productId}/pricing carry listPromo, advertisedPriceCents (the list price with the live list-price promotion applied), promo and promoResolution. Each SKU carries promotions: the accepted promotions on it whose window is live or upcoming. basePriceCents is unchanged.
  • Who must act: nobody. Show advertisedPriceCents as the sale price; keep charging what POST /orders/preview quotes.

Fixed: shares a vendor had not sent were visible#

  • GET /promotions/shares, GET /promotions/shares/{shareId} and GET /promotions/summary showed shares a vendor had prepared but not sent yet (status: draft), on every contract date. They are no longer listed, readable or counted.
  • Who must act: nobody. A draft share you stored can be dropped: it reappears as pending, with a promotion.offered event, when the vendor sends it.

Fixed: the reference lists every field the promotion operations return#

  • The promotion responses are named schemas (SellerPromotionShare, SellerPromotionDeal, their detail and product schemas, SellerPromotionShareDiscount, SellerPromotionsSummary) that list every field the API returns, with date-time formats and the status values.
  • The 500 of GET /promotions/deals/{responseId} on earlier contract dates no longer carries the database message.
  • Who must act: nobody. A client generated from the reference gains the fields; no field changed type.

Added: refund ids, and finding a refund by your reference#

  • POST /refunds and POST /keys/return answer with refunds[]: one entry per refunded key sold under the API model, with the refund record id (GET /refunds/{refundId} reads it), keyId and what happened to the key (keyDisposition). Keys sold under other business models have no sale record in Avrix, so they have no refund record.
  • GET /refunds takes refundReference, chargebackReference, status, type and keyId, next to orderReference; the filters combine, and a value outside the documented set answers 422 VALIDATION_FAILED naming the field. Each record also carries refundReference and chargebackReference, the reference you sent split by type (adjustmentReference is unchanged).
  • On GET /orders/{orderId}, each entry of refunds[] carries refundReference and refundIds.
  • Who must act: nobody. Store refunds[].id to read a refund back without listing.

Added: POST /refunds/preview says whether a key can be refunded#

  • Per key: whether POST /refunds would accept it, why not (key_not_found, key_not_returnable, refund_window_expired), the refund window and its end (refundableUntil), what a refund would do to the key and any open dispute freeze. It changes nothing and takes no Idempotency-Key. The rolling refund limit per allocation is not evaluated.
  • Who must act: nobody.

Added: read your dispute freezes#

  • GET /disputes lists your freezes newest first (filters status, disputeReference, keyId) and GET /disputes/{freezeId} reads one, with its keys, its status and how it ended.
  • Who must act: nobody.

Added: return requests to the Content Owner over the API#

  • POST /returns files a return request (refund or replacement, decided by the Content Owner), GET /returns and GET /returns/{returnRequestId} read them with the message thread and the evidence, POST /returns/{returnRequestId}/reply answers the Content Owner's question, POST /returns/{returnRequestId}/evidence attaches a file and POST /returns/{returnRequestId}/cancel withdraws the request. Until now this was possible only in the console. return.information_requested and return.decided report the Content Owner's side.
  • Who must act: nobody.

Added: chargeback.opened, key.replacement_rejected and refund fields on refund.completed#

  • chargeback.opened: POST /refunds recorded a chargeback; report the outcome with POST /chargebacks/resolve.
  • key.replacement_rejected: the Content Owner turned down a key replacement you requested; the original key stays delivered.
  • refund.completed also carries refundReference, chargebackReference, refundIds, keyDisposition and saleTotals.
  • Who must act: nobody. Add the new events to an endpoint's events to receive them.

Changed behaviour (contract date 2026-12-01 only): keyDisposition gives the real outcome#

  • On POST /refunds and POST /keys/return, keyDisposition is quarantined, held (keys sold under revenue share stay with you) or mixed (both in one call). Earlier dates keep answering quarantined whatever happened.
  • Who must act: integrations that pin 2026-12-01 and treat every refunded key as gone: keep held keys in your records, and read refunds[].keyDisposition on mixed.

Changed behaviour (contract date 2026-12-01 only): a partial refund leaves the order fulfilled#

  • On 2026-12-01 and later, an order's status follows its keys after POST /refunds: it reads refunded once every key is refunded and stays fulfilled after a partial refund. Earlier dates mark the orderReference you send as refunded as soon as one key is refunded.
  • Who must act: integrations that pin 2026-12-01 and read refunded on GET /orders as "a refund happened": read refunds[] on the order instead.

Changed behaviour (contract date 2026-12-01 only): POST /keys/return ends dispute freezes#

  • On 2026-12-01 and later, POST /keys/return ends any dispute freeze on its keys, as POST /refunds always did (key.unfrozen, resolution refunded). Earlier dates leave the freeze open until it is released or expires.
  • Who must act: nobody, unless you release freezes yourself after POST /keys/return: that call then answers that the freeze already ended.

Changed behaviour (contract date 2026-12-01 only): direct pulls and exports bind the previewed price#

  • POST /keys/pull reads priceCommitmentToken, and POST /keys/export reads priceCommitmentToken, expectedUnitPriceCents and expectedWholesaleUnitPriceCents, with the rules of POST /orders: the token must be yours and for this SKU (422 PRICE_COMMITMENT_INVALID or PRICE_COMMITMENT_EXPIRED), an echoed price must equal the token's, and the token's price and country bind the sale. Earlier dates accept the fields and ignore them, so an export from an API allocation on a production key keeps answering 422 EXPECTED_UNIT_PRICE_REQUIRED there.
  • Who must act: integrations that pin 2026-12-01 and send these fields on a pull or export: send a current token, or drop the field.

Deprecated: POST /keys/return#

  • POST /refunds is the one call for every refund and chargeback. It does what POST /keys/return does and also records your refund or chargeback reference, so the refund can be found again with GET /refunds?refundReference=. POST /keys/return keeps working unchanged and is marked deprecated in the API reference. No sunset date is set, and no response carries a Deprecation header until one is announced here.
  • Who must act: integrations that call POST /keys/return: move to POST /refunds with type: "refund" and your refundReference. Nothing breaks if you do not.

Deprecated: refundPolicy.keyRevealForfeitsRefund#

  • Read refundPolicy.revealedKeysRefundable instead. The old name suggests a revealed key cannot be refunded, which is not the rule: a delivered key can be refunded within the refund window. The old field keeps its value. No sunset date is set.
  • Who must act: integrations that read keyRevealForfeitsRefund: read revealedKeysRefundable.

Fixed: POST /keys/pull declares immediateFulfilment#

  • The API always accepted immediateFulfilment on POST /keys/pull, as on POST /orders; the reference now declares it. Reference correction: POST /keys/pull.
  • Who must act: nobody.

Documentation: one refunds guide, with a call for each case#

  • Refunds and key returns now opens with which call to use in each case, shows a refund per business model, and documents the chargeback states, dispute freezes and return requests. Its POST /refunds sample lacked type and refundReference, both required; it has them now. It no longer says pending is a refund status you will see: no refund is recorded in that state today.
  • POST /keys/return is documented as the call kept for existing integrations; POST /refunds is the one to use. Nothing about POST /keys/return changes or is removed.
  • The RefundPolicy description no longer says Content Owners cannot set a refund window: they can, per product or per SKU. The 409 of POST /chargebacks/resolve documents details.currentState.
  • Who must act: nobody.

Changed behaviour (contract date 2026-12-01 only): GET /events serves your event log#

  • On contract date 2026-12-01 and later, GET /events lists your events, one row per event, whether or not any webhook endpoint subscribes to it, kept 30 days. Each row has id (the same value as eventLogId), eventType, eventVersion, occurredAt, createdAt, resourceType, resourceId and payload (the event's own fields, as a webhook delivery carries them). New filters narrow it: eventType (one or more event names, at most 20; an unknown name answers 422 VALIDATION_FAILED), resourceType and resourceId. Paging, cursor, since, meta.nextCursor and meta.headCursor work as before. The feed reads a few seconds behind the present so a forward cursor never passes an event recorded a moment earlier.
  • Earlier dates keep the delivery rows (endpointId, status, attempts, ...), one per delivery to each endpoint and nothing when you have none. The new filters are not read there: they are refused with 422 VALIDATION_FAILED naming them, as before they existed.
  • Who must act: integrations that pin 2026-12-01 and read delivery fields (endpointId, status, attempts, responseStatus) from GET /events: read delivery status from GET /webhooks/{id}/deliveries instead. A store with no webhook endpoint can now follow its events from GET /events alone.

Added: one id per event on every webhook delivery, and a delivery id header#

  • Every webhook delivery carries eventLogId in the body and the X-Avrix-Event-Log-Id header: the event's own id, the same on every endpoint that receives it, on retries and on replays, and the id of the event in GET /events. Deduplicate on it.
  • eventId and X-Avrix-Event-Id keep their meaning: the id of one delivery.
  • Every delivery also carries X-Avrix-Delivery-Id, the delivery row as GET /webhooks/{id}/deliveries lists it.
  • Test deliveries, and deliveries created before this release, carry no eventLogId.
  • Who must act: nobody. Deduplicate on eventLogId ?? replay?.originalEventId ?? eventId so one event reaching two endpoints, or replayed, is applied once.

Added: 17 webhook events for changes that had none#

  • Orders: order.cancelled. Allocations: allocation.request_decided. Catalog: product.added. Agreements: contract.expiring, contract.expired, contract.terminated. Connections: connection.suspended, connection.reactivated, connection.ended, access.proposal_created. Key returns: return.decided, return.information_requested. Monthly invoices: invoice.issued, invoice.paid. API keys: api_key.created, api_key.rotated, api_key.revoked. Each has a section in the Event reference and a payload schema in the OpenAPI webhooks section.
  • An endpoint receives only the event names in its events, so none of them reaches an existing endpoint until you add it. All of them are in your event log either way.
  • product.added is recorded in the same database transaction as the catalog change that causes it. The others are recorded right after their change commits.
  • Who must act: nobody. Add the events you handle with PATCH /webhooks/{id}.

Added: sku.sellability_changed for a SKU's first appearance#

  • A SKU that appears for your company for the first time and is sellable now sends sku.sellability_changed with sellable: true and the new field firstSeen: true. Flips between sellable and not sellable carry firstSeen: false. The first time Avrix observes your catalog it records every SKU without sending events, as before.
  • Who must act: endpoints subscribed to sku.sellability_changed whose handler looks the SKU up locally: a firstSeen: true event can name a SKU you do not have yet; read it with GET /allocations.

Deprecated: order.returned, an older name of order.cancelled#

  • order.returned is sent for a cancellation before delivery (POST /orders/cancel), not for a return of delivered keys (order.keys_returned). order.cancelled now names that change. Endpoints subscribed to order.returned keep receiving it, with the same payload and the same eventLogId as the order.cancelled delivery of the same cancellation. The event log records the cancellation once, as order.cancelled. No sunset date is set.
  • Who must act: nobody yet. Subscribe to order.cancelled and then remove order.returned from the endpoint, or deduplicate the two on eventLogId.

Fixed: the sandbox chargeback.resolved test event sends resolved as an integer#

  • POST /webhooks/{id}/test with eventType: chargeback.resolved sent resolved: true; the live event sends the number of sale lines resolved. The test event now sends an integer too. The schema still accepts both types.
  • Who must act: nobody, unless a handler was written against the test event: read resolved as a number.

Fixed: the webhook helper package states the 8-second delivery timeout#

  • The comments of @avrix/seller-api-helpers createWebhookConsumer said deliveries time out after 30 seconds. They time out after 8 seconds, as Webhooks says.
  • Who must act: handlers built to the 30-second figure: return 2xx within 8 seconds and do the work afterwards.

Documentation: order lifecycle transitions and event examples#

  • Order lifecycle said POST /orders/reserve sends order.reserved (it sends no event: the response is the answer), that a commit rejection sends order.failed (it answers an HTTP error; order.failed is sent only when an automatic pre-order fulfilment could not deliver keys), and drew a cancel from reserved (a hot-drop reservation expires at its TTL; POST /orders/cancel does not apply to it).
  • Every example in the Event reference now shows the full delivery body, envelope included.
  • Who must act: nobody.

Added: GET /usage counts the whole window, with breakdowns per route, status and code, day and key#

  • GET /usage now counts in the database, so totalRequests, totalErrors and totalLookupMisses cover the whole window however busy it was. Before, one response stopped at 50,000 requests.
  • New fields: byRoute (method and route template, ids as {id}), byStatus (HTTP status and error code), byDay (UTC day) and byKey (API key), all complete; maxEndpointBuckets; and keyId. A new optional query parameter, keyId, counts one of your keys only.
  • The call log behind GET /usage and GET /requests/{requestId} now stores the error code of every error response (VALIDATION_FAILED, RATE_LIMIT_EXCEEDED, ...). Responses recorded before this release report HTTP_<status>.
  • byEndpoint is unchanged and lists at most maxEndpointBuckets (50,000) entries, largest first; truncated now says only that it left some out.
  • Who must act: nobody. Dashboards that split a window to stay under 50,000 requests can stop doing so.

Deprecated: maxCountedRequests on GET /usage#

  • The totals are no longer capped, so maxCountedRequests has no meaning left. It stays in the response with its old value, 50,000. No sunset date is scheduled.
  • Who must act: nobody now. Read truncated and maxEndpointBuckets instead.

Added: GET /requests/{requestId} finds every request made with your keys#

  • The inspector now also reads the per-request call log, which is never sampled: callLog gives the method, endpoint, status, latency, error code and key of each response with that id, and coverage says what was found (detailed, summary or none). Before, most successful requests came back empty because only the sampled audit log was read.
  • Who must act: nobody.

Changed behaviour (contract date 2026-12-01 only): GET /requests/{requestId} answers 404 for an id nothing recorded#

  • On contract date 2026-12-01 and later, an id with no call-log row, no trace and no webhook delivery in the last 90 days answers 404 NOT_FOUND with details.lookupRequestId and details.retentionDays. Earlier dates answer 200 with coverage: "none" and empty lists.
  • Who must act: integrations that pin 2026-12-01 and treat the empty 200 as "no trace kept": handle the 404.

Added: X-RateLimit-Bucket and the key's rate limits on GET /whoami#

  • Every response counted against a rate limit names the bucket its X-RateLimit-* numbers belong to, as <class>:<kind> (orders:write, catalog:read-cached, catalog:snapshot), in the new X-RateLimit-Bucket header. A 429 from the limiter repeats it in details.rateLimitBucket, with details.limit and details.retryAfterSeconds.
  • GET /whoami returns data.key.rateLimits: every bucket of the calling key with its limit and window, and any orders-class launch limit set for the key.
  • The API reference states each operation's class in x-avrix-rate-limit-class. It corrects x-avrix-tier, which said catalog for operations counted in orders and finance for one counted in general.
  • Reference correction: GET /transactions, GET /allocations/requests, POST /allocations/requests and GET /activity are counted in orders, and GET /finance/statements in general; their x-avrix-tier now says so. The API did not change.
  • Who must act: nobody. Pace from X-RateLimit-Bucket if one job calls routes of several classes.

Changed behaviour (contract date 2026-12-01 only): API-key management is counted in general#

  • On contract date 2026-12-01 and later, GET and POST /keys, DELETE /keys/{id}, POST /keys/{id}/rotate and PATCH /keys/{id}/allowed-ips are counted in the general rate-limit class, so they report its numbers and no longer spend the checkout budget. Earlier dates keep counting them in orders.
  • Who must act: integrations that pin 2026-12-01 and pace key management from the orders numbers: read X-RateLimit-Bucket.

Changed behaviour (contract date 2026-12-01 only): X-Request-Id has one format#

  • On contract date 2026-12-01 and later, an X-Request-Id request header that is not 8 to 128 characters from A-Z, a-z, 0-9, _, ., : and - is refused with 400 INVALID_REQUEST_ID before anything runs. Every id in that format can be looked up with GET /requests/{requestId}. Earlier dates echo any value, as before.
  • Who must act: integrations that pin 2026-12-01 and send their own ids: send a UUID, a ULID or another id in the format, or omit the header.

Changed behaviour (contract date 2026-12-01 only): catalog read failures answer like every other route#

  • On contract date 2026-12-01 and later, a database timeout on GET /products/{productId}, GET /products/{productId}/pricing or GET /catalog/snapshot answers 504 HOT_PATH_TIMEOUT, an unavailable dependency 503 SERVICE_UNAVAILABLE, both with Retry-After, and any other failure 500 INTERNAL_ERROR with a generic message. Earlier dates keep 500 INTERNAL_ERROR; there, a message that would show database internals is replaced by Internal Server Error.
  • Audit rows of product detail and pricing now carry the request id the response carries, the key and the response time, and the snapshot logs the status it sent.
  • Who must act: integrations that pin 2026-12-01: retry 503 and 504 after Retry-After.

Changed behaviour (contract date 2026-12-01 only): five unversioned paths redirect to /v1/#

  • /api/seller/access/*, /api/seller/chargebacks/*, /api/seller/disputes/*, /api/seller/geo/* and /api/seller/me/* were served in place while every other unversioned path redirects to /v1/. For requests that send X-Avrix-Api-Version: 2026-12-01 (or next) they now redirect too (307, method and body kept). Other requests are served in place.
  • Who must act: integrations that pin 2026-12-01 and call these paths without /v1/ from a client that does not follow redirects: call the /v1/ paths.

Fixed: standard headers on the buyer-browser geo confirmation calls#

  • POST /geo/attest/{attestId}/complete and GET /geo/attest/{attestId}/pixel now send X-Request-Id (equal to the body's requestId), X-Avrix-Api-Version, X-Api-Version and Cache-Control: no-store, and the JSON call sends Retry-After on 429, 503 and 504.
  • Who must act: nobody.

Fixed: a per-minute limit allows exactly that many requests#

  • The in-process limiter behind the buyer-browser geo confirmation (30 completions a minute per address) and the sandbox limits when their shared store is unreachable refused the request that reached the limit, so a limit of 30 allowed 29. It now allows 30.
  • Who must act: nobody.

Fixed: GET /whoami errors use the shared error body#

  • The two 500 answers of GET /whoami were built by hand; they now carry the same fields as every other error body. The code and message are unchanged.
  • Who must act: nobody.
  • Its quickstart link pointed into a private repository; it now points to https://docs.avrix.io/seller-api/quickstart.
  • Who must act: nobody.

Changed behaviour (contract date 2026-12-01 only): pricing says whether an order there would be accepted#

  • On contract date 2026-12-01 and later, sellable and blockedReason on every price of GET /products/{productId}/pricing are the order path's answer for that SKU in that country, the same POST /orders/preview, POST /orders and GET /availability?countryCode= give: your footprint, the currencies and territory your agreement grants, the SKU's territory and region locks, the catalog price and the priced currency, in that order. blockedReason can be any of FOOTPRINT_COUNTRY_NOT_DECLARED, FOOTPRINT_CURRENCY_NOT_DECLARED, CURRENCY_NOT_PERMITTED_BY_TERM, TERRITORY_NOT_GRANTED, REGION_LOCKED_FOR_CONTRACT, COUNTRY_RESTRICTED, TERRITORY_NOT_ALLOWED_FOR_SKU, TERRITORY_EXCLUDED_FOR_RELEASE, REGION_LOCKED_FOR_SKU, SKU_REGION_UNRESOLVED, CATALOG_PRICE_NOT_SET, CURRENCY_NOT_PRICED_FOR_COUNTRY and SRP_MISMATCH_FOR_CURRENCY.
  • Earlier dates keep the currency-only answer: a priced country outside your footprint still reads sellable: true there, and an order in it is refused.
  • Whether you hold an allocation for the SKU is not part of the answer; GET /allocations says so.
  • Who must act: integrations that pin 2026-12-01 and show every price with sellable: true as purchasable: expect more false values, and hide those countries or show blockedReason.

Changed behaviour (contract date 2026-12-01 only): the media download answers like every other route and says when the archive is incomplete#

  • On contract date 2026-12-01 and later, GET and HEAD /products/{productId}/media/download:
    • answer errors on the standard error body, with timestamp and requestId, instead of the short { code, message, requestId };
    • answer 404 PRODUCT_NOT_SHARED for a product that exists but is not shared with you (NOT_FOUND before), as product detail does;
    • answer the Seller API 401 (with X-Request-Id and an error body) to a request without an API key, on GET and on HEAD;
    • end the archive with avrix-media-manifest.json, { "complete", "entries": [{ "filename", "included" }] }. A file that cannot be read from storage is left out after the 200 has been sent; complete: false says so. That archive has its own ETag.
  • Earlier dates keep the short body, NOT_FOUND, the bare 401 on HEAD and the archive without a manifest.
  • Who must act: integrations that pin 2026-12-01 and parse media errors: read code from the standard body, and treat PRODUCT_NOT_SHARED as "remove from your listing". Read complete in the manifest before trusting an archive; skip the manifest entry when you unpack it.

Changed behaviour (contract date 2026-12-01 only): a catalog export request body is validated#

  • On contract date 2026-12-01 and later, POST /catalog/exports refuses a body that is not valid JSON, is not an object, has a key other than pricing, or has a pricing other than "territory", with 422 VALIDATION_FAILED. An empty body is accepted as before.
  • Earlier dates ignore a body they cannot use, as they ignored every body before, and build the export without territory prices.
  • Who must act: integrations that pin 2026-12-01 and send a body with POST /catalog/exports: send {} or { "pricing": "territory" }, or no body.

Added: territory prices in catalog exports#

  • POST /catalog/exports takes an optional body { "pricing": "territory" }, on every contract date. The export then carries territoryPrices on every shared SKU, as GET /catalog/snapshot?pricing=territory does, and GET /catalog/exports/{exportId} reports pricing: "territory" (null otherwise). An export with territory prices and one without are separate exports.
  • Who must act: nobody. A large store can now cold-start with prices from one export instead of one pricing call per product.

Added: catalog filters, sort and external-reference lookup#

  • GET /products takes platform, externalReference (with externalReferenceSource), releaseDateFrom, releaseDateTo, launchPhase, tradingState, productType and sort (-createdAt, the default and the order the list always had, createdAt, -updatedAt, updatedAt, name, -name), on every contract date. meta.total counts the filtered list. A cursor belongs to the sort it was issued with; sent with another sort it answers 422. Without the new parameters the list is served as before.
  • GET /products/lookup?externalReference= maps up to 100 Steam app ids, Steam package ids or platform product ids to products in one call: one row per value, in the order sent, with the product, SKU and reference that matched, and meta.requested, matched and unmatched.
  • Who must act: nobody.

Added: lighter product detail and credits#

  • GET /products/{productId}?omit= leaves out assets, eula, localizedDescriptions, systemRequirements, relatedProducts or releasePricing (the deprecated release-level pricing[]). Without it the body is unchanged.
  • Product detail carries developer and creditedPublisher, the studio and publisher the store page credits; null when not set.
  • Who must act: nobody. A store that syncs prices or stock can send omit=assets,eula,localizedDescriptions to cut most of the body.

Added: currency digits for the suggested retail price, and facets on product.updated#

  • Catalog sharedSkus[] carry srpCurrencyExponent beside srpPriceCents and srpCurrencyCode, as every other money field has its exponent; null when there is no SRP.
  • product.updated carries changedFields (the GET /catalog/changes vocabulary, once each) when the change that sent it names what changed. It is absent otherwise.
  • Who must act: nobody. Divide srpPriceCents by 10^srpCurrencyExponent, not by 100; on product.updated, refetch only the facets named, or the whole product when the field is absent.

Added: an ETag on product pricing, and the file count on the media download#

  • GET /products/{productId}/pricing sends a weak ETag on every contract date. Send it back as If-None-Match to get 304 Not Modified without a body or a read budget charge.
  • GET and HEAD /products/{productId}/media/download send X-Avrix-Media-Entries, the number of files the archive is built from, on 200 and 304, on every contract date. The archive is streamed file by file instead of being built in memory first.
  • Who must act: nobody.

Deprecated: publisherCompanyId on GET /products and GET /catalog/checksum#

  • publisherCompanyId is the older spelling of partner on these two operations. It keeps working, with no sunset date; a request that uses only it gets an X-Avrix-Deprecated-Parameter header naming partner. Sending both with different values answers 422, as before.
  • Who must act: nobody now. Send partner when you next touch the call.

Fixed: the media download sends its rate-limit headers, and the reference declares its HEAD and ETag#

  • The reference declared X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset on the media download, and the route did not send them. It sends them now on 200, 304 and HEAD, on every contract date.
  • Reference correction: headProductMedia (HEAD /products/{productId}/media/download) was served and described in prose but had no operation in the reference, so no SDK could call it; it is declared now. downloadProductMedia declares the ETag header it already sent.
  • Who must act: nobody. A client generated from the reference gains headProductMedia.

Fixed: the reference names the pricing country of list prices#

  • Reference correction: listProducts and PartnerProduct.listPriceFromCents said the list price was the US price. It is the price in your pricing country: the country of your company's default currency, or the United States when none is set. The API did not change.
  • Who must act: if you read listPriceFromCents as a US price, read listPriceCurrencyCode with it.

Documentation: catalog guide corrections#

  • Catalog and allocations:
    • Pricing said your cost under the API model is the territory list price. The sale is booked at that price; what you owe is the Content Owner's share of it, net of the VAT you declare. The share is a term of your agreement, fixed on each sale at commit, which is why no catalog field carries it.
    • Launch phases listed discontinued as a launch phase and said a pre_order product cannot be ordered. discontinued is a tradingState; a pre_order product is orderable on the pre-order path, which the section now describes.
    • A new section, Regions, platforms and countries, lists the region and platform codes and says to key on countries.
    • A guide to which price field to read, and the filters, lookup and media notes.
  • Caching and fairness said every catalog route sends an ETag and that a 304 costs no database work. It lists the routes that send one; a 304 saves your rate budget and the transfer, while the server still assembles the response to compare.
  • The Integration tutorial uses one scenario throughout (a buyer in the Netherlands paying EUR 79.99), and the Product field matrix documents the media archive and marks the detail fields the reference declares.
  • The Error reference documents PRODUCT_NOT_SHARED, which product detail already answered; its errors now carry hint, recoverable and doc_url, like every other code.
  • Who must act: integrations that computed their cost under the API model as the full list price: read the split from economics on GET /orders or from GET /finance/api-sales.

Added: invoice detail, invoice document, payments and monthly reports#

  • GET /finance/invoices/{invoiceId} returns one invoice you owe: its lines (one per balance movement it bills, with the report and month), its payment, every payment record, disputes, history and the document. GET /finance/invoices/{invoiceId}/document returns a five-minute download link for the invoice PDF.
  • GET /finance/payments lists your payment of each invoice: amount, method, the reference your transfer must carry, state and settlement date. Filters: paymentState, invoiceId, publisherCompanyId, settledFrom, settledTo.
  • GET /finance/reports, GET /finance/reports/{reportId} and GET /finance/reports/{reportId}/lines return the monthly sales reports: totals in minor units, the exchange rates each report froze (fx), attested rates, confirmation (state, who acts next, deadline) and the lines. Confirming a report stays in the console.
  • GET /finance/invoices gains the fields that tell one invoice from another (kind, publisherCompanyId, supplierInvoiceNumber, reportMonth, subtotalCents, taxCents, paidCents, outstandingCents, paymentTermsDays, paymentState, replacesInvoiceId, supersededByInvoiceId, updatedAt, reconciliationAvailable, reconciliationPath, detailPath) and the filters status, kind, invoiceType, publisherCompanyId, reportMonth, issuedFrom, issuedTo and updatedSince. Without a filter it answers exactly as before.
  • GET /finance/summary gains currentPeriod.activityTotals: the running month's sales per vendor and currency, the same figures as meta.balances on GET /finance/ledger for that period.
  • The statement CSV (GET /finance/statements?format=csv) gains currencyExponent and the key, report and settlement columns the api-sales CSV has, after its first twelve columns. The reconciliation CSV gains paymentCurrencyExponent and saleCurrencyExponent as its last two columns. The GET /finance/api-sales reference now declares its text/csv response.
  • Finance and settlement walks one month from sale to payout, lists the invoice states and says which endpoint answers which question.
  • Who must act: nobody. A CSV reader that maps columns by name, not position, sees the new columns at the end.

Added: invoice.overdue, invoice.disputed and invoice.dispute_updated#

  • invoice.overdue fires once when a monthly invoice passes its dueAt unpaid; it stays payable. invoice.disputed fires when you dispute an invoice in the console, and invoice.dispute_updated when the vendor answers or you withdraw it (outcome: accepted, rejected, withdrawn or escalated). All three carry the fields of invoice.issued, and appear in the event log on GET /events.
  • invoice.issued and invoice.paid carry replacesInvoiceId when the invoice corrects an earlier one.
  • Who must act: nobody. Subscribe an endpoint to the new events to receive them; existing subscriptions do not change.

Changed behaviour (contract date 2026-12-01 only): finance statement and reconciliation refusals#

  • GET /finance/statements refuses an unknown format with 422 VALIDATION_FAILED naming format (earlier dates serve JSON), names limit in the 422 for a bad limit, and answers an infrastructure failure with 503 or 504 and Retry-After instead of 500.
  • GET /finance/invoices/{invoiceId}/reconciliation for an invoice you owe that has no settlement answers 409 CONFLICT with details.reason: RECONCILIATION_NOT_AVAILABLE and details.invoicePath, instead of 404. An invoice that is not yours still answers 404.
  • Who must act: integrations that pin 2026-12-01 and send a format other than json or csv to the statement, or treat the reconciliation 404 as "not yet": check reconciliationAvailable on the invoice before asking, and retry a 503 after Retry-After.

Changed behaviour (contract date 2026-12-01 only): PUT /me/footprint checks its codes and answers with what it stored#

  • On contract date 2026-12-01 and later, PUT /me/footprint answers with the footprint as stored, duplicates removed and sorted, which is what GET /me/footprint returns next, and refuses a code that names no country or no current ISO 4217 currency (for example ZZ or XXQ) with 422 VALIDATION_FAILED, details.issues[].field naming its position (countries.1). Earlier dates echo the lists the request sent and store any two- or three-letter code.
  • The reference now states the limits the API always applied: at most 300 countries and 200 currencies, two and three letters.
  • Who must act: integrations that pin 2026-12-01: compare the answer to the request as sets, and send only real country and currency codes.

Fixed: a statement failure no longer returns the database message#

  • A 500 from GET /finance/statements carried the underlying database error text. It now carries the same generic message as every other finance route, on every contract date.
  • Who must act: nobody.

Fixed: an allocation request is decided from the Content Owner's stock count, never from the request#

  • POST /allocations/requests took publisherAvailableKeys from the request body as the Content Owner's free stock when their rules decide a request automatically. A request could change its own outcome: 0 sent a request the rules grant at once into manual review, and a large number let an automatic grant reach past the free stock. The decision now always uses the count Avrix holds, on every contract date. This is a security fix, so it is not behind a contract date.
  • The field is still accepted and validated (a negative or non-integer value is refused with 422 as before), and ignored. The reference marks it so.
  • Who must act: nobody. A store that sent the field gets the outcome the Content Owner's rules give; drop the field when convenient.

Added: the allocation request as a resource#

  • GET /allocations/requests/{id} reads one request you filed. POST /allocations/requests/{id}/cancel withdraws a pending one (no body; Idempotency-Key optional; cancelling it again answers the same 200; a request the Content Owner already decided answers 409 CONFLICT with details.reason: ALLOCATION_REQUEST_ALREADY_RESOLVED and details.state). There is no amend: cancel and file a new request. Cancelling in the console works the same way.
  • Every request row gains state (pending, auto_granted, approved, denied, backordered, cancelled: one field for where it stands), allocationId (the same value as allocationGrantId), skuCode and updatedAt. Existing fields are unchanged.
  • GET /allocations/requests follows the list contract: limit (1 to 100, default 100, the page size it always had), cursor, meta with nextCursor, hasMore and count, and the filters state (comma-separated) and allocationId.
  • POST /allocations/requests accepts allocationId, the name every other surface uses for the allocation; grantId stays accepted (send one, or both with the same value). Its answer adds allocationId and state, and a second request on an allocation that already has a pending one names it in details.pendingRequestId.
  • New webhook event allocation.request_cancelled. allocation.request_decided is now also sent when a Content Owner's ceiling increase approves a pending request.
  • Who must act: nobody. Stores that kept their own copy of request status can read it instead, and subscribe to allocation.request_decided and allocation.request_cancelled.

Added: GET /allocations/{id}#

  • Reads one of your allocations: the row GET /allocations returns, whatever its status, so an allocation a webhook names can be read even when it is paused or revoked. 404 when the id is not one of yours.
  • Who must act: nobody.

Added: allocation.running_low, sent once per crossing of your own threshold#

  • Sent when an allocation's remaining falls to or below its low-stock threshold: your replenishThreshold (PATCH /allocations/{id}) when you set one, otherwise 10% of quantityLimit, rounded down. It carries threshold and thresholdSource. It is sent again only after remaining has risen above the threshold and fallen to it again.
  • allocation.low_stock is unchanged: a fixed 10%, sent with every allocation update while the allocation stays there. Its deliveries now state that number in threshold. Webhook deliveries carry no contract date, so its timing was not changed; allocation.running_low is the event with one meaning and one delivery per crossing.
  • Who must act: nobody. Stores that page someone on low stock should subscribe to allocation.running_low instead of allocation.low_stock.

Added: PATCH /allocations/{id} says what your top-up trigger will do#

  • The answer adds rules (the Content Owner's top-up rules, as GET /allocations/{id}/replenishments shows them) and effective: whether a crossing tops the allocation up at once (automatic), files a request for the Content Owner (request) or does nothing (off), with the quantity and what limited it. GET /allocations/{id}/replenishments adds effective too.
  • Who must act: nobody.

Changed behaviour (contract date 2026-12-01 only): allocation request create and revoked allocations#

  • POST /allocations/requests answers 201 Created instead of 200 OK for a request it files or grants at once. The body is the same.
  • PATCH /allocations/{id} on a revoked allocation answers 409 CONFLICT (details.reason: allocation_revoked) instead of saving a trigger that can never fire.
  • Earlier dates and unpinned requests are unchanged.
  • Who must act: integrations that pin 2026-12-01 and test for exactly 200 on the create: accept any 2xx.

Added: GET /orders/hold/{holdId}#

  • Reads a checkout hold created with the same API key: what it holds, until when, and the price it bound. Once the hold is no longer live it answers 404 HOLD_NOT_FOUND with details.holdState (released, consumed or not_found); 503 STORE_UNAVAILABLE when the hold store cannot be read.
  • Who must act: nobody.

Fixed: failed allocation reads answer 5xx, never 404 or an empty history#

  • GET /allocations/{id}/replenishments answered 404 or an empty history when a database read failed, and PATCH /allocations/{id} returned the database's own message in a 500. Both now answer 500, 503 or 504 like every other read, with Retry-After on 503 and 504. GET /availability/changes gives its 500 the same envelope and Retry-After handling. The replenishment history also sends the rate-limit headers.
  • Who must act: nobody. A client that deleted its copy of an allocation on a 404 during an outage no longer sees one.

Fixed: the allocation and checkout hold reference#

  • Reference correction: GET /allocations/requests and POST /allocations/requests declare their 200 bodies; the create's 409 lists every details.reason; publisherAvailableKeys is described as ignored; POST /orders/hold describes holdId, expiresAt, expiresInSeconds, allocationId, maxFulfillableQuantity, currencyCode, salesCountryCode and priceBoundAt; allocation.low_stock is described as it works.
  • Who must act: clients generated from the earlier reference may regenerate to get typed request rows.

Documentation: stock, reservations and checkout holds#

  • New page Stock and reservations: the three ways to set keys aside (a checkout hold, a launch reservation, an allocation), the stock numbers each answer shows, and the low-stock events side by side.
  • Checkout holds: the create sample is under its own heading and no longer followed by a stray command without countryCode; the hold lifetime is stated as it is (30 minutes by default, a platform setting, not chosen per request and not extendable).
  • The Integration tutorial delta loop uses cursor, not since.
  • Who must act: nobody.

Changed behaviour (contract date 2026-12-01 only): POST /oauth/token answers JSON errors with RFC 6749 codes#

  • On contract date 2026-12-01 and later, a JSON token request that fails carries the RFC 6749 error code in error (invalid_client, invalid_request, unsupported_grant_type, unauthorized_client, temporarily_unavailable, server_error) instead of the message. The status codes and code do not change; the message is in message and error_description.
  • On the same date a JSON request that sends the client credentials both ways, in the body and with HTTP Basic, is refused with 422 VALIDATION_FAILED (error: invalid_request). Earlier dates read the body as always and ignore the Authorization header.
  • Form-encoded requests, new in this release, behave this way on every date.
  • Who must act: integrations that pin 2026-12-01, call the token endpoint with JSON and read the error text from error: read message or error_description. Clients that send Authorization: Basic next to a JSON body with client_secret: send one of them.

Added: the standard OAuth 2.0 client-credentials call on POST /oauth/token#

  • The token endpoint accepts a form-encoded body (application/x-www-form-urlencoded) and client credentials in an Authorization: Basic header, as OAuth 2.0 client libraries send them. The JSON call with the credentials in the body works as before, on every date.
  • The response adds scope (the key's scopes, which the token carries exactly) and the header Pragma: no-cache. A requested scope is ignored.
  • Every error adds error_description. A refused HTTP Basic client gets WWW-Authenticate: Basic.
  • The endpoint is also served at /api/seller/v1/oauth/token, under the same versioned prefix as every other route.
  • OAuth tokens now opens with the ways the endpoint differs from a stock OAuth server.
  • Who must act: nobody.

Added: scoped keys and expiry on POST /keys, and a readable key inventory#

  • POST /keys takes scopes: the new key gets exactly those, each of which the calling key must hold. One it lacks is refused with 403 INSUFFICIENT_SCOPE naming it in details.missingScopes, and no key is created. Without scopes the default set applies as before. Keys wider than the calling key are still created in the console.
  • POST /keys takes expiresAt: at least a minute ahead (422 otherwise) and no later than the calling key's expiry (403 otherwise). Without it the new key inherits the calling key's expiry, as before. The response repeats scopes and expiresAt.
  • New scope seller:keys:read: lists keys (GET /keys) without being able to create, rotate or revoke them. seller:keys:write still lists them. On contract date 2026-12-01 a key holding neither gets INSUFFICIENT_SCOPE with both in details.requiredScopes.
  • GET /keys rows add scopes, environment and allowedIps, beside createdAt, lastUsedAt and expiresAt.
  • Who must act: nobody. To audit keys from a monitoring job, give it a seller:keys:read key.

Added: api_key.expiring and api_key.expired#

  • api_key.expiring is sent once, 14 days before a key's expiry, for keys meant to live longer than that; api_key.expired once the expiry passes. Neither is sent for a revoked key. Both carry keyId, keyName, environment and expiresAt, never the secret. See the Event reference.
  • No event is sent for a key that had already expired before this release.
  • Who must act: nobody. Subscribe an endpoint to both if your keys have an expiry.

Added: production access state on GET /whoami#

  • GET /whoami returns productionAccess: status (not_requested, requested, approved), requestedAt, approvedAt, whether the deployment enforces approval, and the three steps (api_model_activated, production_key_created, production_access_approved) with whether each is done. Read it with a sandbox key while production keys are refused.
  • 403 PRODUCTION_ACCESS_NOT_APPROVED adds details.productionAccess with status and requestedAt: the refused call has recorded the request.
  • Who must act: nobody.

Fixed: the OAuth token limiter admitted one request fewer than its limit#

  • When the shared rate-limit store was unavailable, the fallback limiter on POST /oauth/token refused the tenth token request per client per minute and the twentieth per source address, one below the published limits. It now admits the full limit.
  • Who must act: nobody.

Fixed: the token response is described in the API reference#

  • The POST /oauth/token success body was declared as a free-form object; the reference now declares access_token, token_type, expires_in, scope and meta, and the form-encoded request body. Reference correction: tokenOauth.
  • Who must act: clients generated from the reference get typed fields after regenerating.

Documentation: first-call guides agree with the API#

  • The GET /whoami example in Authentication shows the shape the API returns (company, data.key.environment, data.key.scopes, requestEnvironment), as the Quickstart and the API reference do. Environments and Go live read data.key.environment.
  • KEY_ENVIRONMENT_MISMATCH is explained by its two real causes: a production key sent with X-Avrix-Sandbox: true, or a sandbox key on a deployment where the sandbox is disabled.
  • What sandbox and production keys must declare on an order is one table in Sandbox; the Quickstart and Sandbox to production no longer call the sandbox set "minimal".
  • The Quickstart links the published Order context page.
  • OAuth tokens states what a key rotation does to tokens minted before it.
  • Who must act: nobody.

Fixed (security, every contract date): PATCH /keys/{id}/allowed-ips applies the console's rules#

  • PATCH /keys/{id}/allowed-ips accepted an empty allowed_ips on a production key, which removed the key's IP restriction, and accepted a list on a sandbox key. The console refuses both. The API now refuses them the same way, on every contract date and unpinned requests alike: 422 VALIDATION_FAILED with details.issues[0].field allowed_ips and details.issues[0].code PRODUCTION_ALLOWLIST_REQUIRED (an empty list on a production key that is not bound to a trusted workload) or SANDBOX_ALLOWLIST_NOT_ALLOWED (a non-empty list on a sandbox key). Clearing the list of a sandbox key, and clearing the list of a production key bound to a trusted workload, are still accepted. The key keeps the list it had.
  • Who must act: a client that clears a production key's allowlist with allowed_ips: [] now gets the console's refusal: send the key's current public egress IPs instead, or bind the key to a trusted workload first. Nothing else changes.

Fixed: POST /orders/{orderId}/fulfill on a wholesale allocation uses the price the order was placed at#

  • Fulfilling a pre-order (awaiting_release) or a backorder (awaiting_stock) placed on a wholesale allocation answered 409 EXPECTED_UNIT_PRICE_REQUIRED, which the request cannot satisfy because fulfil takes no body. Fulfil now checks the delivery against the unit price committed when the order was placed (expectedUnitPriceCents) and the order's integrationOrderContext, which Avrix now keeps with a deferred order. If the allocation's price has changed since, fulfil answers 409 with a message starting WHOLESALE_PRICE_MISMATCH, no key is delivered and the order keeps its status. Applies on every contract date. The price check on POST /orders is unchanged.
  • Orders placed before this release have no stored integrationOrderContext: on an allocation whose territory rules need it, their fulfil answers as before.
  • Who must act: nobody. Retry fulfil on a wholesale pre-order or backorder that was refused EXPECTED_UNIT_PRICE_REQUIRED.

Fixed: a pre-order becomes ready at its release, and a key-locked pre-order never does#

  • The job that moves waiting orders to ready (and sends order.ready) promoted a pre-order (awaiting_release) as soon as the Content Owner had uploaded keys, before the release; fulfil then delivered nothing. A pre-order is now promoted only once its release is unlocked, or its pre-order window has closed and its release date has passed: the rule the delivery itself applies. A backorder (awaiting_stock) is still promoted as soon as stock covers it.
  • The job also promoted a key-locked pre-order (preordered: a pre-order line of POST /orders/bulk, POST /keys/pull or POST /keys/export), whose keys Avrix delivers at the release itself, and sent order.ready for it. It no longer does. Orders already promoted keep their status. Applies on every contract date.
  • Who must act: nobody. A store that calls fulfil on order.ready receives the event when fulfil can deliver, and no longer for a key-locked pre-order.

Changed behaviour (contract date 2026-12-01 only): POST /orders/preview answers a paused allocation as POST /orders does#

  • On contract date 2026-12-01 and later, preview of an order 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 for the same order, instead of 404 ALLOCATION_INACTIVE. details.previewError and details.allocationStatus are kept.
  • Earlier dates and unpinned requests keep 404 ALLOCATION_INACTIVE exactly.
  • Who must act: integrations that pin 2026-12-01 and match preview's 404 ALLOCATION_INACTIVE: match 400 with details.allocationResolve NO_ACTIVE_ALLOCATION, the answer POST /orders gives.

Fixed: the sandbox catalog in whoami describes SANDBOX-PREORDER-001 as it behaves#

  • The sandbox catalog entry for SANDBOX-PREORDER-001 still said the SKU is not sellable and that an order is refused PRODUCT_NOT_SELLABLE. Since pre-orders are on by default the SKU is sellable: preview quotes fulfillmentType: pre-order and POST /orders answers 200 with status: awaiting_release and no keys. The expectedOutcome text now says so. Only the text changed.
  • Who must act: nobody.

Changed behaviour (contract date 2026-12-01 only): GET /partners lists connections in their notice period and pending connection requests#

  • On contract date 2026-12-01 and later, GET /partners without status also lists connections with status terminating (notice given, still live until terminationEffectiveAt; earlier dates left them out although orders under them still succeed) and your connection requests that wait for an answer, with status pending. A request row has no connection yet: its connectionId is the request id, its contracts summary is empty, and its connectionRequest object says who sent it, whose answer it waits for and where to follow it in the console.
  • Earlier dates without status list active, suspended and terminated connections exactly as before.
  • Who must act: integrations that pin 2026-12-01 and treat every GET /partners row as a tradeable connection: skip rows whose status is pending (or that carry connectionRequest), and handle terminating like active until terminationEffectiveAt. Pass only connection ids to GET /partners/{connectionId}/offers.

Added: connection requests and a status filter on GET /partners#

  • status (comma-separated: active, suspended, terminating, terminated, pending, rejected) lists exactly the statuses named, on every contract date. rejected requests come with the vendor's note in connectionRequest.reviewNote and are listed only when asked for. An unknown value answers 422 VALIDATION_FAILED with details.issues[].field status.
  • Request rows carry connectionRequest (requestId, initiatedBy, waitingOn, requestedAt, decidedAt, reviewNote, consoleUrl). Requests are still sent and answered in the console; consoleUrl opens that request's page in the company that owns the key.
  • Who must act: nobody. A store that onboards many vendors can follow its requests with GET /partners?status=pending,rejected.

Added: GET /partners/{connectionId}/agreements reads the agreed terms#

  • Lists the agreements in force (active, terminating) or suspended (paused) on one connection: the master agreement and each business-model agreement, with effectiveFrom, expiresAt, renewalPolicy, termination dates, the territory orders are checked against, sellerRevenueSharePercent, the settlement terms and the sale-currency rule, and a consoleUrl to the signed documents. Requires seller:products:read. A connection that is not yours, or a connection request id, answers 404 NOT_FOUND.
  • The MCP server has a matching list_partner_agreements tool, and list_partners takes a status argument.
  • Who must act: nobody. Read it when a contract.* event arrives instead of waiting for an order to be refused at an agreement's end date.

Documentation: partner onboarding covers connection requests, agreed terms and access proposals#

  • Partner onboarding states which vendor-relationship decisions are made over the API and which in the console, documents access proposals (list, accept, decline, the seller:account:manage scope, Idempotency-Key, the access.proposal_created event) and gives the empty-sandbox row a check you can run (GET /whoami sandboxCatalog.tenantReady).
  • The error reference lists every details.accessCode an access proposal answer can return.
  • The partner filter on GET /products and GET /catalog/checksum takes a partner row's publisherCompanyId (a slug-safe company id, not a UUID), never its connectionId; the reference now says so on GET /partners.
  • The glossary, How Avrix works and Partner onboarding expand BMA as Business Model Agreement, the name the console uses.
  • Who must act: nobody.

Added: connection.request_decided and sandbox.certification_passed events#

  • connection.request_decided fires once when a vendor approves or rejects a connection request your company sent: requestId, decision (approved or rejected), publisherCompanyId, connectionId (the new connection on approval, null on rejection), reviewNote (the vendor's note on rejection), requestedAt and decidedAt. Its GET /events resourceType is the new value connection_request. Nothing fires for a vendor's invitation you answer yourself.
  • sandbox.certification_passed fires when a sandbox key's certification report passes every case, the first time and again only after a report with a failed case: keyId, keyName, environment, reportVersion, caseCount, firstPass and passedAt. It is sent to the endpoints registered with that sandbox key, and is evaluated when the report is built (GET /sandbox/certification, the console panel, or accepted evidence).
  • Both are listed by GET /webhooks/event-types, and a sandbox key can test-fire both. New event types are never added to an existing endpoint's subscription, and no existing payload changes.
  • Who must act: nobody. Subscribe to connection.request_decided to stop polling GET /partners for an answer, and to sandbox.certification_passed to know when to ask for review.

Added: an early warning when a webhook endpoint keeps failing#

  • An active endpoint becomes failing once at least 3 delivery attempts in a row have failed and the run has lasted at least 10 minutes, about 45 hours before the circuit breaker would disable it. The endpoint stays active and retries continue; the breaker is unchanged.
  • Two new events: system.webhook_endpoint_failing (once per episode) and system.webhook_endpoint_recovered (the next 2xx). Both are on your event log, so GET /events (contract date 2026-12-01) shows the warning even when every endpoint is down. Company admins also get a console notification.
  • GET /webhooks rows gain failing, failingSince, lastSuccessAt, lastFailureAt, consecutiveFailedAttempts, pendingDeliveries and updatedAt.
  • Who must act: nobody. To be warned by webhook, add system.webhook_endpoint_failing (or system.*) to an endpoint other than the one you are watching.

Added: read one webhook endpoint, and the full endpoint on every write#

  • GET /webhooks/{id} returns one endpoint in the GET /webhooks shape, health included.
  • The answers of POST /webhooks, PATCH /webhooks/{id} and POST /webhooks/{id}/enable also carry that shape. Existing fields are unchanged.
  • Who must act: nobody.

Added: the delivery log#

  • GET /webhooks/{id}/deliveries/{deliveryId} shows one delivery: the body your endpoint received, the identifying headers, your endpoint's last answer, and attemptHistory, one entry per attempt with its time, outcome, status, error, duration and an excerpt of the answer. Excerpts are at most 500 characters, and credentials your endpoint echoed back are masked before they are stored. Attempts before this release have no history entries.
  • GET /webhooks/{id}/deliveries rows gain eventLogId.
  • Who must act: nobody.

Added: pause an endpoint, and resume without the backlog#

  • POST /webhooks/{id}/disable pauses an active endpoint (disabledReason: manual). Events are buffered as after a circuit-breaker disable; a pause raises no alert.
  • POST /webhooks/{id}/enable accepts an optional replayFrom: buffered events older than it are closed as failed with lastError: skipped_on_enable (skippedBufferedDeliveries) instead of being sent; retry and replay can still send them. Without it, enable sends every buffered event, as before. An invalid or future replayFrom answers 422 VALIDATION_FAILED.
  • Who must act: nobody.

Changed behaviour (contract date 2026-12-01 only): a test send reaches a disabled endpoint#

  • On contract date 2026-12-01 and later, POST /webhooks/{id}/test on a disabled endpoint queues one test delivery (202) instead of answering 400 BAD_REQUEST. The endpoint stays disabled; the test is not retried and does not count toward its health.
  • On the same date, POST /webhooks/{id}/enable refuses a body that is not a JSON object with 422 VALIDATION_FAILED; earlier dates ignore it.
  • Who must act: integrations that pin 2026-12-01 and read the 400 as "endpoint disabled": read status from GET /webhooks/{id}.

Changed behaviour (contract date 2026-12-01 only): at most 16 webhook endpoints per company#

  • On contract date 2026-12-01 and later, POST /webhooks answers 409 WEBHOOK_ENDPOINT_LIMIT_REACHED (details.limit, details.current) when the company already has 16 endpoints, active and disabled; for a sandbox key the limit is per key. Endpoints that already exist above the limit keep working, and earlier dates have no limit.
  • Who must act: integrations that pin 2026-12-01 and create an endpoint per event or per customer: subscribe fewer endpoints to more events, with wildcards.

Added: wildcard subscriptions and schema pointers#

  • An endpoint's events accepts * (every event, including ones added later) and <family>.* (for example order.*). One event reaches an endpoint once; the older alias order.returned is sent only to endpoints that name it.
  • GET /webhooks/event-types entries gain category (the family) and schemaRef (the pointer to the payload schema in the OpenAPI document).
  • Who must act: nobody. A wildcard endpoint receives event types added later, so acknowledge event types you do not handle.

Added: GET /events says when you fell behind its retention#

  • On contract date 2026-12-01, meta gains retentionDays, retainedFrom and positionBeforeRetention. The last is true when your cursor or since is older than the 30 days the log keeps, so events in between may be gone.
  • Who must act: event-log readers that can be offline for weeks: on positionBeforeRetention: true, reconcile from orders, allocations and the catalog before continuing.

Added: webhook delivery history is kept 30 days#

  • Finished deliveries (succeeded or failed) are deleted after 30 days by a daily job; the guide promised at least 7 days and nothing was deleted before. Pending and buffered deliveries are never deleted.
  • Who must act: anyone who reads GET /webhooks/{id}/deliveries for history older than 30 days: keep your own copy.

Added: forward events to a local receiver#

  • @avrix/seller-api-helpers exports forwardEventsToLocal (also from @avrix/seller-api-helpers/local-forwarder): it reads GET /events and posts each event to a local URL with delivery headers, signed with a secret you choose. Avrix still delivers only to public HTTPS URLs. See Local development.
  • Who must act: nobody.

Documentation: the webhook delivery guarantee, stated precisely#

  • Webhooks now says what is guaranteed: an event on your event log is delivered at least once to every endpoint subscribed to it, and recording follows the change it reports rather than being part of it, so a failure between the two can leave a change without its event. Reconcile from the resources.
  • Who must act: nobody, if you run the reconciliation job the guide recommends.

Added: a ...Minor name for every amount#

  • Every success response and every webhook event that carries an amount named ...Cents, or the bare cents of a per-currency bucket, now also carries it under its ...Minor name with the same value: unitPriceMinor beside unitPriceCents, totalMinor beside totalCents, amountMinor beside cents. Amounts already named ...Minor are unchanged.
  • GET /finance/summary reports (recentReports, attentionReports) gain totalNetRevenueMinor and currencyExponent beside totalNetRevenue, the one total the API gave in major units.
  • Request fields and CSV columns keep their names: send expectedUnitPriceCents as before.
  • The convention is in Naming conventions.
  • Who must act: nobody. Read the ...Minor names in new code.

Added: paths that name what they act on#

  • GET /keys/pulls (listKeyPulls) lists key pulls, the list GET /transactions serves.
  • API keys are managed under /api-keys: GET and POST /api-keys (listApiKeys, createApiKey), DELETE /api-keys/{id} (deleteApiKey), POST /api-keys/{id}/rotate (rotateApiKey) and PATCH /api-keys/{id}/allowed-ips (updateApiKeyAllowedIps). /keys paths act on game keys everywhere else.
  • DELETE /orders/hold/{holdId} (releaseHold), POST /orders/reservations/{reservationId}/commit (commitReservation) and POST /orders/reservations/{reservationId}/extend (extendReservation) name the hold or the reservation in the path. A body that also names it must name the same one, or the request is refused with 422 VALIDATION_FAILED.
  • Each new path runs the same handler as its older path: same scopes, rate limit, Idempotency-Key rule, responses and errors. The SDKs and the Postman collection gain one method or request for each; the older ones stay.
  • Who must act: nobody.

Added: ids and invoice numbers under their own names#

  • GET /keys/pulls and GET /transactions rows gain keyPullId (the same value as id), transactionId (the sale row the pull produced, the id GET /finance/api-sales/{transactionId} reads; null when the pull has no sale row) and skuId.
  • GET /finance/invoices, invoice.issued and invoice.paid gain platformInvoiceNumber (the number Avrix gives the invoice) and supplierInvoiceNumber (the number on the Content Owner's own document, null when they use none). invoiceNumber keeps its value on each: the platform number on the list, the supplier number (when there is one) on the events.
  • api_key.created, api_key.rotated and api_key.revoked gain apiKeyId, the same value as keyId: keyId names a game key everywhere else.
  • GET /finance/api-sales rows gain refundStatus, the refund state in the vocabulary GET /refunds uses for status (null when nothing took the sale back). adjustmentStatus keeps the ledger's own values. pending is declared in both vocabularies but not produced today: a refund is recorded complete in the request that asks for it.
  • Who must act: integrations that passed a GET /transactions row's id to GET /finance/api-sales/{transactionId} got 404: pass the row's transactionId. Match invoice events to GET /finance/invoices on platformInvoiceNumber, not invoiceNumber.

Deprecated: the older names of those amounts, ids and paths#

  • The ...Cents names (and cents) beside each new ...Minor name, and totalNetRevenue.
  • GET /transactions, and its rows' id and readableId (readableId is not an order id; look the order up with orderReference).
  • GET and POST /keys, DELETE /keys/{id}, POST /keys/{id}/rotate and PATCH /keys/{id}/allowed-ips.
  • DELETE /orders/hold, POST /orders/commit and POST /orders/{orderId}/extend.
  • invoiceNumber on GET /finance/invoices, invoice.issued and invoice.paid; keyId on api_key.* events.
  • Each keeps working with the same value and behaviour. The API reference marks them deprecated, and so do the SDK methods of the older operations (@deprecated in TypeScript and PHP, the docstring in Python). No sunset is set, no Deprecation header is sent, and removing them would need a new major contract. They are listed in Active deprecations.
  • Who must act: nobody yet. Use the new names in new code.

Changed behaviour (contract date 2026-12-01 only): an Idempotency-Key reused on another target is a mismatch#

  • On contract date 2026-12-01 and later, 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 sent to another allocation or another key answers 409 IDEMPOTENCY_KEY_MISMATCH. Earlier contract dates replay the first answer, so the second target was never changed although the call answered 200.
  • A true retry (same path, same body, same key) still replays.
  • Who must act: integrations that pin 2026-12-01 and reuse one key across targets: use one key per target, and retry with the same X-Avrix-Api-Version you first sent.

Added: updatedAt on GET and DELETE /me/integration-presets#

  • GET /me/integration-presets returns updatedAt, the time of the last PUT, as PUT already did. DELETE and a GET with no presets saved return updatedAt: null.
  • Who must act: nobody.

Fixed: the API reference describes every response and webhook#

  • Reference correction: every success response and every webhook payload has an example, and every parameter a description. Every webhook declares the headers a delivery carries (X-Avrix-Signature, X-Avrix-Event-Id, X-Avrix-Delivery-Id and the others on Webhooks).
  • Reference correction: listAllocationsRequests and createRequest declare their 200 bodies (SellerAllocationRequest, SellerAllocationRequestCreated); getRequest declares its 422 body; getAvailability and getFinanceApiSaleTransaction declare data with the fields they return.
  • Reference correction: the finance status fields list their values with what each means: invoice status and invoiceType, sales report status and modelType, statement aggregationStatus and reconciliation paymentState. New values may be added; treat an unknown value as "not yet handled", not as an error.
  • The reference groups regions and platforms under Reference data and partner operations under Partners, says how the key selects production or sandbox on the one host, and states the rule for unknown fields and values. POST /api/seller/v1/oauth/token reaches the token operation as /api/seller/oauth/token does; neither checks X-Avrix-Api-Version.
  • The API did not change. The SDK method names, signatures and existing types did not change: the TypeScript SDK suggests the listed finance values and still accepts any string there (x-extensible-enum in the reference).
  • Who must act: nobody. A client generated from the reference gains the typed bodies.

Added: one typed client, payload types, readable method names and a paginator in the SDKs#

  • TypeScript: createSellerApi() in @avrix/seller-api-client returns every operation as a typed method bound to one configuration. Given the createSellerClient() result of @avrix/seller-api-helpers, every typed call runs on the helpers transport (retries, throttling, automatic Idempotency-Key). See Official SDKs.
  • Python: avrix_seller_api.models has a TypedDict for every request body and every response data; iter_items() and iter_pages() follow meta.nextCursor for any list method.
  • PHP: Generated\Shapes declares a PHPStan array shape for every request body and response data; Paginator::items() and Paginator::pages() follow meta.nextCursor.
  • All three: readable method names next to the generated ones, for example pullKeys for pullKey, revokeApiKey for deleteKey and sendTestWebhook for createTest. Each calls exactly the same operation. No method, parameter or return type was renamed or removed.
  • Who must act: nobody.

Added: MCP connector tools for refunds, disputes, finance, the promotions calendar and integration checks#

  • New seller_api_ tools: refunds and chargebacks (list_refunds, get_refund, create_refund, resolve_chargeback), dispute freezes (freeze_dispute_keys, release_dispute_freeze), finance (get_finance_statement, get_finance_ledger, get_api_sale_transaction, get_invoice_reconciliation, list_settlement_activity), promotions (get_promotions_calendar, list_promotion_share_discounts, filters on list_promotion_shares), platforms, and integration checks (webhook event types, test and retry deliveries, the event feed, catalog and availability change feeds, allocation requests, usage, request traces, integration status).
  • list_available_tools and explain_tool name the Seller API operations each tool calls. The full list is under AI assistants and the Avrix MCP connector.
  • Who must act: nobody.

Fixed: the MCP tool list_orders lists orders#

  • seller_api_list_orders returned key pull transactions (GET /transactions), one row per key, although it is described as listing orders. It now reads GET /orders: one row per order, filtered by status, from and to, or the single order for orderReference.
  • The previous rows stay available: pass source: "transactions" to list_orders, or call list_transactions.
  • seller_api_export_keys now checks for the seller:keys:export scope, the scope the route requires, instead of seller:keys:pull. Key export stays off on the hosted connector.
  • Who must act: agents or prompts that read per-key rows from list_orders: pass source: "transactions" or use list_transactions.

Documentation: the helpers README used a base URL that doubled the path#

  • The @avrix/seller-api-helpers README configured the generated client with https://api.avrix.io/api/seller/v1; operation paths already start with /api/seller/v1, so every request went to /api/seller/v1/api/seller/v1/.... The README now uses the host https://api.avrix.io and createSellerApi().
  • Who must act: integrations that copied that base URL: use https://api.avrix.io.

2026-11-12#

Added: Idempotency-Key on eight more writes, so every retry is safe#

  • These operations now accept an optional Idempotency-Key: POST /allocations/requests, POST /promotions/shares/{shareId}/accept, POST /promotions/shares/{shareId}/decline, POST /promotions/deals/{responseId}/respond, PATCH /webhooks/{id}, POST /webhooks/{id}/deliveries/replay, POST /keys and POST /keys/{id}/rotate. A retry with the same key and body replays the first answer with Idempotency-Replayed: true and acts once; the same key with a different body answers 409 IDEMPOTENCY_KEY_MISMATCH, and a retry while the first call still runs 409 IDEMPOTENCY_REQUEST_IN_FLIGHT. The header is optional on every contract date; a request without it behaves as before.
  • Secrets are never stored for a replay: a replayed POST /keys omits key, a replayed POST /keys/{id}/rotate omits secret, and both carry secretRedacted: true. A replayed PATCH /webhooks/{id} rotation returns the secret the first call minted while it is still the endpoint's secret, and secretRedacted: true once the endpoint has been rotated again.
  • Idempotency now lists, generated from the API reference, every operation that requires the header and every one that accepts it.
  • Who must act: nobody. Send a key on these calls wherever your client retries.

Added: an overlap window for in-place API key rotation#

  • POST /keys/{id}/rotate takes an optional body, { "overlapSeconds": n } (60 to 86400). The replaced secret then keeps working until previousSecretExpiresAt, which the response returns (null without a window). Rotating again inside the window issues a new secret and keeps the same replaced secret and expiry; a rotation without overlapSeconds or a revoke ends the window. The window covers Authorization: Bearer with the secret, not POST /oauth/token.
  • A rotation without a body behaves as before: the replaced secret stops at once. A body the endpoint ignored before is still ignored; only an overlapSeconds outside 60 to 86400 answers 422 VALIDATION_FAILED.
  • Who must act: nobody. Rotate with overlapSeconds so a lost response never locks you out.

Added: paging and state fields on webhook and promotion writes#

  • POST /webhooks/{id}/deliveries/replay returns hasMore and nextSince: when the window held more deliveries than limit, call again with since set to nextSince.
  • PATCH /webhooks/{id} with rotateSecret: true returns previousSecretExpiresAt: until when deliveries are also signed with the replaced secret.
  • Share accept and decline, and deal respond, return the promotion's status after the call.
  • Who must act: nobody.

Fixed: a refund that fails part-way changes nothing#

  • POST /refunds quarantined the keys and then stamped the sale in a second write. When that second write failed the request answered 500 with the keys already quarantined, and a retry answered 409 KEY_NOT_RETURNABLE: the sale stayed billable and could not be refunded through the API. The keys, the sale stamp and the refund completion now commit together or not at all, so a refund that answers 5xx can be retried with the same Idempotency-Key.
  • Who must act: nobody. If a refund answered 500 and then 409 KEY_NOT_RETURNABLE, contact support with the request ids so the sale can be corrected.

Fixed: automatic allocation grants stay within the publisher's limit#

  • Two POST /allocations/requests sent at the same moment could both be granted automatically from the same reading of the grant, taking it past the publisher's automatic limit. The limit is now checked again when the grant is applied; a request that would exceed it waits for the publisher's review, as a request over the limit always has.
  • Who must act: nobody.

Fixed: two answers to one promotion cannot both land#

  • Accept and decline of the same share (or approve and reject of the same deal) sent at the same moment could both answer 200, the second overwriting the first. The first answer now stands; the other answers as a repeat would (400 BAD_REQUEST, or 409 CONFLICT on contract date 2026-12-01 and later).
  • Who must act: nobody.

Changed behaviour (contract date 2026-12-01 only): answering a promotion that already has an answer#

  • On contract date 2026-12-01 and later, POST /promotions/shares/{shareId}/accept, .../decline and POST /promotions/deals/{responseId}/respond on a promotion that already has an answer return 200 with its status when the answer is the same (a retry of a call that worked), and 409 CONFLICT with details.reason (SHARE_ALREADY_RESPONDED or RESPONSE_ALREADY_ANSWERED) and details.currentStatus when it is different. Earlier dates keep 400 BAD_REQUEST for both.
  • Who must act: integrations that pin 2026-12-01 and branch on the 400 of a repeated answer: treat the 200 as success and handle the 409.

Changed behaviour (contract date 2026-12-01 only): webhook replay does not clone replays or test deliveries#

  • On contract date 2026-12-01 and later, POST /webhooks/{id}/deliveries/replay leaves out deliveries that are themselves replays (their payload carries replay) or test deliveries, so replaying the same window twice no longer multiplies deliveries. Earlier dates clone every matching delivery.
  • Who must act: integrations that pin 2026-12-01 and replay a replayed delivery on purpose: replay the original delivery instead.

Documentation: POST /allocations/requests never required Idempotency-Key#

  • Idempotency listed POST /allocations/requests among the routes that require the header; it never did. It now accepts one. The promotions and integration recipes pages now say how to retry an answer, and webhooks how to retry a secret rotation.
  • Who must act: nobody.

Fixed: an order is found by its id however many orders the store has#

  • GET /orders/{orderId}, GET /orders?orderReadableId= and POST /orders/{orderId}/fulfill looked an order id up in a capped slice of the store's orders: the 500 durable orders the database returned first, and the newest key pulls up to the row cap. An order outside that slice answered 404 NOT_FOUND although it existed, from roughly the store's thousandth order on. The id is now looked up through an index, in both order read models, at any volume.
  • Who must act: nobody. If you added a fallback to ?orderReference= after a 404 on an id, you can keep it; it is no longer needed.

Added: orderId on every order response and order webhook#

  • An order now has one id, orderId (ord_ plus eight characters), on every response that returns an order: POST /orders (fulfilled and pre-order), POST /orders/bulk lines, POST /orders/commit, GET /orders (lookup, cart and list), GET /orders/{orderId}, and the order.fulfilled and order.preorder_fulfilled webhooks. For an order placed from this release on it is the same value everywhere; store it, and use it with GET /orders/{orderId}, GET /orders?orderReadableId= and POST /orders/{orderId}/fulfill.
  • Until now a fulfilled create response carried only orderReadableId (the id of the order's first key pull), while a pre-order, the list and GET /orders/{orderId} could name the same order with a different ord_ value. Both values of an order placed before this release keep resolving on every lookup.
  • The pre-order variant of POST /orders already returned orderId and status; the API reference now declares them. Reference correction: createOrder (SellerOrderPreorderData).
  • Who must act: nobody. New integrations: store orderId.

Deprecated: orderReadableId on order responses#

  • orderReadableId on order responses, bulk lines, the aggregate's fulfilled lines and the order.fulfilled webhook is deprecated in favour of orderId. It stays in every response; no sunset date is set. On contract date 2026-12-01 and later it carries the same value as orderId.
  • The orderReadableId query parameter of GET /orders is not deprecated: it takes any order id.
  • Who must act: nobody now. When you next touch the code that stores the order id, read orderId instead.

Changed behaviour (contract date 2026-12-01 only): orderReadableId holds the order's one id#

  • On contract date 2026-12-01 and later, every orderReadableId in an order response (POST /orders, POST /orders/bulk, POST /orders/commit, GET /orders, GET /orders/{orderId}) holds the same value as the response's orderId, and a GET /orders list row's orderId is the order's one id in both read models.
  • On earlier dates and unpinned requests, orderReadableId keeps the id of the order's first key pull, and in the reconstruction read model a list row of an order placed before this release keeps that pull's id as orderId. For an order placed from this release on the values are already the same on every date.
  • Who must act: only an integration that pins 2026-12-01 (or sends next) and compares orderReadableId values stored before this release with values read afterwards: compare on orderReference, or look the stored value up with GET /orders/{orderId}, which accepts both.

Changed behaviour (contract date 2026-12-01 only): order reads are not cached#

  • GET /orders (lookup, cart and list) was sent with Cache-Control: private, max-age=60, so a client with an HTTP cache polling an order for ready, or after a refund, could read a state up to a minute old. On contract date 2026-12-01 and later it is sent with Cache-Control: private, no-store, like GET /orders/{orderId} already was.
  • Earlier dates and unpinned requests keep private, max-age=60. See Caching and fairness.
  • Who must act: only an integration that pins 2026-12-01 (or sends next) and relies on its HTTP cache to absorb repeated order reads: expect each read to reach the API and count against the orders rate limit.

Added: what an order was billed at, on the order#

  • A delivered order now carries economics: the order's API sale rows summed, with the same field names as the activity log's economics (currencyCode, currencyExponent, quantity, unitPriceCents, initialUnitPriceCents, totalPriceCents, promo, publisherShareCents, sellerShareCents, platformFeeCents, revenueSharePercent, vatMinor, netMinor, transactionIds). It is on the fulfilled POST /orders response, each delivered POST /orders/bulk line, and the GET /orders and GET /orders/{orderId} aggregates.
  • It is null when the order has no API sale rows: a wholesale or complimentary allocation, which is billed per allocation rather than per sale, or a pre-order not delivered yet. Refunds and chargebacks are not netted in; they stay under the order's refunds and in the finance reads.
  • Who must act: nobody. To record cost of goods at checkout, read economics instead of a second call to GET /finance/api-sales.

Added: GET /whoami says which order read model the environment uses#

  • capabilities.orderReadModel is durable (orders are read from the order table, which holds every status) or reconstruction (orders are rebuilt from delivered keys, so the order listing holds fulfilled, returned and refunded orders only). See Order lifecycle.
  • Who must act: nobody. A store that lists orders by a pre-delivery status can check this field instead of reading an empty page as "none".

Fixed: POST /orders/recover-keys accepts every order reference#

  • POST /orders accepts an orderReference of up to 255 characters, but POST /orders/recover-keys refused one over 128 with 422, so a long reference could be ordered and not recovered. It now accepts up to 255, the same limit. The API reference also states the limit on the GET /orders and POST /orders/cancel reference fields: a longer value matches no order.
  • Who must act: nobody.

Documentation: GET /orders and the order guides give one answer per question#

  • GET /orders is titled for what it does (list orders, or look one up by reference or id), and its description says how to tell the three response shapes apart; its 404 and 422 descriptions now match the list mode. The order guides now say once which id to store (orderId), how to look an order up (GET /orders/{orderId} or ?orderReference=), and which checkout flow is the default.
  • Who must act: nobody.

Added: every paged list carries limit, hasMore, nextCursor and nextUrl#

  • Every paged list now answers the same four meta keys, described once on the new Lists and pagination page. Keys a list already had keep their names and values; only missing ones were added:
    • hasMore on GET /partners, GET /keys, GET /webhooks, GET /webhooks/{id}/deliveries, GET /promotions/shares, GET /promotions/deals, GET /activity, GET /refunds and GET /events;
    • nextUrl on GET /activity, GET /finance/ledger, GET /events, GET /catalog/changes and GET /availability/changes;
    • limit on GET /events, GET /catalog/changes and GET /availability/changes;
    • a meta object on the GET /finance/statements JSON response, beside data.nextCursor and data.truncated, which keep their meaning.
  • GET /catalog/changes and GET /availability/changes also send the X-RateLimit-* headers.
  • Reference correction: listPartners, listPromotionsShares, listPromotionsDeals and listWebhooksDeliveries already returned meta with limit, count, nextCursor and nextUrl; the API reference now declares it.
  • Who must act: nobody. New code can loop on meta.hasMore everywhere.

Added: X-Next-Cursor on every CSV export, readable from a browser#

  • The GET /finance/statements and GET /finance/api-sales CSV downloads send the next cursor in X-Next-Cursor, like the ledger and activity exports. The statement keeps X-Avrix-Statement-Next-Cursor, with the same value.
  • X-Next-Cursor and X-Avrix-Statement-Next-Cursor are now listed in Access-Control-Expose-Headers, so a browser client can read them; before, a cross-origin script could not see the cursor of a CSV page.
  • Who must act: nobody.

Fixed: lists keep their place while items are added#

  • GET /partners, GET /keys, GET /webhooks, GET /webhooks/{id}/deliveries, GET /promotions/shares and GET /promotions/deals paged by position: an item created between two calls shifted every later page by one, so a walk could serve an item twice. They now page by keyset (newest first, then by id), with the same items in the same order, and an item created during a walk no longer moves the pages. Shares, deals, webhooks and deliveries are paged in the database instead of loading every row first.
  • GET /webhooks/{id}/deliveries stopped at the newest 100 deliveries; it now pages through the whole retained history.
  • A cursor issued before this release is still read, so a walk in progress finishes normally.
  • Who must act: nobody.

Fixed: the GET /finance/api-sales cursor is opaque#

  • The API reference said the cursor of GET /finance/api-sales was a numeric offset string. It is the opaque meta.nextCursor value, as on every list; offset cursors issued before 2026-08 are still read. Reference correction: listFinanceApiSales.
  • Who must act: nobody, unless you build this cursor yourself: send back meta.nextCursor unchanged instead.

Changed behaviour (contract date 2026-12-01 only): an unreadable list cursor answers 422#

  • On contract date 2026-12-01 and later, a paged list refuses a cursor it cannot read with 422 VALIDATION_FAILED, details.issues[].field cursor: GET /partners, GET /keys, GET /webhooks, GET /webhooks/{id}/deliveries, GET /promotions/shares, GET /promotions/deals, GET /activity, GET /refunds, GET /finance/api-sales, GET /finance/invoices, GET /transactions and GET /allocations.
  • Earlier dates and unpinned requests ignore such a cursor and serve the first page, as before.
  • Who must act: only an integration that pins 2026-12-01 (or sends next) and sends a cursor it did not receive from the same list, for example one stored for another list or truncated.

Changed behaviour (contract date 2026-12-01 only): a change-feed position beyond retention answers 409#

  • The catalog and availability feeds keep their rows for at least 30 days. A cursor or since older than that used to get a page of the rows still kept, with no sign that the rows between were deleted, so a mirror could miss removals and price changes. On contract date 2026-12-01 and later, GET /catalog/changes and GET /availability/changes answer 409 CATALOG_RESYNC_REQUIRED with details.reason retention_expired, the same code a sandbox move already uses, for production keys too. A position at or after the oldest kept row is served as before.
  • On the same date GET /catalog/changes refuses a limit that is not a whole number from 1 to 5000 with 422, and both feeds give their 422 the details.issues[] form every other list uses. Earlier dates keep the earlier answers: the catalog feed serves a page (clamping a number into range), and both keep details.field.
  • Positions deleted before this release are not recorded, so the 409 covers rows deleted from this release on.
  • Who must act: an integration that pins 2026-12-01 (or sends next): handle the 409 by taking a fresh GET /catalog/snapshot and continuing from its meta.changesCursor and meta.availabilityCursor (error reference). If you already handle CATALOG_RESYNC_REQUIRED for the sandbox move, that handler covers it.

Changed behaviour (contract date 2026-12-01 only): GET /allocations?sellableOnly=true fills each page#

  • With sellableOnly=true, the filter ran after the page was cut, so a page could be short or empty while meta.hasMore was true. On contract date 2026-12-01 and later each page is filled with sellable allocations up to limit. The items and their order are the same; only where the pages break changes.
  • Earlier dates and unpinned requests keep the earlier pages.
  • Who must act: nobody who loops on meta.hasMore. A client that counted pages, or stopped at the first empty page, gets full pages instead.

Documentation: one page for lists and pagination#

  • Lists and pagination describes the list contract once: the four meta keys, cursors, page sizes, change feeds and CSV exports. The catalog, finance, webhook, promotion, polling and versioning guides link to it, and the versioning guide no longer says to start the catalog feed from since and stop when nextCursor is absent: start from the snapshot's meta.changesCursor and loop on meta.hasMore.
  • Who must act: nobody.

Added: platform.notice, announcements about the API as a webhook event#

  • A new webhook event, platform.notice, carries Avrix's announcements about the Seller API itself: a contract change, a deprecation, a change of the default contract date, the switch of rate limits to enforced, planned maintenance. Each notice has a stable noticeId, a category, actionRequired, a plain-text title and summary, effectiveAt, the contractDate it concerns, the operations or events it affects, and a url with the details. See the event reference.
  • It is sent only to endpoints whose events include it, so no existing endpoint receives anything new. GET /webhooks/event-types, POST /webhooks and PATCH /webhooks/{id} accept it, and a sandbox key can test-fire it with POST /webhooks/{id}/test. The catalog now has 41 events.
  • Who must act: nobody. To hear about changes without reading this page, add platform.notice to an endpoint's events.

Added: Deprecation and Sunset response headers for deprecated operations and parameters#

  • A deprecated operation, query parameter or request header can now answer with Deprecation: @<Unix seconds> (RFC 9745) and, when a removal is scheduled, Sunset: <HTTP-date> (RFC 8594), each with a Link to the explanation. A request that sends no X-Avrix-Api-Version can receive them before the default contract date changes; a pinned request never does. The API reference declares both headers. See Deprecation communication.
  • No date is scheduled, so no response carries them today. A date is set only after a changelog entry names it.
  • Who must act: nobody now. Consider logging or alerting when a response carries Deprecation.

Fixed: info.version in the API reference is the default contract date#

  • The OpenAPI document's info.version was 2026-09-08, which is not a contract date. It is now 2026-09-01: the date an unpinned request is served, the date the SDKs pin and the date in their version number. A new info.x-avrix-contract-dates object lists the default, every supported date and the opt-in dates. Both are checked against the dates in code on every change, and so is the table of contract dates on the versioning page.
  • The SDKs' OPENAPI_VERSION constant (Python and PHP) moves to 2026-09-01 with the next regeneration; method signatures do not change.
  • Who must act: nobody, unless a tool of yours compares info.version to decide when to regenerate a client: it now changes when the default contract date does.

Documentation: every changelog entry has a type and says who must act#

  • From this date, every entry starts with its type (Breaking, Changed behaviour, Deprecated, Added, Fixed or Documentation) and ends with who must act; Breaking and Changed behaviour entries name the contract date that gates them. A check refuses an entry without them. Entries dated before 2026-11-12 keep their original headings.
  • Versioning and compatibility states the rule the types follow: a new refusal, a changed status or error code, or a changed field ships only behind the next contract date. A check on each change to the API reference refuses a breaking difference without such an entry.
  • Rate limits: two pages said "your tier"; there are no tiers, and the pages now say so. Monitoring and support: support is by email with no published hours or response times, the status page has no subscription, and planned maintenance can arrive as a platform.notice.
  • Who must act: nobody.

Added: contract date 2026-12-01 (opt-in)#

  • New contract date 2026-12-01. It is opt-in: pin it with X-Avrix-Api-Version: 2026-12-01, or send next, which now resolves to it. The stamped default for unpinned requests stays 2026-09-01. The new date includes everything on 2026-10-01 (typed key objects).
  • From now on, a correction that changes what an existing request gets back (a status, an error code, a field) is released on this date only, so an integration sees none of them until it pins the date. See Supported contract dates.
  • Who must act: nobody. If you send next on production traffic, it now also selects the behaviour described in the next entry.

Changed behaviour (contract date 2026-12-01 only): a missing Idempotency-Key has its own error code#

  • On contract date 2026-12-01 and later, a write that requires Idempotency-Key and receives none, or a malformed one, answers 400 IDEMPOTENCY_KEY_REQUIRED. details.idempotency is key_missing or key_invalid, and details.maxLength and details.pattern state the format (1 to 64 characters from A-Z, a-z, 0-9, - and _). See the error reference.
  • Unpinned requests and every earlier contract date keep the response they have today: 400 BAD_REQUEST with the message "Idempotency-Key header is required for this operation."
  • Who must act: only an integration that pins 2026-12-01 (or sends next) and matches on BAD_REQUEST for this refusal: match on IDEMPOTENCY_KEY_REQUIRED as well.

Fixed: the API reference declares Idempotency-Key on every operation that requires it#

  • Nine operations required the header while the API reference, the SDK types and the Postman collection did not show it, so a call written from them was refused with 400: accepting and declining an access proposal, POST /disputes/freeze, POST /disputes/{freezeId}/release, POST /orders/{orderId}/fulfill, POST /orders/{orderId}/extend, POST /orders/{orderId}/keys/{keyId}/replace, and regenerating and revoking a keyless fulfilment. All 22 operations that require the header now reference one shared parameter, which also publishes the key format. PATCH /allocations/{id} declares the header as optional. The Idempotency guide lists the same 22.
  • The API itself did not change: these operations always required the header.
  • SDKs: the PHP and Python clients now send a generated key on these operations when you do not pass one; the TypeScript types gain the header.
  • Who must act: an integration that calls one of the nine operations without the header (it is refused today): send Idempotency-Key.

Fixed: examples in the API reference are accepted by the API#

  • Corrected request examples that the API refused with 422: DELETE /orders/hold (holdId is a UUID), POST /refunds and POST /keys/return (keyIds are UUIDs), POST /promotions/deals/{responseId}/respond (decision is approved or rejected), POST /api/seller/oauth/token (client_id is the key's UUID). POST /keys now leads with an example that is accepted as written; the allowlist examples say that 203.0.113.10 is a documentation address to replace with your own.
  • Corrected response examples that did not match their schema: GET /orders (lookup mode), the 409 examples of POST /orders, and GET /whoami.
  • Every example in the reference is now checked against its schema on each change.
  • Who must act: nobody.

Fixed: GET /regions and promotion share discounts are documented as unpaged#

  • GET /regions, GET /regions/{code} and GET /promotions/shares/{shareId}/discounts listed limit, cursor and (regions) partner, which were never read: the routes always returned the complete list. The reference now says the reads are not paged and marks those parameters deprecated: they are still accepted, and still ignored. GET /regions/{code} now has a typed response.
  • Nothing changes for a request that sends them, and the generated SDK methods keep their signatures.
  • Who must act: nobody. If you send these parameters you can stop: they have no effect.

Fixed: operations are filed under eleven reference groups#

  • The reference used twelve groups where nine were declared, one of them a duplicate webhooks. It now has eleven: Seller auth, Seller meta, Catalog, Allocations, Orders, Keys, Refunds, Webhooks, Finance, Promotions, Sandbox. Moved: the refund, chargeback, key-return and dispute operations to Refunds; allocations and availability to Allocations; GET /transactions to Orders; /me/footprint and /me/integration-presets to Seller meta; API key management to Seller auth.
  • Paths, operation ids and SDK method names are unchanged.
  • Who must act: nobody.

Fixed: the Postman collection contains every operation#

  • Twelve operations were missing from the collection: selling footprint and integration presets (new Account folder), access proposals (new Access proposals folder), chargeback resolution and dispute freezes (in Refunds), and the sandbox certification report (new Sandbox folder). Requests for the nine operations above now carry Idempotency-Key.
  • Who must act: re-import the collection to get the new requests.

Fixed: GET /orders/{orderId} accepts the order-read scopes#

  • GET /orders/{orderId} accepted seller:products:read only, so a key holding the documented seller:orders:read listed orders but was refused 403 FORBIDDEN on a single order. It now accepts the same four scopes as GET /orders: seller:orders:read, seller:orders:write, seller:products:read and seller:keys:pull. The API reference lists them on the operation.
  • Every key that could read a single order before still can. A key with none of the four is still refused; the 403 now names seller:orders:read as the missing scope.
  • Who must act: nobody. If you added seller:products:read to a key only to read single orders, you can drop it.

Fixed: all three rate-limit headers on every response to a counted request#

  • X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset are now on every response to a request that was counted against a limit, on every route: successes, 304, validation and not-found errors, 5xx, replayed idempotent responses and 429. See Rate limits.
  • Before, successful responses carried none of them on GET /orders/{orderId}, GET /catalog/changes, GET /availability/changes, POST /orders/{orderId}/fulfill, POST /orders/{orderId}/keys/{keyId}/replace, GET /products/{productId}/media/download, POST /geo/attest, the allocation request, allocation settings and replenishment routes, /me/integration-presets, access proposal accept and decline, and dispute freeze and release. X-RateLimit-Reset was missing on POST /keys/pull, POST /keys/return, POST /keys/export, POST /orders/commit, POST /orders/reserve, POST /orders/hold, DELETE /orders/hold, POST /orders/{orderId}/extend, keyless fulfilment regenerate and revoke, and POST /webhooks. Error responses carried none on any route.
  • Values that were already sent are unchanged. Limits and enforcement are unchanged. A request refused before it is counted (401, a scope or IP allowlist 403) still carries none.
  • Who must act: nobody.

Changed behaviour (contract date 2026-12-01 only): GET /orders refuses a status filter it cannot serve#

  • Until durable-order reads are switched on for an environment, its order listing is built from delivered keys and holds fulfilled, returned and refunded orders only. A status filter for any other value (awaiting_release, preordered, awaiting_stock, ready, partially_fulfilled, cancelled, failed) returned an empty page, which reads as "you have none".
  • On contract date 2026-12-01 and later that request answers 422 VALIDATION_FAILED: details.issues[0].field is status, the message names the value, and details.issues[0].allowedValues lists the values the listing can serve. Where durable-order reads are on, every value is served and nothing is refused. See Order lifecycle.
  • Unpinned requests and every earlier contract date keep the response they have today: 200 with data: [] and meta.nextCursor: null.
  • Who must act: only an integration that pins 2026-12-01 (or sends next) and filters the listing on one of those statuses: handle the 422, or look the order up by orderReference. Everyone else: do not read an empty page for those statuses as "no orders".

Changed behaviour (contract date 2026-12-01 only): a missing scope answers INSUFFICIENT_SCOPE#

  • On contract date 2026-12-01 and later, a request whose key lacks the scope the operation needs answers 403 INSUFFICIENT_SCOPE. details.requiredScopes lists every scope the operation accepts, preferred first, and details.scopeMode says whether one of them is needed (anyOf) or any Seller API scope will do (any). details.missingScope names the preferred scope. See the error reference.
  • Unpinned requests and every earlier contract date keep the response they have today: 403 FORBIDDEN with the same message and the same details.missingScope and details.requiredScopes. Scopes added to an operation in this release do not appear in that older body.
  • POST /keys already answered INSUFFICIENT_SCOPE when the calling key could not grant the new key its scopes; it still does, on every date.
  • Who must act: only an integration that pins 2026-12-01 (or sends next) and matches on FORBIDDEN with details.missingScope for a scope refusal: match on INSUFFICIENT_SCOPE as well.

Added: scopes that match the action#

  • New scope seller:allocations:write for the two allocation writes, POST /allocations/requests (ask a vendor for more stock) and PATCH /allocations/{id} (top-up settings). Both still accept seller:orders:write and seller:keys:pull.
  • Refund and dispute writes (POST /refunds, POST /chargebacks/resolve, POST /keys/return, POST /disputes/freeze, POST /disputes/{freezeId}/release) and refund reads (GET /refunds, GET /refunds/{refundId}) now also accept seller:orders:write, as the scope matrix said they did.
  • GET /activity, the settlement feed, now accepts seller:finance:read, the scope of the other finance reads. seller:products:read is still accepted.
  • GET /me/footprint and GET /me/integration-presets can be read by any Seller API key. Changing either still needs seller:account:manage.
  • No scope that worked on an operation before has been removed from it.
  • Who must act: nobody. For a new key, choose scopes from the scope matrix.

Added: GET /orders/{orderId} returns everything the order listing returns#

  • The single-order read now carries the fields its row in GET /orders carries: keyIds, totalCents, currencyCode, currencyExponent, createdAt, fulfilledAt and updatedAt. Each has the value the order's listing row has, including null where the row has none (for example money on an order with no recorded sale).
  • Who must act: nobody. If you read an order twice to get its total and its timestamps, one call is now enough.

Documentation: one scope matrix, generated from the API reference#

  • The scope tables of the scope matrix are now generated from the scopes the API reference declares on each operation, which a check keeps equal to what the API enforces. The page lists every operation, the scope to choose for each job, and the operations any key can call. Other guides link to it instead of keeping their own lists.
  • seller:keys:pull, and seller:products:read on order reads and the settlement feed, are deprecated in the documentation: do not put them on new keys. They stay accepted wherever they are accepted today, and no date has been set to stop.
  • Who must act: nobody. When you next issue a key, use the preferred names.

Added: GET /usage says when its counts are cut short#

  • One GET /usage response counts at most 50,000 requests. A window with more used to return totals for the earliest 50,000 with nothing to show they were partial. The response now carries truncated (boolean) and maxCountedRequests (50000). When truncated is true, narrow from and to until it is false and add the windows up. See Monitoring and support.
  • The counts themselves are unchanged.
  • Who must act: nobody. If you chart usage for a busy key, check truncated.

Documentation: the request inspector's sampling and retention are documented#

  • The API reference and Monitoring and support now state what GET /requests/{requestId} covers: writes and recorded errors on the order, key, refund and webhook routes are always traced; on other routes 429 and recorded 5xx responses always, other 4xx about 1 in 10 and successful responses about 1 in 100; a request refused before its handler ran is not traced. Traces are kept for 90 days. A request without a trace answers 200 with traces: [], the same as an unknown id.
  • The API itself did not change.
  • Who must act: nobody. Do not treat an empty trace as proof that a request was never made.

Fixed: PUT is an allowed CORS method#

  • Access-Control-Allow-Methods listed GET, POST, PATCH, OPTIONS, DELETE, so a browser client on an allowed origin could not call PUT /me/footprint or PUT /me/integration-presets. PUT is now listed. Server-to-server calls were never affected.
  • Who must act: nobody.

Fixed: the API reference states the scopes, headers, status codes and response fields the API uses#

  • Scopes. Every operation now lists every scope its handler accepts, the preferred name first (x-avrix-scopes), and says how to read the list (x-avrix-scope-mode: one of the listed scopes, any seller scope, or no key). The reference had named one scope per operation and never seller:orders:read or seller:orders:write: it now shows, for example, that GET /orders accepts seller:orders:read, seller:orders:write, seller:products:read and seller:keys:pull, and that GET /whoami, GET /access/proposals, POST /geo/attest and GET /sandbox/certification accept a key with any seller scope.
  • Headers. X-Avrix-Api-Version, X-Request-Id and the sandbox-only X-Avrix-Sandbox-Simulate are declared as request headers on the operations that read them, with their accepted values. Responses declare X-Request-Id, X-Avrix-Api-Version, Idempotency-Replayed, Retry-After and the X-RateLimit-* headers. The three X-RateLimit-* headers are required on every success response of an operation that counts requests against a limit and declared on its 429 (not required there: a sandbox 429 simulated with X-Avrix-Sandbox-Simulate: rate_limit carries none). On operations that count nothing (GET /health, GET /webhooks/egress-ips, the two /geo/attest/{attestId} operations and the OAuth token exchange) the 429 keeps its X-RateLimit-* entries, marked not required and described as not sent by that operation; the OAuth token exchange's 429 sends Retry-After.
  • Status codes. Operations now declare the statuses they already returned and the reference left out: 400 UNSUPPORTED_API_VERSION, 409 for a reused or in-flight Idempotency-Key, 413 for a body over 100 KB, 422 for a refused path, query or body value, and the retryable 503 and 504. Also, among others: 409 NO_ACTIVE_BMA on POST /webhooks, 404 on the webhook management operations, 410 on POST /orders/{orderId}/extend, 412 on POST /orders/commit, 304 on GET /products and GET /products/{productId}. A strict POST /orders/bulk cart that is refused when the keys are taken answers the refusing line's own code and status with details.strictCart; the reference now says so. Operations that read no API key say which of their listed statuses they never return.
  • Response fields. GET /whoami declares sandboxTenant, sandboxCatalog and capabilities.requireProductionAllowlistEnabled. POST /keys/{id}/rotate returns the new secret as data.secret, not data.key as the reference said. relatedProducts on product detail is inside data. GET /keys returns meta. resolved on the chargeback.resolved event is the number of sales resolved, not a boolean.
  • Corrections a breaking-change check will flag. The reference changes, not the API: resolved on the chargeback.resolved event is now declared as integer or boolean (it was boolean only), the one type this entry widens; the API sends an integer, and the sandbox test event still sends true. data.key on POST /keys/{id}/rotate stays declared and is described as never returned. Nothing declared before this entry has been removed.
  • Guides. Sandbox names the six operations that ignore X-Avrix-Sandbox-Simulate: rate_limit. Creating orders documents the rollback_incomplete outcome of a refused strict cart, which the guide reported as rolled_back in every case. The scope matrix points to x-avrix-scopes in the API reference.
  • The API itself did not change: this entry corrects the reference, the Postman collection and the generated TypeScript types. The TypeScript client now also sends your bearer token on eight operations where it was left out (/me/footprint, /me/integration-presets, GET /finance/ledger, GET /finance/api-sales/{transactionId} and the invoice reconciliation file) when the token is supplied through the client's auth option.
  • Who must act: nobody, unless you generated a client from the earlier reference: generate it again. If your code reads data.key after rotating a key, read data.secret.

Refunds per allocation are limited#

  • Refunds plus chargebacks on one allocation are limited to 20% of the keys sold on it in the last 30 days, and never fewer than 5 keys. POST /refunds and POST /keys/return answer the new 422 REFUND_LIMIT_REACHED above that, with the figures in details; nothing is refunded. Sandbox keys are not limited. See Refunds and key returns.
  • POST /keys/return now honours the Content Owner's refund window, like POST /refunds with type: "refund": a late return answers 422 REFUND_WINDOW_EXPIRED.
  • If the refund window cannot be read, both routes answer 503 with Retry-After instead of accepting the refund.

Health no longer counts a disabled endpoint's buffer as backlog#

  • GET /health components.webhookDelivery.pending (and backlog.webhookDeliveriesPending) now count only deliveries that are waiting to be sent. Deliveries buffered for a disabled endpoint are reported apart as buffered and never degrade the status. Before, one disabled endpoint with a full buffer kept the status degraded for everyone.

API keys manage only keys within their own reach#

  • POST /keys/{id}/rotate, PATCH /keys/{id}/allowed-ips and DELETE /keys/{id} act on the calling key, or on a key in the same environment whose scopes and IP allowlist stay within the calling key's. GET /keys lists the calling key's environment only. See API key management.
  • An IP-restricted key can narrow its own allowlist through PATCH /keys/{id}/allowed-ips, but no longer widen or clear it: that answers 403 FORBIDDEN. Add an address in the console, or with a key that is not IP-restricted.
  • GET /keys rows carry status (active or revoked) and revokedAt. Revoked keys were already listed; they can now be told apart.

Documentation: guides corrected where they contradicted the API#

Documentation only. The API did not change. Who must act: nobody. If you built from the earlier wording, check the item that applies to you.

  • Webhooks. The delivery timeout is 8 seconds; two passages of the Webhooks guide still said 30. The event list is 40 events, not 32. order.returned is your cancel of a pre-order or backorder, not a buyer return. The registration sample shows the real response (id is a UUID, plus deliveryProbe), the guide no longer points at a single-endpoint read that does not exist (use the GET /webhooks list), the secret rotation sample no longer sends an Idempotency-Key that PATCH ignores, and a change of pinned egress addresses is announced 14 days ahead, not 30.
  • Event reference. New sections for order.activated, order.ready and chargeback.resolved. occurredAt is documented as present on every delivery. allocation.low_stock is described as it works: a fixed 10% of quantityLimit, sent with every allocation update while remaining is at or below it, and unrelated to replenishThreshold.
  • Default contract date. Every page now says the same thing: a request without X-Avrix-Api-Version is served 2026-09-01. next is accepted with any key and resolves to the newest supported date, opt-in dates included. See Versioning and compatibility.
  • Catalog sync. One merge rule on every page: a SKU is sellable when GET /allocations lists it with sellable: true. An allocation without a share is not sellable (NO_SKU_SHARE); the catalog guide said it was. The GET /allocations sample uses limit=100 (the maximum) and rows keyed id, and the merge sample in Sellable SKU readiness now reads the snapshot shape correctly and pages allocations.
  • Scopes. A request that lacks a scope answers 403 FORBIDDEN with details.missingScope. The guides showed INSUFFICIENT_SCOPE, which only POST /keys returns. The scope matrix now lists every operation; twelve were missing.
  • Key recovery. The Key recovery runbook now recovers lost keys with POST /orders/recover-keys. Its former step 3 sent you to POST /keys/export, which pulls and bills new keys. Order lifecycle, Reconciliation and Fulfilment keys say the same.
  • Change feed. This changelog's RSS feed, https://docs.avrix.io/changelog.xml, is linked from the Versioning, Changelog and Monitoring pages.
  • SDKs. The Official SDKs page states that the TypeScript, Python and PHP packages are not on npm, PyPI or Packagist yet, and what to use until they are.

2026-11-09#

Unlisted releases report as open#

  • Content owners can mark a release Unlisted. For stores nothing changes: an unlisted release you have access to reports tradingState: open; a release you have no share for is not in your catalog.

2026-10-27#

Every money object says how many decimals it has#

  • currencyExponent beside currencyCode on the finance and order objects that did not carry it yet: GET /finance/api-sales rows (also statement lines[]), every statement bucket, approved settlement, settlement invoice and outstanding balance on GET /finance/statements, GET /finance/ledger entries and meta.balances[], GET /finance/invoices rows, GET /finance/summary per-currency items, GET /orders list rows, each sale of GET /finance/invoices/{invoiceId}/reconciliation, and the invoice.created and payout.file_ready webhooks. The reconciliation file also gains paymentCurrencyExponent for totalCents and the movement amounts.
  • integrationOrderContext as echoed on finance rows and order webhooks gains currencyExponent for its *Minor amounts. It is response only: do not send it.
  • GET /products and catalog snapshot rows gain listPriceCurrencyExponent beside listPriceFromCents and listPriceCurrencyCode.
  • Additive. Amounts are unchanged: still integers in the currency's own minor units (0 decimals for JPY, 3 for KWD and BHD). See Money fields.

2026-10-19#

Product detail prices say whether they can sell, and how many decimals they have#

  • GET /products/{id} release pricing[] and skus[].prices[] now carry sellable and blockedReason, like the other price objects since 2026-10-15. The reference already listed both fields here; the response did not send them until now. They also carry currencyExponent, like every other price since 2026-10-10. Additive.
  • The price on GET /availability?country= and GET /availability/{skuCode}?country= rows (priceCents, currencyCode, currencyExponent, zone; null when the country has no price) is now described in Catalog and allocations. The field itself is unchanged.

catalogShareMode keeps the signed mode while an agreement is paused#

  • Changed: a paused Full catalog API agreement reports catalogShareMode: "all". On GET /partners, the field states how the governing API agreement was signed, and a pause does not change that. Before, it read selected while the agreement was paused. The pause itself is reported by pausedBmaTypes. Values and field name are unchanged.

2026-10-16#

Fallback prices say which store currency they replace#

  • fallbackFromCurrency on every price object (GET /catalog/snapshot?pricing=territory sharedSkus[].territoryPrices[], GET /products/{id}/pricing prices[] and skus[].prices[], GET /products/{id} skus[].prices[]). Set when the content owner excludes the currency the store charges in that country and prices the country in another allowed currency: the price is then the platform's highest price in currencyCode (the highest tier cell, or the highest Steam zone, in that currency over every country of the platform), and it sells (sellable: true). null on every other price. Additive.

2026-10-15#

Every price says whether it can sell#

  • sellable and blockedReason on every price object: GET /catalog/snapshot?pricing=territory sharedSkus[].territoryPrices[], GET /products/{id}/pricing skus[].prices[] and the release-level prices[]. A content owner's platform price (a tier price, a Steam price) is now kept in the currency the store charges even when the owner does not allow that currency for the country; the price is reported, with sellable: false and blockedReason: "CURRENCY_NOT_PRICED_FOR_COUNTRY", and an order there is refused with that code until the owner sets a price in an allowed currency or allows the stored one. Additive: prices that could sell before still say sellable: true.
  • The in-app price notice says the same when a changed price cannot sell yet.

2026-10-14#

One refusal order on every order surface#

  • When several checks would refuse the same sale, POST /orders/preview, /orders/hold, /orders/reserve and POST /orders now all name the first in one order, the same order GET /availability?country= reports blockedReason in: your selling footprint (country, then currency), the territory and then the currency the agreement or your partner access grants, the SKU's territory and region locks (restricted countries, SKU locks, release exclusions, then the agreement's locks), the catalog price, the priced currency, the sales channel, and last the buyer checks.
  • What is refused is unchanged; only which code is named when more than one applies. Before, the SKU's territory and the catalog price were checked first: a country you have not declared and that has no price answered CATALOG_PRICE_NOT_SET, and now answers FOOTPRINT_COUNTRY_NOT_DECLARED; a SKU-locked country outside your agreement's territory answered REGION_LOCKED_FOR_SKU, and now answers TERRITORY_NOT_GRANTED.
  • See Currency and FX for the currency checks in that order.

2026-10-13#

A reconciliation file for every payout#

  • GET /finance/invoices/{invoiceId}/reconciliation returns the reconciliation file for one payout, as JSON or format=csv: every balance movement the vendor invoice settles and every API sale under each one, with order reference, key id, gross, VAT, net and the publisher, seller and platform shares. Movement amounts add up to the payout total in the payment currency. The same file is downloadable from the invoice page in the console. Scope seller:finance:read.
  • New webhook payout.file_ready. Fires when a vendor invoice you owe is paid, by any rail. It carries the payout total, the sale count and the reconciliationPath to download. See Event reference.

A finance ledger that ties to the statement#

  • GET /finance/ledger returns your money ledger for a month (period=YYYY-MM) or any window of up to 366 days (from / to): every sale, refund, chargeback and reinstatement entry, oldest first, with running balances per currency on each entry. Refunds and chargebacks are their own negative entries; an entry never changes once returned. meta.balances holds the closing balances, which for a month equal the statement's activityTotals field for field. Keyset paging, a currency filter and format=csv. Scope seller:finance:read. See The ledger.

Launch-window reservations on allocations#

  • launchWindow on GET /allocations. A Content Owner can reserve keys for your store during a launch window. While the window is open, setAside keys are held for you: no other store can take them and your orders use them first. When it closes, unused keys go back to the shared pool. Nothing changes for allocations without a window (launchWindow: null). See Launch-window reservations.

2026-10-12#

An isolated sandbox environment per store#

  • Each store gets its own sandbox. Avrix is moving stores, one at a time, from the shared sandbox catalog to an isolated environment with its own catalog, allocations, stock pools and fault scenario state. All sandbox keys of a store share it; orders and webhook endpoints stay scoped per key. Other integrators can no longer deplete your pools. Production keys are not affected.
  • Public fixture codes are unchanged; sandbox ids change at the move. SANDBOX-ALWAYS-001 and the other fixture codes keep working in requests and appear unchanged in every response, snapshot and webhook. Product, SKU and allocation ids are new in your environment: take a fresh GET /catalog/snapshot after the move. A change-feed cursor from the shared feed, or a since from before the move, answers 409 CATALOG_RESYNC_REQUIRED on GET /catalog/changes and GET /availability/changes.
  • Nothing you hold breaks. Webhook endpoints keep their ids and secrets, idempotent retries replay across the move, and orders placed before it stay reachable by the key that created them through the key-scoped order, refund, dispute and recovery operations.
  • New sandbox error codes. 503 SANDBOX_ENVIRONMENT_UNAVAILABLE while your environment is being prepared or repaired (details.retryAfterSeconds; requests are never routed elsewhere), 503 SANDBOX_ENVIRONMENT_PAUSED for writes while Avrix repairs it (reads keep working), 422 SANDBOX_SCENARIO_UNAVAILABLE and 422 SANDBOX_KEY_REQUIRED. These four and CATALOG_RESYNC_REQUIRED are in the ApiError.code enum and the Error reference.

Stateful fault scenarios#

  • X-Avrix-Sandbox-Simulate takes five scenarios that fail only the first attempt of an idempotent request, so the retry with the same Idempotency-Key and body can recover: timeout_then_success and error_after_commit (the order is committed, then the response is replaced by a 500) on POST /orders, webhook_delay_duplicate (order.fulfilled 30 seconds late and twice with one eventId), partial_cart on POST /orders/bulk and sold_out_after_hold on POST /orders/hold. They run in your store's isolated environment. See Sandbox.

Test-fire any webhook event, with receiver challenges#

  • POST /webhooks/{id}/test accepts an optional body with eventType (any Seller API event, sent with a contract-valid sample payload) and challenge (valid, invalid_signature, stale_timestamp, duplicate, previous_secret_only). Sandbox keys only; production keys keep test.ping and receive 422 SANDBOX_KEY_REQUIRED for anything else. The 202 response adds deliveryIds, eventType, challenge and testRunId.
  • Test deliveries carry testEvent. A top-level testEvent object (testRunId, challenge) marks every test event other than a plain test.ping. A previous_secret_only challenge without an open rotation overlap fails with the new lastError value no_previous_secret. See Webhooks.

Automatic certification report#

  • GET /sandbox/certification evaluates the 28 certification cases from your sandbox key's traffic over the last 30 days: pass, fail, not_run or needs_partner_evidence, with the request and delivery ids behind each. Cases about behaviour inside your systems take evidence you submit in the Console, which Avrix reviews. The report does not enable production access by itself. See Certification.

Per-key orders limit for launches#

  • One production key can get a higher orders limit for a launch. On request, a platform admin can set the orders-class limit of a single production key, optionally for a time window. Outside the window the default of 1,200 a minute applies again. See Rate limits.
  • Read the limit from the headers. X-RateLimit-Limit reports the limit that applies to the key at the time of the request, including a raised one. Nothing else changes.

2026-10-10#

Every price says how many decimals it has#

  • currencyExponent (0, 2 or 3: the ISO 4217 minor-unit digits of the currency next to it) now sits next to every integer money field: basePriceCents on GET /products/{id}/pricing and the snapshot's territoryPrices[], the price on GET /availability?country=, the expand=pricing pairs on GET /products, POST /orders/preview lines, total and settlement, the POST /orders/hold response, declaredRetail on finance rows and the sku.pricing_updated payload. An amount is cents / 10^currencyExponent: JPY 2480 is 2,480 yen, not 24.80. Additive.
  • New Money fields section: what each money field means, with a USD, JPY and KWD example.

Pending title offers, and Full catalog now means the titles listed at signing#

  • Added GET /api/seller/v1/partners/{connectionId}/offers. It lists the titles a Content Owner has offered under your agreement that you have not yet accepted or declined. It is read-only: you accept or decline each offer in the console. A connection that is not yours returns 404. See Catalog and allocations.
  • Changed: a Full catalog agreement now covers the titles listed at signing. Titles the Content Owner publishes later arrive as offers you accept, not automatically. What you can sell is the list of SKUs the Content Owner shares under the titles you accepted.
  • Nothing you read today is renamed. catalogShareMode keeps its values (all and selected). PRODUCT_EXCLUDED stays documented as a readiness blocker but is no longer emitted, because scope is the explicit share list.
  • Changed: catalogShareMode is read per connection. On GET /partners, each connection's catalogShareMode now comes from that connection's API agreement only. Before, it read all when any in-force Full catalog agreement of any model existed with that Content Owner.
  • Unshare emits removed when it ends your access to the product. GET /catalog/changes reports removed when a Content Owner stops sharing the last SKUs of a product you can see, unless another agreement still shares that product with you. The updated event with changedFields: ["availability"] for whole-catalog sharing no longer applies; release and SKU level delists still emit it.
  • Added: SKU share changes under a product you still see are reported. When a Content Owner stops sharing some SKUs of a product but others stay shared, or shares new SKUs under a product you already see, GET /catalog/changes reports each of those SKUs as updated with changedFields: ["availability"] and its skuId and skuCode, the entry a SKU-level delist already uses. No new event type or field. Refetch GET /products/{productId} and re-read GET /allocations (sellable). A 404 on a SKU refetch, or a product that no longer lists the SKU, means it is no longer shared with you: remove it from your listing. The checksum changesCursor moves with it; the digest stays product-level by design.

2026-10-09#

No default sale country#

  • Nothing assumes the United States any more when no country is sent. Readiness checks use your selling footprint (or the SKU's allowed countries), an allocation's price check passes when the SKU has a price in a country you both sell in, and the partner list price uses your pricing country. The order surfaces refuse a missing country with 422 SALES_COUNTRY_REQUIRED, as before.

Partner access#

  • GET /whoami gains accessByPublisher: per Content Owner, the countries (or worldwide) and currencies you may sell, locked countries with the owner's reason, dated changes still to come (pending, each with effectiveFrom) and proposals waiting for your answer. enforced says whether orders are checked against it yet; while false, your agreement governs and this is the same grant, seeded from it.
  • New endpoints: GET /access/proposals lists a Content Owner's offers of more countries or a currency; POST /access/proposals/{id}/accept and /decline answer them (with seller:account:manage and an Idempotency-Key). Nothing changes until you accept. A refusal names details.accessCode, for example ACCESS_FX_NOT_COVERED with details.currencyPair.
  • A narrowing can carry a date. A lock or a removed currency applies from its effectiveFrom: until then it is listed under pending and orders are accepted; from that moment they are refused with the existing codes (REGION_LOCKED_FOR_CONTRACT, TERRITORY_NOT_GRANTED, CURRENCY_NOT_PERMITTED_BY_TERM); the last two then carry details.grantSource: "partner_access". Holds made before the date run to their expiry. You are notified of every narrowing, including title locks and stricter location checks on a title.
  • Partner access applies once you accept the updated platform terms that carry its clause. Until then your agreement governs, accessByPublisher[].enforced is false, and accepting a proposal answers 409 with details.accessCode: "ACCESS_TERMS_NOT_ACCEPTED".
  • No error code, field or enum value is renamed.

One currency per country#

  • A country is sold in the one currency it is priced in. The second-currency path (a currency permitted on a SKU and settled at a reference-rate floor) is retired. A sale declared in another currency is refused with CURRENCY_NOT_PRICED_FOR_COUNTRY, naming the priced currency.
  • SRP_MISMATCH_FOR_CURRENCY is deprecated and no longer returned; details.floorMinor is never set. The code stays in the spec so existing clients keep parsing.
  • all_catalog_currencies in whoami.permittedCurrenciesByPublisher[].currencyMode now permits exactly what primary_only permits.
  • Owners choose their currencies. When a Content Owner stops pricing a country in a currency, sales there are refused with CURRENCY_NOT_PRICED_FOR_COUNTRY (details.reason: "currency_not_allowed_by_owner") until it is priced again.

Price zones on prices, and a price on availability#

  • Every price carries its zone. Product detail prices (release and SKU), GET /products/{id}/pricing and the snapshot's territoryPrices gain an additive zone: { code, label } | null, the platform price zone of the country (for example { "code": "EUR", "label": "Euro area and rest of Europe (EUR)" } for Germany on Steam). Null when the platform has no zones. It is the same label the content owner sees.
  • GET /availability returns the price per country. Each country answer gains an additive price: { priceCents, currencyCode, zone } | null, the catalog price a sale there charges.
  • No breaking changes. Existing fields, codes and readiness reasons are unchanged.

2026-10-08#

Reserve runs the same checks as hold and commit#

  • POST /orders/reserve on an API allocation now runs the order admission that POST /orders/hold and POST /orders run: your selling footprint, the agreement's territory and currencies, the grant, region locks, the sales channel and a price echo when you send one. Before, it priced a request without a country for the United States, compared no price echo, and could accept a reserve that commit then refused with CURRENCY_MISMATCH.
  • A reserve without countryCode or salesCountryCode is refused with 422 SALES_COUNTRY_REQUIRED. Send the buyer's country, as on hold.
  • The admitted price, currency and country are kept on the reserved slot, and commit settles on them.

Every invalid order field in one response#

  • The order surfaces report all field problems at once. On POST /orders, /orders/preview, /orders/hold and /orders/reserve, a 422 about the request's fields (VALIDATION_FAILED, SALES_COUNTRY_REQUIRED, TAX_DECLARATION_REQUIRED, SALES_CHANNEL_REQUIRED, EXPECTED_UNIT_PRICE_REQUIRED) now lists every invalid or missing field in details.issues, each with its path and reason. Previously each response named one field, so a request with several problems took several round trips.
  • Nothing you read today moves. Error codes, field names and enum values are unchanged; the top-level code and message are the same refusal as before, and its field is first in details.issues.
  • Issues carry more. Each issue may include code (the refusal that field alone would get) and, for an enum, allowedValues (for example salesChannel: web, mobile_app, partner_embed, marketplace:<slug>).

2026-10-06#

A price per SKU#

  • skus[].prices[] on GET /products/{id} and GET /products/{id}/pricing: the price a sale of that SKU charges, per country (countryCode, currencyCode, basePriceCents). It is the same price as the snapshot's territoryPrices and the sale price. The release-level price list (pricing[] on product detail, prices[] on /pricing) stays for one API version and is deprecated: a sale charges the SKU price. Additive.

2026-10-02#

Preview checks the price you echo#

  • POST /orders/preview accepts expectedUnitPriceCents (and its deprecated alias expectedWholesaleUnitPriceCents). When you send it for an API-model line and it does not match the territory catalog list price, preview refuses with 409 CATALOG_PRICE_MISMATCH (details.previewError), the same code and status as POST /orders/hold and POST /orders, and returns no quote. Previously the field was ignored and preview quoted the catalog price with canFulfill: true.
  • Omitting the echo is unchanged: preview still returns the current quote.

Preview answers commit's status for every refusal; sellable includes payment#

  • POST /orders/preview documents every status it can return. Each refusal answers the same status as POST /orders (since the shared status table); the spec now lists the 402 PAYMENT_NOT_CLEARED response and names MINIMUM_ORDER_VIOLATION, the declaration codes, PRODUCT_NOT_SELLABLE and the buyer-network outages under 422, 404 and 503. None of these answer 404 "not found" any more.
  • sellable now includes payment clearance. On GET /allocations and the partner product SKUs, a wholesale or pre-order grant whose payment is not confirmed reports sellable: false with the new PAYMENT_NOT_CLEARED readiness blocker and recommendedAction: complete_allocation_payment, because every commit under it is refused with 402. API and revenue-share grants are unaffected: they settle after the sale and never needed payment confirmation. No grant in use today changes state.

2026-09-25#

Approved promotions lower what you are billed#

  • Every promotion is both by default. The Content Owner funds the discount, so an approved promotion now lowers unitPriceCents on API-model lines on POST /orders/preview, POST /orders/hold, reservations and POST /orders, and the sale is billed at the discounted price. promo and listPromo name the same source and unitPriceCents equals advertisedUnitPriceCents. This includes promotions that were already live on release day. list_price remains a supported value, but no console flow sets it. See Promotions.
  • Agreed per-key prices are unchanged. Wholesale, Traditional Revenue Share and Buy-In Wholesale (pre-order) lines keep the price in your agreement, and promo is always null on them.
  • The promotion travels with a bound price. A price-commitment token, checkout hold or hot-drop reservation carries the promotion it was quoted under, so a sale committed after the promotion ended still records it. The token is longer as a result: treat priceCommitmentToken as opaque, since its length and contents may change.
  • promo on correction rows. Refund, chargeback and reinstatement rows of GET /finance/api-sales, GET /finance/statements and GET /activity now carry the original sale's promo, and the promoId filter on GET /activity matches them. initialSalePriceCents is null on those rows.
  • Secondary-currency promo sales. A sale in a permitted secondary currency now records its promo only when the store's settled gross lands below the currency floor worked out from the undiscounted catalog price, never when the gross meets or clears that floor, with initialSalePriceCents always null: the pre-promo price exists only in the catalog currency.
  • Three columns on the api-sales CSV. GET /finance/api-sales?format=csv appends promoSourceType, promoSourceId and initialSalePriceCents (31 columns in all; the full list is in the OpenAPI description). Columns are only ever appended, so parse by header name.

Automatic allocation top-ups#

  • New PATCH /allocations/{id}: set a low-stock threshold (replenishThreshold) and the top-up you want (replenishQuantity). When a pull crosses it, the allocation is topped up within the Content Owner's rules and allocation.replenished is sent; outside the rules an allocation request is filed for the Content Owner (the manual path is unchanged). GET /allocations/{id}/replenishments shows the rules and the history, which the Content Owner sees too. GET /allocations rows carry replenishment. Content Owners set the rules under Allocations → Policy → Automatic top-ups.

Keyless delivery is generally available#

  • Keyless (hosted redemption) is on by default; each Content Owner can refuse it (GET /allocations → keyless.allowed) and choose it as its default (keyless.default).
  • Up to 20 keys per keyless line, with one link for all of them; the buyer reveals each key on its own. delivery.items lists every key's fulfillmentId, keyId and link.
  • New deliveryMode: "auto" follows the Content Owner's default. New webhook fulfillment.revoked when a link is revoked before redemption (manual, refund, chargeback, revoked key). Asking for a platform entitlement provider answers 422 before any key is pulled. See Keyless fulfilment.

Typed key objects (opt-in contract date 2026-10-01)#

  • New contract date 2026-10-01 (opt-in; the stamped default stays 2026-09-01). With it, keys on order responses and POST /orders/recover-keys holds typed objects — { id, type: text | image | link | file, key, url, expiresAt, redemption: { platformCode, url, instructions, locale } } — so image keys, redemption links and platform activation steps can be shown to the buyer. Earlier dates keep string[]. See Fulfilment and key custody and Versioning.

Refund windows and dispute freezes#

  • A Content Owner can set a refund window (all products, or per SKU). refundPolicy.windowDays on GET /allocations and GET /products/{id} shows it (source: publisher or sku), and POST /refunds with type: "refund" after it answers 422 REFUND_WINDOW_EXPIRED. Chargebacks are never windowed. Content Owners set it under Products → Returns → API key replacements and refunds.
  • New POST /disputes/freeze and POST /disputes/{freezeId}/release: freeze delivered keys while a payment dispute is open (withheld from recover-keys, not replaceable). A refund or chargeback on the keys converts the freeze; otherwise it expires after expiresInDays (default 30). New webhooks key.frozen and key.unfrozen. See Refunds and key returns.

Revoked keys are announced#

  • New webhook keys.revoked: when a Content Owner revokes keys already sold (leaked batch, grey-market resale, platform revocation, fraud) each affected order gets one event with the key ids, reason and recommendedAction (replace or refund). GET /orders/{orderId} lists them under revocations[]; POST /orders/recover-keys lists them under revoked[] instead of returning them. A revoked key can be replaced with POST /orders/{orderId}/keys/{keyId}/replace. Content Owners revoke from Products → Key finder → Revoke sold keys. Sandbox SKU SANDBOX-REVOKE-001 revokes its keys right after delivery.

Replace a delivered key in one call#

  • New POST /orders/{orderId}/keys/{keyId}/replace (reason: already_redeemed, invalid, wrong_region, revoked; Idempotency-Key required). The old key is quarantined and a fresh key from the same allocation is delivered: no new sale, no capacity used. Within the Content Owner's policy it answers 200 with the key; otherwise 202 pending until the Content Owner approves. New webhook key.replaced, replacements[] on GET /orders/{orderId}, error 409 KEY_NOT_REPLACEABLE and sandbox SKU SANDBOX-REPLACE-PENDING-001. Content Owners set the policy and decide pending replacements under Products → Returns → API key replacements. See Fulfilment and key custody.

Mirror the catalog with fewer calls#

  • New GET /availability/changes: a cursor feed of stock (stock_down / stock_up with the allocation's new remaining) and sellability (unsellable / sellable with the readiness reasons) changes. Start it from the snapshot's new meta.availabilityCursor.
  • GET /catalog/snapshot?pricing=territory adds territoryPrices (every country list price) to each shared SKU, so a cold sync needs no per-product pricing call.
  • GET /catalog/changes entries now carry skuId and skuCode when the change is about one SKU (a territory price, a SKU pause); null for product-level changes.
  • The TypeScript helpers request territory pricing on syncSellableCatalog and add syncAvailabilityChanges. See Catalog and allocations.

Content Owners can refuse VAT declarations below the reference#

  • New API agreement term vat_declaration_policy: warn (unchanged behaviour, and what applies when the agreement states nothing) or refuse_below_reference. Under refuse, a sale whose declared salesTaxRatePercent is below the reference rate for the sale country answers 422 VAT_DECLARATION_BELOW_REFERENCE on preview and on every committing call, before any key is pulled. GET /whoami lists the policy per Content Owner under vatDeclarationPolicyByPublisher. See Finance and settlement.

Order presets: a production order with only the essentials#

  • New GET / PUT / DELETE /me/integration-presets (scope seller:account:manage) and a console tab (Settings → Commercial → Order presets). With presets saved, a production POST /orders (or bulk line) needs only the SKU, quantity, orderReference, the buyer IP and the priceCommitmentToken; Avrix fills the sales channel, payment method, tax inclusion and checkout session, and derives the sale country, currency, amounts and tax rate. Explicit fields always win, and each filled field is recorded as preset or derived.
  • GET /whoami shows integrationPresets and lists only what is still required.
  • integrationOrderContext.schemaVersion now defaults to 1 when omitted. See Creating orders.

A refunded order reference stays spent#

  • POST /orders (and bulk, reserve/commit) with an orderReference whose order was refunded or returned now answers 409 ORDER_REFERENCE_CONFLICT. Before, a fully refunded reference could be sold a second time. Use a new orderReference for a new sale; a retry of an order that never completed still works under the same reference. See Idempotency.

Orders hold up better under launch bursts#

  • Many concurrent POST /orders on one allocation no longer queue behind each other for the whole delivery: the allocation is locked only for the final capacity step. The allocation limit is enforced exactly as before (never oversold, never short). In a local test with 32 concurrent orders on one allocation, deliveries per second roughly doubled.
  • POST /orders/preview reuses its read-only authority checks for about 5 seconds per SKU and quantity; see Caching and fairness. Refusals and live values (stock, price, territory, buyer geo) are never reused.
  • No request or response changes.

Launch mode is visible on allocations#

  • GET /allocations rows carry hotDropMode: true while the Content Owner has the allocation in launch mode (use POST /orders/reserve → POST /orders/commit). Switching it on or off sends allocation.updated with reason: hot_drop_mode_changed and hotDropMode. See Hot drop.

2026-09-24#

The agreement's territory is enforced#

  • TERRITORY_NOT_GRANTED (422). A sale into a country outside the territory your API agreement grants is now refused on preview, hold, bulk and POST /orders, and GET /availability reports it per country. The grant is set per agreement when the Content Owner invites you (worldwide, specific regions, or your footprint at the time), frozen as a country list at send, and printed in full in the signed Commercial Schedule. Worldwide agreements are unaffected. See Territory enforcement and Where a sale is allowed.

Pre-orders and backorders on by default#

  • whoami.capabilities.preorderEnabled and backorderEnabled are now true by default. A Content Owner can opt its own products out of either; those requests answer PRODUCT_NOT_SELLABLE (reason PREORDER_DISABLED) or 403 BACKORDER_NOT_ALLOWED.
  • Send backorderOnUnavailable: true on every order placed after payment: when stock runs out the order becomes a backorder (status: awaiting_stock) instead of a 409, and the response carries backorderExpiresAt.
  • A backorder still waiting for stock at backorderExpiresAt (default 14 days) is cancelled, its allocation headroom released, and the new order.backorder_expired webhook tells you to refund the buyer. See Order lifecycle.
  • New sandbox magic SKU SANDBOX-BACKORDER-001: never in stock, so every order with backorderOnUnavailable is a backorder; it expires after 15 minutes so you can test the refund path in one session.

Maintained WooCommerce and Shopify plugins#

  • Avrix Keys for WooCommerce (PHP SDK) and Avrix Keys for Shopify (a custom-app backend on the TypeScript SDK) cover the whole store flow: catalog and stock mirror (snapshot, then the GET /catalog/changes cursor), preview (and an optional hold) at checkout, POST /orders after payment through the order recovery helper, keys shown to the buyer, signed webhooks with secret rotation, and POST /refunds on a store refund.
  • The API key stays on your server in both plugins, and keys are stored encrypted. A line is only flagged for a refund when Avrix confirmed that no key was issued for it.
  • Install and configuration: Commerce platforms. WordPress.org and Shopify App Store listings follow; until then the plugins install as an upload (WooCommerce) and as a custom app (Shopify).

Buyer geolocation data on every deployment#

  • Buyer-country detection. Staging and production deployments now carry the buyer geolocation database. Before this, buyer countries were never detected, so a declared VAT rate above the store-country rate settled at the store-country rate (rateReason: fallback_store_country).
  • Health. GET /health components.consumerGeo is degraded when a deployment has no (or stale) buyer geolocation data, and that degrades the top-level status with a degradedReasons entry (still HTTP 200). whoami.capabilities.buyerGeolocationStatus mirrors it.

Activation territory is enforced by default#

  • A sale into a country where the SKU's keys provably cannot be activated is now refused with 422 ACTIVATION_REGION_MISMATCH (policy enforce_known, previously warn), on preview, hold, reserve, orders and every bulk line. Unknown activation coverage is still allowed.
  • A Content Owner can accept the redemption risk for its own SKUs; its sales then only warn.
  • The error carries recommendedAction: restrict_sale_to_activation_countries and details.allowedCountries. Rehearse it with SANDBOX-ACTIVATION-LOCK-001 (Germany only).

Checkout holds are part of production health#

  • GET /health reports components.checkoutHold. A deployed environment without the hold store (or with holds switched off) is degraded, which degrades the top-level status, instead of letting stores fall back to preview → order unnoticed.
  • The Postman collection has a Store profile B folder (preview → hold → order with checkoutHoldId) that fails when holds are unavailable.

Status page: order placement and sandbox#

  • The public status page reports two more capabilities: order placement (server-error share on order requests) and the sandbox. GET /health carries them as components.orderPath and components.sandbox, and components.webhookDelivery.deliveryP95Seconds reports delivery latency. The error playbook and the quickstart link to the status page.

Guides agree with each other#

  • Bulk carts: every guide now says the same thing. An omitted strict is true on contract 2026-09-01, which unpinned requests have used since 2026-09-01; only a request pinned to 2026-04-29 keeps partial success.
  • IP allowlists: expected on every production key; whether an empty list is refused is reported by whoami.capabilities.requireProductionAllowlistEnabled (IP allowlist).
  • The superseded single-hold page now redirects to Checkout holds.

Large catalogs: snapshot served from a prebuilt store#

  • GET /catalog/snapshot is kept compressed and rebuilt once per catalog change, in the background, for stores that read snapshots. A catalog with thousands of products no longer rebuilds on every call.
  • Without Accept-Encoding: gzip, a large snapshot is streamed rather than refused. Send gzip anyway: it is roughly ten times smaller.

Fair-use limits for production keys (shadow mode)#

  • Production keys now have per-key limits per route class: catalog 600, orders 1,200, finance 300 requests a minute, plus 6 full catalog snapshots an hour (304 revalidations are free). X-RateLimit-* reports them.
  • They start in shadow mode: nothing is refused. GET /whoami reports data.key.rateLimitMode: "shadow". Enforcement (429 with Retry-After) will be announced here before it is switched on. Details: Rate limits.

Catalog caching: origin only, documented as it works#

  • Catalog reads no longer send s-maxage. Seller API responses are private and key-scoped, so no shared CDN cache ever stored them; the guides that promised a 5-minute edge cache were wrong. Speed comes from the per-company response cache, the prebuilt catalog snapshot and conditional GETs (If-None-Match → 304, no rate cost). Your own HTTP cache may keep a body for the max-age shown in Caching and fairness.

One slow webhook receiver no longer delays the others#

  • Webhook delivery waits up to 8 seconds for your response (was 30). A timeout is retried with backoff (lastError: timeout).
  • Every delivery run caps how many deliveries a single endpoint contributes. An endpoint that is timing out gets one delivery per run until it answers in time again, so a slow store cannot hold up the deliveries of other stores.

Key export needs its own scope#

  • POST /keys/export (keys as a ZIP file) now requires the opt-in scope seller:keys:export. seller:keys:pull and seller:orders:write no longer grant it. Keys that called the route in the 90 days before 2026-09-24 were granted the new scope automatically, so an exporting integration keeps working. Any other key gets 403 FORBIDDEN with details.missingScope: "seller:keys:export"; issue or edit the key with the scope to export.

rateReason says whether the store-country cap changed the rate#

  • A sale without corroborated buyer evidence whose declared VAT rate sat at or under the store country's rate now reads settlement.rateReason: declared_within_store_cap: the declared rate was applied as declared. fallback_store_country now means the cap lowered the declared rate. Sales settled earlier keep their stored reason. Statement and audit "store rate" shares count both values; by_rate_reason separates them.

Readable product ids in paths#

  • GET /products/{productId}, /products/{productId}/pricing and /products/{productId}/media/download accept the readable prd_ id that product payloads return as readableId, as well as the UUID. A well-formed prd_ id for a product you cannot see answers 404 NOT_FOUND, and any other shape 422 VALIDATION_FAILED.

One spelling for the country filter#

  • GET /products/{productId}/pricing accepts countryCode, the spelling the availability routes already use. country stays accepted on pricing and availability. Sending both with different values fails validation. A request that uses only country gets an X-Avrix-Deprecated-Parameter: country; replacement="countryCode" response header. No sunset is scheduled for country.

Declared buyer IP must not be the store server#

  • At buyer verification level declared_ip, a production key's integrationOrderContext.consumerIp that equals the calling server's address, or matches the key's IP allowlist, is refused with 422 CONSUMER_IP_INVALID on preview, hold, reserve, orders and bulk. This is the rule that already applied to checkout confirmations. Sandbox keys are unchanged.

Official SDKs for TypeScript, Python and PHP; public Postman collection#

  • Three official SDKs. @avrix/seller-api-client with @avrix/seller-api-helpers (npm), avrix-seller-api (PyPI) and avrix/seller-api (Packagist) are generated from the OpenAPI document and expose every operation as a method, with typed errors that carry code, recoverable, requestId and details. See Official SDKs.
  • Order creation with key recovery. Each SDK ships one helper that retries POST /orders with the same Idempotency-Key and body, looks the order up with GET /orders?orderReference=, re-reads lost keys with POST /orders/recover-keys, and reports a refund as safe only when no live keys exist.
  • Webhook verification and catalog mirror. The verifiers accept any v1 signature during a secret rotation; the catalog mirror seeds from the snapshot and follows the GET /catalog/changes cursor.
  • Versions follow the contract date. 1.20260901.0 targets contract 2026-09-01 and sends it as the default X-Avrix-Api-Version.
  • Postman. The Seller API collection and its production environment are a direct download on this site, regenerated from the OpenAPI document with every release.
  • Quickstart. Steps 4, 6 and 8 show the SDKs next to cURL.

2026-09-23#

Spec matches the runtime; Postman runs end to end; retry before you refund#

  • OpenAPI matches what the API sends. POST /orders declares fulfillmentState, transactionIds and warnings on both the fulfilled and the pre-order shape (warnings used to sit beside them, where generated clients dropped it), plus meta.requestId; bulk lines declare fulfillmentState and transactionIds; POST /webhooks declares deliveryProbe; GET /webhooks declares consecutiveFailures, disabledReason and its pagination meta; GET /orders/{orderId} declares meta. A contract test now compares runtime responses with the spec for orders, order detail, bulk, webhooks, activity and the finance summary, and the generated client is regenerated.
  • Postman. Required query parameters ship a value (statements period), every path variable is a declared collection variable (no literal {{refundId}}), and a request whose path ids are still empty skips itself with a message instead of failing the run.
  • 5xx after you charged the buyer. 503 IDEMPOTENCY_STORE_UNAVAILABLE and 504 HOT_PATH_TIMEOUT can arrive after the order was fulfilled and billed. The error playbook, Idempotency and the golden path now carry one rule: retry with the same Idempotency-Key and orderReference, check GET /orders?orderReference=, recover lost keys with POST /orders/recover-keys, and refund only when no live keys exist. The HOT_PATH_TIMEOUT entry no longer promises the order did not commit.
  • 409 shortfalls. The integration profiles name both codes: NO_AVAILABLE_KEYS (vendor stock empty) and ALLOCATION_EXCEEDED (your allocation cap; request more with POST /allocations/requests).
  • Catalog deltas. Guides that suggested GET /products?updatedSince= for polling now point at GET /catalog/changes: price and stock changes never move a product's updatedAt.

Finance before the monthly report; list-price deals in every currency#

  • GET /finance/summary shows the running month. currentPeriod counts this month's API sales and their totals per currency before any monthly report exists, and publisherRelationshipCount counts the publishers you hold a live grant with (it read 0 until a report existed). notices says when balances and reports are still waiting on the report. The response is now typed in the OpenAPI spec.
  • An empty GET /finance/invoices explains itself. Invoices follow report approval; an empty first page while the month has sales carries meta.notices pointing at the statement. The lifecycle is described in Finance and settlement.
  • List-price deals in a secondary currency. A preview in a permitted secondary currency settles at the reference-rate floor with no settlement promo, but it now still reports the live listPromo and advertisedUnitPriceCents, so a store can show the vendor's sale price.
  • CATALOG_PRICE_NOT_SET in the error playbook says how to find the countries a SKU is priced in (GET /products/{productId}/pricing, GET /availability?countryCode=).

Health that reflects the queues, explained export failures, order traces#

  • GET /health reports queue health. components.webhookDelivery and components.outboxJobs carry pending, dueLagSeconds (how long the oldest due row has waited past its due time) and failedLast24h. The top-level status is degraded when a queue is overdue or backlogged, or push delivery is not configured in production, with degradedReasons naming each cause (HTTP 200; only a database failure answers 503). Thresholds are in Monitoring and support.
  • Background job retries honour their backoff. A job that failed is no longer re-run early by a duplicate push; one that is not yet due waits for its time.
  • Catalog exports explain a failure. GET /catalog/exports/{exportId} returns attempts and, when status is failed, error { code: "EXPORT_FAILED", message, retryable }. Posting the same export again requeues it and reports its real status (it used to answer pending while the export stayed failed). The gzip artifact upload that caused the failures is fixed.
  • Order traces. GET /requests/{requestId} rows carry orderReference and outcome, and the response lists webhookDeliveries for the request and its order reference.

Bulk carts can be read back by your cart id#

  • GET /orders?parentOrderReference= returns every line of a bulk cart (the parentOrderReference you sent in its integrationOrderContext), in line order. The order list, order detail and GET /transactions carry parentOrderReference and lineIndex, and GET /transactions?parentOrderReference= lists a cart's pulls. Refunds stay per line (Order context).

Product detail for one store page; media archive revalidation#

  • GET /products/{productId}?locales=de,fr keeps only those languages in localizedDescriptions and eula (a language keeps its regional variants). A single product in one language is a few kilobytes instead of every locale. Without locales the response is unchanged.
  • descriptionFormat=text returns long descriptions as plain text: paragraphs, line breaks and bullet points, without the store's HTML, embedded video players or scripts.
  • An unknown expand value is 422 naming it (it used to return the full payload).
  • GET /products/{productId}/media/download carries an ETag computed from the asset list. If-None-Match answers 304 without a download, and HEAD returns the headers without building the archive. The file name is stable for the same assets.

Pricing and product detail agree on a release's state#

  • GET /products/{productId}/pricing reports each release's launchPhase and tradingState, and its deprecated status now matches the product detail. It could read draft for a released SKU whose phase is set on the edition or advanced by its release date, so a price sync that skipped drafts dropped a sellable SKU.

Requesting more allocation through the API#

  • requestable on availability and on GET /allocations now says what POST /allocations/requests accepts: any grant of yours that is not revoked. It used to read false unless the grant was already exhausted and the publisher had configured an automatic rule, although the request was accepted either way (without a rule it goes to the publisher for review). Once a grant has no headroom, recommendedAction is request_allocation_increase.
  • A request on a revoked grant is 409 CONFLICT with details.reason: grant_not_requestable.
  • A SKU held under two business models (an API and a wholesale grant) used to answer "SKU not found" on availability and on POST /orders by skuId. Both now use the grant with headroom, preferring the API model; send allocationId to choose.

Listing: status filters that find every match, unknown parameters refused#

  • GET /orders?status= finds every match. The filter used to run on one page after it was cut, so status=refunded could return an empty page (with a cursor) while refunded orders sat further back. The listing now pages until it has limit matches or reaches the end, and meta.nextCursor is null when nothing more matches. preordered is accepted as the name pre-orders had before awaiting_release and selects the same orders.
  • Unknown query parameters are refused. A GET with a parameter its route does not declare answers 422 VALIDATION_FAILED naming it (?customerReference= on GET /orders used to be ignored and returned every order). Parameters several routes already read are now declared: limit / cursor on GET /keys, /partners, /webhooks, /promotions/deals, /promotions/shares; cursor on /webhooks/{id}/deliveries; quantity on GET /availability/{skuCode}. GET /finance/api-sales?orderReference= now filters (it was ignored and returned every sale); /catalog/snapshot takes no partner (scope rows by publisherCompanyId). The filters syntax is documented in the lists and pagination guide.

2026-09-22#

Checkout risk scoring level#

Connections whose buyerVerificationByPublisher level is checkout_attest_risk now score each confirmed checkout once (preview, hold, reserve and commit share the result). Two new error codes: CONSUMER_RISK_HIGH (422, the Content Owner's threshold was reached and their action is refuse; do not deliver) and CONSUMER_RISK_UNAVAILABLE (503 + Retry-After; retry with the same Idempotency-Key and consumerGeoAttestId). Under riskAction: warn the same outcomes arrive as an additive riskWarning { code } on the 200 of preview, hold, reserve and order responses. The score is never returned. whoami.capabilities.buyerRiskScoringEnabled says whether scoring is live; while it is false the level behaves as checkout_attest. Sandbox keys never call the provider; consumer IP 203.0.113.77 returns CONSUMER_RISK_HIGH deterministically. See Territory enforcement → Buyer verification levels and the error playbook.

Webhooks: self-describing bodies, failure reasons, soft delete, rotation-safe samples#

  • Bodies say what they are. Every delivery body carries eventType (documented, but only sent as a header until now) and occurredAt; order events carry skuId, skuCode, quantity and fulfilledAt; order.keys_returned and refund.completed carry orderReference / orderReferences and keyIds. Deliveries send User-Agent: Avrix-Webhooks/1. Replays and test pings use evt_… ids like live events (replays were bare UUIDs).
  • Failure reasons. A failed attempt reports lastError on GET /webhooks/{id}/deliveries and GET /events (timeout, dns_private_address, connect_refused, http_503, …). responseStatus / the stored response body are only ever what your endpoint returned; a transport error no longer lands there. A succeeded delivery shows no nextRetryAt.
  • Deleting an endpoint keeps its history. DELETE /webhooks/{id} stops deliveries and removes the endpoint from the listing; its deliveries stay on GET /events and GET /webhooks/{id}/deliveries (meta.endpointDeleted: true).
  • Cursors at the head. GET /events returns meta.headCursor (the resume position, also at the head); make the first call without cursor (the guide's cursor=0 was never accepted). GET /catalog/changes at the head returns the cursor you sent instead of null.
  • Verifier samples. The TypeScript, Python and PHP samples check every v1= signature: during a secret rotation (t=…,v1=<current>,v1=<previous>) the old samples kept only the last one and rejected every delivery on the new secret.
  • Delivery throughput. Deliveries run through a bounded pool (at most 16 in flight, 4 to one endpoint) until the run's time budget; a test ping, retry or replay delivers only its own rows.
  • Small items. GET /availability?skuCodes= lists unknown codes in meta.notFound; GET /webhooks/egress-ips carries a policy text; GET /whoami-ip is limited to 60 requests a minute per IP.

Server-Timing on preview and orders; late sales recorded, not only alerted#

  • POST /orders/preview and POST /orders return Server-Timing with named phases (auth, idempotency, allocation, authority, term, geo, price, settlement, rpc, decrypt, billing, idempotency-commit, total, …). See Monitoring and support.
  • A delivery whose sale record was lost (the platform stopped between delivering the key and recording the sale) is now recorded within about five minutes instead of an hour, at the price it was delivered at. One found after its reporting period was finalized is recorded and held out of that period for a correction in the current one, rather than left unrecorded.

Preview and hold owe the commit nothing it would refuse#

  • Geo-mismatch policy on evidence. An agreement's refuse geo-mismatch policy now applies whenever the sale carries evidence (the checkout attest's country, else the IP lookup of the consumerIp), whether or not consumer geo enforcement is on: 422 CONSUMER_GEO_MISMATCH_POLICY_REFUSED on preview, hold and commit alike, with details.evidencedCountry and details.evidenceSource. Before, it ran only when enforcement was on, so a checkout pixel from another country than the declared one sold anyway. whoami reports the policy orders are judged under (refuse for an agreement that states none, with the new policyStated: false) instead of null.
  • Buyer IP at quote time. On a production key, POST /orders/preview and POST /orders/hold refuse a body without the buyer IP (integrationOrderContext.consumerIp or consumerGeoAttestId) with the same 422 VALIDATION_FAILED POST /orders answers. whoami.requiredDeclarationsByOperation lists it for preview and hold.
  • commitRequirements.missing on preview and hold names every field the commit will still refuse without (payment-time fields such as paymentProcessorReference, checkoutSessionId, salesPriceNetMinor), with a COMMIT_FIELDS_MISSING warning on preview.
  • Hold replay. Replaying POST /orders/hold with the Idempotency-Key of a released, consumed or expired hold answers 404 HOLD_NOT_FOUND with details.holdState instead of the dead hold as live; a live hold replays with its current expiry.
  • Hold id naming. The hold response also carries checkoutHoldId (same value as holdId), and POST /orders accepts holdId as an alias of checkoutHoldId. The documented hold response now lists skuId, skuCode, quantity, orderReference, remainingSlots and geoWarning, which it already returned.
  • Extend by order id. POST /orders/{orderId}/extend accepts an ord_… id: a placed order is 409 ORDER_NOT_EXTENDABLE (only a hot-drop reservation, by its reservationId, can be extended), an unknown one 404.

orderReference replay is exact; one buyer confirmation per cart#

  • A repeated orderReference replays only when the requested quantity equals the live keys already fulfilled under it. A smaller quantity used to return a subset of the original keys and send a second order.fulfilled; it is now 409 ORDER_REFERENCE_CONFLICT, like a larger one. A replay (orders, bulk lines, keys/pull, keys/export, fulfil) sends no webhook and records no second sale.
  • Parallel orders on one allocation no longer queue behind each other: the allocation is locked only for the capacity step, so a burst on one SKU answers ALLOCATION_EXCEEDED or NO_AVAILABLE_KEYS instead of 504 HOT_PATH_TIMEOUT.
  • A consumerGeoAttestId is spent in the same transaction as the keys. A refused or failed order leaves it usable for the corrected retry, and a cart-level consumerGeoAttestId on POST /orders/bulk covers every line of that cart (it used to be spent by the first line, so line 2 was refused CONSUMER_GEO_ATTEST_CONSUMED).

Strict bulk carts are all-or-nothing#

POST /orders/bulk with strict: true used to pre-check every line and then pull line by line, so a line refused at pull time (for example two lines of one SKU that together exceed the stock) left the earlier lines fulfilled. A strict cart now pulls every line before any line is billed, delivered or announced; a refused line releases what the earlier lines took and the request answers that line's code and status with details.strictCart (outcome, failedItemIndex, and a status per line). A refused line of a non-strict cart now reads type: "failed" instead of type: "fulfilled" with pulled: 0.

Refunds and returns: stable codes, quantity reporting, key disposition#

  • A second POST /refunds or POST /keys/return for a key that is already returned or refunded answers 409 KEY_NOT_RETURNABLE with details.keyId, details.keyStatus and details.businessModel (was 500 INTERNAL_ERROR). A key your account never pulled is 404 NOT_FOUND (was 400).
  • POST /refunds with quantity reports requested, returned and skipped[] (one { keyId: null, reason: "no_live_key" } per unit with no live key left) instead of silently refunding fewer keys. strict: true refuses the shortfall with 409 REFUND_QUANTITY_EXCEEDS_LIVE_KEYS and refunds nothing.
  • Both responses carry keyDisposition: "quarantined": refunded keys are never sold again while the allocation headroom is restored.
  • Keys from an order that failed on Avrix's side before they were delivered now go back to stock instead of being quarantined as if a buyer had returned them.

One HTTP status per error code on every order surface#

POST /orders/preview, /orders/hold, /orders/reserve, /orders, /orders/commit, /orders/bulk and /keys/pull now answer the status the error reference lists for each code. Changes you may see: FOOTPRINT_CURRENCY_NOT_DECLARED is 422 on POST /orders, /keys/pull and bulk (was 400); CATALOG_PRICE_MISMATCH and WHOLESALE_PRICE_MISMATCH are 409 on reserve (was 422); preview answers SALES_COUNTRY_MISMATCH, CONSUMER_GEO_MISMATCH_POLICY_REFUSED and CATALOG_PRICE_MISMATCH with their documented status instead of 404; a buyer-geo lookup outage on reserve is 503 CONSUMER_GEO_UNAVAILABLE (was 422). A registered code used as a message prefix is the code on the wire, so a spent buyer-network confirmation on /keys/pull or /keys/export answers 422 with its own code instead of 400 BAD_REQUEST. SKU_NOT_FOUND, ALLOCATION_NOT_FOUND, ALLOCATION_INACTIVE, SOLD_OUT and STORE_UNAVAILABLE are now documented and carry recoverable and doc_url.

Database and dependency outages are retryable 503 / 504#

A PostgREST schema reload, a dropped, reset or refused connection or an exhausted connection pool now answers 503 SERVICE_UNAVAILABLE with Retry-After on every route (a database that answers too slowly is 504 HOT_PATH_TIMEOUT), instead of 500 INTERNAL_ERROR. A 500 never echoes database text. X-Avrix-Sandbox-Simulate: service_unavailable rehearses the outage.

Client errors that answered 5xx or the wrong 4xx#

  • GET /refunds/{refundId}, GET /finance/api-sales/{transactionId} and POST /geo/attest/{attestId}/complete validate the id as a UUID: 422 VALIDATION_FAILED (was 500, 503 and 404).
  • POST /promotions/shares/{shareId}/accept and /decline for an unknown share: 404 NOT_FOUND (was 500).
  • POST /allocations/requests for an unknown or foreign grantId: 404 NOT_FOUND (was 400); a publisher-side gate is 409 CONFLICT with details.reason. The published example now uses grantId / requestedQuantity.
  • POST /orders/commit while hot-drop is off: 412 HOT_DROP_NOT_ENABLED, like reserve (was 410 RESERVATION_GONE, which now means a reservation that existed and expired).
  • Keyless fulfilment regenerate / revoke answered the undocumented code VALIDATION_ERROR; it is VALIDATION_FAILED.

details.consoleUrl pointed at app.api.avrix.io, a host that does not exist. It now points at the console (app.avrix.io). Footprint refusals link to Settings → Commercial (consoleAction: review_commercial_settings) and their fixItUrl is the same absolute link.

Idempotency records no longer hold keys or secrets#

A successful POST /orders, /orders/bulk, /orders/commit, /orders/{orderId}/fulfill, /keys/pull or /keys/export used to be cached for replay with its plaintext keys. The cache now keeps only keyIds; a replay with the same Idempotency-Key re-reads the same keys through the audited read-only path and answers exactly as before, or 503 KEY_DECRYPT_FAILED (retry the same key) if they cannot be re-read. POST /keys/pull and every fulfilled POST /orders/bulk line now also return keyIds. A replayed POST /webhooks omits secret and says secretRedacted: true. Expired idempotency records are deleted daily.

Webhook URLs: credentials and IPv4-mapped literals refused#

POST /webhooks and PATCH /webhooks/{id} refuse a URL with a username or password, and an IP-literal host in a private or reserved range in any spelling, including IPv4-mapped IPv6 (https://[::ffff:<IPv4>]/…) and NAT64, 6to4 and Teredo prefixes. Stored URLs are returned without any userinfo.

Authenticated responses are never publicly cacheable#

Every key-scoped Seller API response now sends Cache-Control: private, no-store (or private, no-cache when it carries an ETag) with Vary: Authorization, unless the route declares its own private policy. Key-free routes (/health, /openapi, /webhooks/egress-ips) keep their public policy.

GET /usage counts every response#

GET /usage aggregated the audit log, whose successful responses are sampled and whose reads are mostly absent, so a healthy key could read as a 99 percent preview error rate with no /catalog, /products or /finance traffic at all. It now reads the per-request call log: every response of the key owner's keys in the calling key's environment is counted once, successes and reads included; a denial thrown before a handler runs (missing scope, IP not allowed) is counted as an error as well. errors still excludes GET 404 lookup misses, reported as lookupMisses. Endpoints are labelled /v1/<path> whichever URL form served them.

GET /transactions carries the declared country and the settlement warnings for API sales#

API-model pulls listed salesCountryCode, detectedCountryCode and countryMismatch as null and warnings as empty however clearly the order had declared a country: the typed columns on the key pull were only written for wholesale and revenue-share pulls, and the sale row never received the evidenced country either. Every pull now records the declared country, the evidenced country (the buyer IP lookup, or the checkout attestation when only that ran) and the mismatch flag, and GET /transactions returns the same warnings as GET /finance/api-sales for the sale behind the pull (COUNTRY_MISMATCH plus the vat_* settlement codes). Rows written before this release fill from the sale row where one exists.

A declared VAT rate below the reference is flagged on every surface#

A sale that declares a tax rate below the platform's reference rate for the buyer's country (5 percent on a Dutch sale, say) still settles at the rate you declared — the platform never deducts VAT you did not charge — but it is no longer silent: the sale carries vat_declared_rate_below_expected. The settlement warnings[] that POST /orders already returned are now also returned by POST /orders/commit, each fulfilled POST /orders/bulk line and POST /keys/pull, and the same codes are persisted on the sale row and returned as warnings on GET /finance/api-sales and GET /activity next to COUNTRY_MISMATCH. Settlement arithmetic is unchanged. See Finance and settlement.

The activity feed sums to the statement#

GET /activity emitted each refund twice — the reversal ledger row appeared as a second sale entry with negative economics and stockMovement: +1, and the refunded sale appeared again as a refund entry — so the feed never summed to GET /finance/statements. sale entries are now the sale rows only; refund / chargeback entries are the reversal rows themselves (one per refund, negative economics, at the instant money moved); a new reinstatement kind (+1, positive economics) carries a won chargeback. Over any period the feed's sale + refund + chargeback + reinstatement economics equal the statement's grossSalesCents − refundedCents + reinstatedCents. Filtering with kinds= accepts reinstatement. Because the entry is the recorded reversal, it follows the refund by the settlement step that also adjusts the statement (seconds, not the refund response itself); GET /finance/api-sales flips adjustmentStatus at once. See Finance and settlement.

Geo attest failures are machine-readable and a store-server pixel is refused when it loads#

A supplied consumerGeoAttestId that cannot be used now answers one of three codes instead of VALIDATION_FAILED: CONSUMER_GEO_ATTEST_EXPIRED (details.expiresAt; the window is 10 minutes from POST /geo/attest), CONSUMER_GEO_ATTEST_CONSUMED (details.consumedOrderReference; one confirmation per order, a retry of the same orderReference may reuse it) and CONSUMER_GEO_ATTEST_INVALID (unknown, another key or account). A pixel loaded from the store's own server is refused at completion time with CONSUMER_GEO_ATTEST_INVALID (POST /geo/attest/{id}/complete answers 422; the image pixel returns but the attest stays incomplete), where before it completed silently and the store learned CONSUMER_IP_INVALID on the next call. See Territory enforcement.

Availability responses carry Server-Timing#

GET /availability and GET /availability/{skuCode} now return a Server-Timing header (db, redis, sellability, total, milliseconds) so a slow response can be attributed without a support ticket; requests above the platform threshold are also logged with the same breakdown. See Monitoring and support.

One per-country sellability answer#

sellableInCountry on GET /availability (?country=) now comes from the same order admission preview and commit run: territory, the catalog price, your selling footprint (country and the catalog currency), the agreement's currency terms and the contract's region locks. It can no longer be true for a country outside your footprint or one the agreement does not permit; blockedReason names the gate (FOOTPRINT_COUNTRY_NOT_DECLARED, FOOTPRINT_CURRENCY_NOT_DECLARED, CURRENCY_NOT_PERMITTED_BY_TERM, CURRENCY_NOT_PRICED_FOR_COUNTRY, SRP_MISMATCH_FOR_CURRENCY, REGION_LOCKED_FOR_CONTRACT join the territory and price reasons). The NO_TERRITORY_PRICING readiness blocker and the API_SKU_MISSING_TERRITORY_PRICING warning on GET /allocations now probe the countries in your footprint rather than the platform default, so they no longer contradict what you sell into. releases[].allowedCountries is sorted. The CURRENCY_NOT_PRICED_FOR_COUNTRY message names the currency the country is priced in, and a FOOTPRINT_CURRENCY_NOT_DECLARED refusal on a quote that declared no currency (the country is priced in a currency you do not sell in) now points at the Content Owner's territory pricing (details.recommendedAction: request_publisher_territory_pricing) instead of your currency settings.

Checkout holds are visible on availability, preview and the catalog list#

GET /availability (single and bulk) and POST /orders/preview now carry heldQuantity (keys inside live checkout holds right now, null if the hold ledger was unreadable) and sellableNow (min(allocationRemaining, inventoryAvailable) − heldQuantity). maxFulfillableQuantity and canFulfill are net of holds; available keeps its gross meaning. The expand=availability block on GET /products (and the snapshot) carries the same two fields advisorily. A hold is now granted only up to min(allocation headroom, inventory) − held, re-read on every request, so a hold never covers a key that is not in stock. With holds enabled the CDN window for GET /availability is 5 s instead of 60 s. See Checkout holds.

One checkout hold per cart, and an idempotent release#

A second POST /orders/hold for an orderReference that a live hold already covers is now refused with 409 HOLD_EXISTS (details.holdId, details.expiresAt) instead of being granted a second time and taking capacity twice. DELETE /orders/hold is idempotent: it answers 200 with data.released true when the call freed the hold and false when the hold was already released, consumed or expired; it no longer answers 404. See Checkout holds.

A private consumerIp is refused when the request is parsed#

consumerIp — inside integrationOrderContext and at the top level of POST /orders/preview — is now checked for shape and for private, loopback, link-local and carrier-NAT ranges when the request is parsed, on every surface, and refused with 422 CONSUMER_IP_INVALID (details.issues names the field). Until now the top-level preview field had no shape check and a private address inside the context was accepted whenever the buyer-network evaluation did not run (for example when a geo attest supplied the buyer's address), which is what the docs already said was refused. The sandbox's documentation-range magic addresses are unaffected.

A sale country declared twice must agree#

countryCode (top level) and integrationOrderContext.salesCountryCode are one declaration on POST /orders/preview, /orders/hold, /orders/reserve and /orders. Send either. If you send both and they differ, the request is now refused with 422 SALES_COUNTRY_MISMATCH (details.countryCode, details.salesCountryCode); until now the context value won silently, so the line could be priced for one country and settled for another. Equal values (case-insensitive) still merge as before.

The buyer-network confirmation is checked after the order admission and spent only on delivery#

On preview, hold and commit the geo attest (consumerGeoAttestId) is now checked after the shared order admission and before the buyer-network verdict. A missing, incomplete or store-server-completed confirmation no longer hides FOOTPRINT_*, CATALOG_PRICE_NOT_SET, SALES_CHANNEL_NOT_PERMITTED or a price refusal: you see the blocker you can fix first. On commit the attest is spent only once every other gate has passed and the key is about to be delivered, so a commit refused for currency, channel, price or stock leaves the confirmation usable for the corrected retry. CONSUMER_IP_INVALID for a pixel completed from the store server is unchanged. See Territory enforcement.

whoami publishes the required declarations per operation#

GET /whoami now returns requiredDeclarationsByOperation: for every operation that takes an integrationOrderContext, the complete list of fields that operation refuses without, computed for the calling key. On a production key the committing operations (orders, commit, bulk, keysPull, keysExport) list schemaVersion, the four settlement declarations, the commercial evidence (currencyCode, salesPriceNetMinor, priceIncludesTax, salesTaxAmountMinor, paymentMethodFamily, paymentProcessorReference, checkoutSessionId, salesCountryCode, consumerIp) and any per-key strict profile paths; preview, hold and reserve list only salesCountryCode. The list is built from the constants the validators read, so it cannot name fewer fields than commit refuses — the previous requiredDeclarations named four fields while a production POST /orders refused for eleven. requiredDeclarations is unchanged (the settlement declaration, sandbox and production alike). See Order context.

Preview, hold and commit share one order admission#

POST /orders/preview and POST /orders/hold now run the same admission POST /orders runs, on the integrationOrderContext you send: the declared currencyCode and salesChannel are checked against your selling footprint and the agreement, region locks are applied, and a price echo is compared when you send one. Until now preview quoted the catalog currency only and hold ran no admission, so a store on the preview → hold → charge → commit path could charge a buyer and only then learn the sale was not permitted (FOOTPRINT_CURRENCY_NOT_DECLARED, SALES_CHANNEL_NOT_PERMITTED). Both surfaces now refuse with the same code as commit, at 422 (previously some of these codes answered 404 on preview). Two visible changes: an API-allocation hold without countryCode / salesCountryCode is refused with SALES_COUNTRY_REQUIRED instead of being priced for a default country, and a quote in a permitted secondary currency now returns the reference-rate floor in that currency with no promo, which is what commit settles on. See Order preview § Errors and Checkout holds.

2026-09-21#

Buyer verification level per Content Owner#

Checkout-page confirmation was one platform-wide rule; it is now a per-connection choice each Content Owner makes. GET /whoami gains buyerVerificationByPublisher[] (publisherCompanyId, level, riskAction, note) and every GET /allocations row carries buyerVerification { level, riskAction }. The levels are declared_ip (no pixel; the declared consumerIp is the buyer evidence), checkout_attest (the platform default and today's behaviour) and checkout_attest_risk (checkout confirmation plus a risk score judged by the Content Owner's threshold and action). consumerGeoAttestRequired stays on both routes and is derived from the level, so an existing integration keeps working unchanged. Levels apply to production keys only. See Territory enforcement → Buyer verification levels.

Preview and hold carry the list-price promotion#

A promotion's priceEffect names two prices: what you pay per unit and what the vendor asks you to advertise. Until now POST /orders/preview and POST /orders/hold reported only the first — a live list_price promotion (the default) left promo: null and promoResolution: "none", so a store on the preview → charge → POST /orders path had to join GET /promotions/calendar on skuId and apply discountPercent to a country list price itself. Every quoted line now also carries listPromo (the live list_price or both promotion, same shape as promo) and advertisedUnitPriceCents (the list price with it applied), so the product-page was/now comes from initialUnitPriceCents vs advertisedUnitPriceCents and the checkout call is enough. unitPriceCents, promo, promoResolution and price binding are unchanged; advertisedUnitPriceCents is null on wholesale and revenue-share lines, whose price is your negotiated cost rather than the territory list price. When promotions overlap on one SKU, each axis now picks its own highest discount instead of the largest percent hiding the other. Share and deal detail products[] document currency_code next to base_price_cents, which is an own-region display price and never a shelf price for a sale country. See Promotions § Promo in the price and Order preview.

2026-09-19#

Webhook bodies are documented as delivered#

A webhook delivery is one flat JSON object: eventId, eventType and eventVersion (a string, "1") sit next to the event's own fields. There is no data wrapper and no envelope-level createdAt — timestamps are event-specific. Nothing changed on the wire; the documentation now matches it. The delivery format on Webhooks, every example in the Event reference and all of the OpenAPI webhook schemas describe that shape, and a replayed delivery's replay marker (sourceDeliveryId, originalEventId) is documented where it actually sits, at the top level.

Two bodies were described with fields that are never sent. sku.pricing_updated carries skuId, productId, publisherCompanyId, countryCode, priceCents, currencyCode, pricingMode, updatedAt, effectiveAt, previousPricing and newPricing — the guide previously showed skuCode and unitPriceCents. test.ping carries test, sentAt and endpointId. Both are now fully typed in the spec, as are the other single-emitter events, so a generated client sees the real fields. If you generated types from an earlier spec, regenerate them: the Webhook* types change from { type, createdAt, data } to the delivered shape.

One wholesale price field, one meaning#

pricePerKeyCents is the wholesale contract price of an allocation, and it now says the same thing on every surface that carries it — GET /allocations, catalog sharedSkus[] on GET /products and GET /catalog/snapshot, and wholesaleFromCents under expand=pricing. null means there is no wholesale price, and the field is never 0.

Under businessModel: api it is always null, together with currencyCode and currencyExponent: those sales settle as a share of the territory list price, so the number to show a buyer and echo on commit comes from GET /products/{productId}/pricing and the preview unitPriceCents, never from the allocation. An unpriced wholesale or pre_order grant reads the same way instead of reporting a free key, and wholesaleFromCents is the lowest priced wholesale allocation for the product — a 0 can no longer win that comparison. Allocations created without a price are stored that way too. If you mirrored the field, expect null where a 0 (or a stale wholesale figure on an API allocation) used to appear; nothing else about allocations, sellability or checkout changes. Catalog & allocations and Pricing authority carry the per-model table.

Snapshot and checksum now notice price changes#

A territory price change never moves a product's updatedAt — by design it travels as the pricing facet on GET /catalog/changes and as sku.pricing_updated. Until now the snapshot ETag and the checksum did not see it either, so a store revalidating GET /catalog/snapshot with If-None-Match after a price change was answered 304 and kept the old srpPriceCents, listPriceFromCents and pricing values.

Both surfaces now carry your change-feed position. The snapshot ETag is derived from (maxUpdatedAt, totalProducts, changesCursor), so it moves on every change the feed records, prices included; meta.changesCursor on the snapshot and changesCursor on GET /catalog/checksum are the same opaque position — persist it and pass it as cursor to GET /catalog/changes to receive everything that happened since, refetching only the facets named in changedFields. The checksum digest is unchanged and still covers product rows only. meta.maxUpdatedAt keeps its meaning: a watermark for GET /products?updatedSince=, which is a metadata and lifecycle delta, not a pricing one. Expect one full 200 on your first conditional request after this release, since every ETag changed once.

On GET /catalog/changes, meta.nextCursor is now the position of the last entry in the page whether or not the page was full (it is null only when the page was empty — keep the cursor you sent), and the new meta.hasMore says whether the page was cut at limit. The helper package follows: syncCatalogChanges accepts cursor, returns changedFields, nextCursor and hasMore, and syncSellableCatalog returns the snapshot's changesCursor. The recipe is on Catalog and allocations.

2026-09-17#

Order references are settled with the delivery#

A store order reference is now judged inside the same transaction that hands out the keys, under a lock held for your company and that reference. Two allocations of one company can no longer both fulfil the same reference, and a replay that asks for more than the original delivery is refused before any key moves. Nothing changes on the wire: a completed reference still replays its original keys, a partial top-up still answers 409 ORDER_REFERENCE_CONFLICT with the same message, and the error playbook entry still applies. Order references stay described on Idempotency.

Sandbox: one order-reference namespace per API key#

On the shared sandbox catalog every API key now has its own order-reference namespace. Two integrators who both send ORDER-001 each receive their own keys and each replays only their own delivery; a reference reused by another key is never treated as a replay of yours. The same scope applies to refunds: POST /refunds refuses key ids that were not delivered to the calling key with the usual "Key not found for this seller or not pulled" answer, GET /refunds lists only refunds of sales made with the calling key, and a refund belonging to another key answers 404. Production keys are unchanged: one company keeps one namespace. See Sandbox for the other per-key isolation rules.

Previews and holds carry the settlement declarations#

The Seller API helpers (@avrix/seller-api-helpers) now let previewCheckoutLine and createCheckoutHold send the same integrationOrderContext and consumerIp an order sends, so a preview or hold is admitted on the same basis as the order it precedes. Both take a single input object; callers of the older positional form update the call at their next upgrade. What the API requires has not changed. The quickstart and the checkout-hold example in Order lifecycle now show complete bodies, and the Order context guide explains the three mandatory declarations.

2026-09-10#

whoami names a missing registered country#

GET /whoami integrationReadiness.blockers gains STORE_COUNTRY_MISSING (recommended action register_company_country). It is raised when the seller company has no registered country on file. Orders are still accepted, but a sale whose buyer country cannot be confirmed settles against the store country's rate, and without one such sales are held out of settlement and appear on no statement. The country is recorded in the console, under Company settings, and is now asked during commercial setup; the blocker exists for companies that arrived by another route. It is listed before any catalog blocker, because nothing in the catalog can fix it.

whoami names locked countries#

integrationReadiness.blockers also gains REGION_LOCKED (recommended action review_publisher_region_locks), with a countries array naming the countries you declare that a Content Owner has locked under an in-force API agreement. Orders into those countries are refused until the owner lifts the lock; the seller cannot. The same locks are now disclosed on the agreement review before signature, with the agreement's currency rule and its five settlement terms, so a store no longer meets them on the first order.

2026-09-09#

Refusal details are on the wire, and pre-orders meet the same checks#

Three changes to how an API-model order is refused, none to what is refused.

ApiError.details now carries what the refusing check knows. A footprint refusal carries fixItUrl and the countryCode or currencyCode it saw. A secondary-currency floor refusal carries floorMinor. A consumer geo refusal carries declaredCountry and, when the buyer IP resolved, detectedCountry. The playbook promised these for some time; the body now delivers them, on POST /orders, POST /orders/bulk (per line, as details), POST /keys/pull and POST /keys/export.

A pre-order placed through POST /orders on a title in its pre-order window now meets every check a live order meets before it is accepted: the price bind, your footprint, the agreement's permitted currencies and channels, the Content Owner's region locks, consumer geo, and the tax declaration. It used to meet none of them, and a problem surfaced at release, after your customer had paid. A refused pre-order answers with the same code, status and body a refused live order would, 422 for a commercial boundary, not the 409 this path used to fall to.

PUT /me/footprint now requires at least one country and one currency, and writes both halves in one transaction. An empty footprint refuses every order, so the API refuses to store one, as the console always has.

GET /whoami data.footprint gains countriesWithoutReferenceRate: the countries in your footprint for which the platform holds no consumer tax reference rate yet. An order into one is accepted and the key delivered, but the sale is held out of settlement until the rate is entered, so it will not appear on a statement in the meantime. Check the list before selling somewhere new in volume.

A checkout attestation (consumerGeoAttestId) is spent on one order. Presenting it on a second order is refused as VALIDATION_FAILED with the message that it was already used; a retry of the same orderReference may reuse it.

Your declared currencies are now checked on every order#

Your footprint has always had two halves, the countries and the currencies you sell in. Only the countries were enforced. A sale in a currency you had not declared went through on the strength of the Schedule and the catalog alone, which is not what GET /me/footprint and the Commercial configuration screen said would happen.

A sale currency absent from your footprint is now refused with FOOTPRINT_CURRENCY_NOT_DECLARED on POST /orders, POST /orders/bulk, POST /keys/pull and POST /keys/export. It is a 422, it is recoverable, and the error details carry a fixItUrl to the screen that fixes it.

Both footprint halves are checked ahead of the Schedule and the catalog, because they are the only boundaries you can fix alone. The country is named before the currency when both are missing.

If you sell in currencies you have never declared, declare them before this reaches your production keys. GET /whoami reports data.footprint with both lists, and it is the fastest way to check.

Declaring a currency does not price it. The Schedule still has to permit it and the title still has to carry a price for the country, so this is the first of three checks, not a replacement for the other two.

Quotes and holds no longer need a tax declaration#

POST /orders/preview, POST /orders/hold and POST /orders/reserve no longer require integrationOrderContext. Previously an API catalog quote that omitted the settlement declarations was refused 422 TAX_DECLARATION_REQUIRED, which made price discovery circular — the preview is how you learn the price you would have to declare — and forced a storefront to know its final tax before it had created the payment session. The published preview request schema always listed only quantity as required; the implementation now matches it.

Nothing about settlement changed. The declarations are still required wherever a key is delivered — POST /orders, POST /orders/bulk, POST /orders/commit, POST /keys/pull and POST /keys/export — in sandbox and production alike, still refusing with TAX_DECLARATION_REQUIRED, SALES_COUNTRY_REQUIRED or SALES_CHANNEL_REQUIRED before anything is delivered. A reservation taken without them can still be refused at commit, so send them as early as you have them.

Send the context on a preview and it now returns the settlement object the response schema documents — basis, applied rate and rate reason — so you can see how the sale would split before charging. Omit it and you still get the price, without that object.


2026-09-08#

Contract: named currency lists and named marketplaces#

A Commercial Schedule can now state its permitted currencies as a named list rather than a rule, and can admit named marketplaces alongside your own storefronts. Both are additive: an agreement that states neither behaves exactly as before.

GET /whoami reports them in permittedCurrenciesByPublisher. A named list arrives as currencyMode: "custom" with a currencyDetail object mapping each permitted currency to the countries it may be sold in, or to "territory" for the whole granted territory. A currency the list does not name is refused with CURRENCY_NOT_PERMITTED_BY_TERM however the SKU is priced, and one named for other countries than the sale's is refused with details.reason: "currency_not_permitted_for_country".

Named marketplaces arrive as permittedChannels: "own_storefront_plus_named_marketplaces" with a marketplaceSlugs array. Declare one as salesChannel: "marketplace:<slug>", spelled as the array spells it; every other marketplace is still refused, and SALES_CHANNEL_NOT_PERMITTED now lists every channel that would have been accepted in details.permittedChannelList.

Read the boundaries before you send an order: Currency and FX explains both, and Order context covers the channel declaration.


2026-09-06#

Breaking: salesChannel is required on API catalog orders#

Every API catalog order must now declare integrationOrderContext.salesChannel: one of web, mobile_app, partner_embed, or marketplace:<slug>. Omitting it is refused with 422 SALES_CHANNEL_REQUIRED, and a channel your agreement's Commercial Schedule does not permit with 422 SALES_CHANNEL_NOT_PERMITTED. Under the default own_storefront, the first three are permitted and any marketplace:<slug> is refused.

This follows the Key Delivery article, which states the grant is to sell to an end user through a permitted channel and excludes resale, sub-distribution and third-party marketplace listing. An operator of a marketplace may hold the agreement in respect of its own first-party storefront.

Contract: commercial boundaries are enforced at order time#

Four new refusals, each with an entry in the error playbook: FOOTPRINT_COUNTRY_NOT_DECLARED, CURRENCY_NOT_PRICED_FOR_COUNTRY, CURRENCY_NOT_PERMITTED_BY_TERM and SRP_MISMATCH_FOR_CURRENCY. A fifth, CONSUMER_GEO_MISMATCH_POLICY_REFUSED, applies only where your agreement sets the geo-mismatch policy to refuse.

GET /whoami reports the boundaries that apply to you, so you can check before sending an order. Currency and FX is new and explains which currency a sale may be in and how a secondary currency is checked.

Contract clarification: secondary-currency sales reach the floor; declaration codes on production keys#

A POST /orders whose integrationOrderContext.currencyCode is not the catalog list currency is now a secondary-currency sale rather than a CURRENCY_MISMATCH: it is checked, in order, against your footprint, the Commercial Schedule's currency mode, the SKU's authored currencies and the reference-rate floor, and settles on your expectedUnitPriceCents in that currency. CURRENCY_MISMATCH keeps one meaning, a currency that disagrees with an active checkout hold. Separately, a production key that omits salesTaxRatePercent, salesPriceGrossMinor or salesChannel now receives the documented 422 TAX_DECLARATION_REQUIRED or 422 SALES_CHANNEL_REQUIRED instead of a generic VALIDATION_FAILED; sandbox keys already did.

Contract: every error code the API returns is named by the OpenAPI schema#

The ApiError.code enum listed 56 of the 84 codes that carry a published entry in the error playbook. The generated SDK derives its code union from that enum, so 28 codes could not be type-matched by an SDK consumer: the seven commercial boundary codes above, and 21 older ones including HOLD_NOT_FOUND, RESERVATION_GONE, HOT_PATH_TIMEOUT and SERVICE_UNAVAILABLE. All 84 are now in the enum and the union. TAX_DECLARATION_REQUIRED gains the playbook entry and doc_url it never had.

A check keeps the enum equal to the documented set from here on, so this cannot drift again unnoticed.

Additive: preview quotes the settlement, orders return warnings#

POST /orders/preview returns a settlement block computed by the same calculator the commit path uses, so you can show a customer what a sale settles at rather than a gross figure. POST /orders returns warnings[]: what the settlement noticed but did not refuse over. A warning never changes the status code.

Additive: whoami reports each Content Owner's commercial boundaries#

GET /whoami gains data.permittedCurrenciesByPublisher and data.geoPolicyByPublisher, one entry per in-force API agreement: the currency mode, the permitted channels, the geo-mismatch policy, and any per-SKU tightening the Content Owner has set. The last of those has no other route to you, because a Content Owner sets it alone, so previously the first sight of one was a 422 on a live order.

data.footprint is also now in the OpenAPI schema and the SDK types. It has been in the response since the footprint endpoints shipped, but the schema never described it.

Additive: read and write your selling footprint#

GET and PUT /api/seller/v1/me/footprint, behind a new seller:account:manage scope. Opt-in at key creation, and the one scope legacy keys do not receive: your footprint is what your sales are settled against, so an existing key does not silently gain the ability to change it.

Additive: per-transaction finance reads#

GET /finance/api-sales/{transactionId} returns one sale as the ledger recorded it. The finance CSV gains the settlement columns, appended so existing column positions do not move.


Contract: no rate-limit tiers; hold fallback; key recovery#

  • Rate limits: the per-company tiers (standard / high / premium / enterprise) are gone. Production keys are IP-allowlisted and are not rate limited by the API; sandbox keys share one flat abuse cap (600 writes / 1,200 reads / 12,000 cached reads per minute). GET /whoami now reports data.key.rateLimited instead of rateLimitTier.
  • Checkout holds: default TTL is 30 minutes (was 5) to match a hosted PSP checkout. A lapsed hold no longer fails a paid order: POST /orders with an expired / released checkoutHoldId commits as a plain order and reports checkoutHold: { holdId, status: "expired", committedWithoutHold: true }. HOLD_MISMATCH / HOLD_NOT_FOUND carry recommendedAction: fallback_to_post_orders_without_hold.
  • Pre-orders transact: check_pull_contract_authority now uses the seller-aware sellability predicate, so a company with seller_api_preorder_enabled can preview / hold / commit a launchPhase: pre_order product (reserved as a pre-order); readiness, availability and the transact paths finally agree.
  • Deprecation headers (mechanism): responses to requests pinned to a contract date marked deprecated carry Deprecation, Sunset and Link once a sunset date is published (off by default, per the versioning policy).
  • Checkout holds are capped by stock: the hold counter is seeded from min(allocation headroom, keys in stock) minus in-flight holds. A SKU with few keys and a large ceiling no longer grants holds that cannot be committed, so buyers are refused at the hold instead of paying and being refunded after NO_AVAILABLE_KEYS.
  • Territory reads never cache an error: a failed region-countries read is retried once and, if it still fails, left out of the cache instead of being served as "no territorial country coverage" for ten minutes.
  • Order lookups at catalog scale: GET /orders?orderReference=, GET /orders/{orderReadableId}, POST /orders/recover-keys and the firstOrderCompleted gate of GET /integration/status loaded the seller's whole grant list and filtered pulls with one IN (…) over every grant id. Past a few hundred allocations that request was refused and every lookup answered 404 NOT_FOUND. Lookups now start from the (indexed) order reference and verify only the grants it points at; grant scans are chunked. Found with a 500-product sandbox catalog.
  • GET /events keyset cursor: responses carry meta.nextCursor (keyset on createdAt,id) and the cursor query parameter is honoured. Paging by since alone could not cross a burst of more than one page of events sharing a timestamp (a poller re-read the same page forever); since now also keeps microsecond precision instead of truncating to milliseconds. meta.nextSince is unchanged for older clients.
  • Paused agreements answer CONTRACT_NOT_ACTIVE: POST /orders/preview, /orders/hold, /orders/reserve, /orders and /keys/export no longer report a SKU whose agreement is paused as SKU_NOT_FOUND / NOT_FOUND (400/404). They answer 403 CONTRACT_NOT_ACTIVE with the same code in previewError / holdError / reserveError / skuResolve, so a paused agreement is not mistaken for a catalog problem. GET /orders and key recovery keep working for orders whose grant is paused.
  • Hot-drop commit parity: POST /orders/commit now returns keyIds (key UUIDs, same order as keys) like POST /orders, so refunds and key returns can target the delivered keys of hot-drop sales.
  • Key recovery: new POST /orders/recover-keys (scope seller:keys:pull) returns the live keys and keyIds already sold under an orderReference for stores that lost the POST /orders response. Never pulls new inventory; GET /orders still never returns plaintext.

Fixes: order lookup consistency and call-log metering#

  • GET /orders?orderReference= right after POST /orders: the sandbox key stamp on the pulled keys is now written before the order response is sent. A store that looks the order up the moment checkout returns no longer gets 404 NOT_FOUND for an order that exists (loop case D-03).
  • Usage metering: every terminal response of POST /orders, /orders/bulk, /orders/cancel, /keys/pull and the other inline-auth routes now produces exactly one api_call_log row; successful orders were previously missing from GET /usage and the admin API activity views. Routes behind the auth wrapper no longer log error responses twice.

Fixes: price changes now reach sellers#

  • sku.pricing_updated was never sent. The publisher-side SKU price writer looked the product up through a column that does not exist, so since June no console price edit produced the webhook, the pricing facet on GET /catalog/changes, or the seller pricing-cache drop. Fixed: the product is resolved through the same RPC the Seller API uses.
  • Release-level price edits now notify too. Prices written on the region-release grid (console grid, CSV import, Steam price sync, price templates, copy-from-release) cascade to every SKU under that release; sellers now receive one sku.pricing_updated per SKU and country written, the product is listed on /catalog/changes with changedFields: ["pricing"], and GET /products/{id}/pricing is served fresh. Tier and scheduled-tier changes are a follow-up.

Fixes: refund callback validation detail#

  • POST /refunds: a request that omits type is now refused with details.issues[0] = { field: "type", message: 'type is required: "refund" or "chargeback"' } instead of the generic "Invalid option" text that a wrong value also produces. A refund without refundReference (or a chargeback without chargebackReference) keeps pointing at that field. Both shapes are documented as 422 examples on the route.

2026-09-05#

Clarification: tax declaration is required on every API catalog order#

GET /whoami now returns requiredDeclarations and requiredDeclarationsNote for every key, not only the sandbox catalog block. API catalog orders without salesTaxRatePercent and salesPriceGrossMinor are refused with 422 TAX_DECLARATION_REQUIRED before a key is delivered. INTEGRATION_ORDER_CONTEXT and the OpenAPI IntegrationOrderContext description match that; the fields are no longer described as optional audit extras.

Contract: finance sales carry the settlement the Platform applied (additive)#

GET /finance/api-sales and GET /finance/statements now return a settlement block on every sale, plus entryType and reversesTransactionId. Additive: no existing field changed meaning or shape.

Until now the only tax figure on a sale was taxMetadata, the echo of what your store declared at order time. That is still there and still unvalidated, but it is no longer the whole story. The Platform measures your declaration against a dated reference rate, caps it, and settles the revenue share on the net. settlement is what that produced:

  • appliedRatePercent and declaredRatePercent, so you can see when the cap bound;
  • rateReason, which says WHY that rate applied. fallback_store_country means the declared consumer country was not corroborated, so the sale settled at your own registered country rate;
  • evidenceRank: 1 a checkout attestation, 2 the consumer IP agreeing with the declaration, 3 the declaration alone;
  • vatMinor and netMinor, the deduction and the base the share was computed on.

settlement is null for a sale that predates the settlement basis, or one quarantined before it could be settled. It is stated as absent rather than as zeroes, because a row of zeroes reads as "no tax was due".

Contract: a refund is now an entry, not a status (behaviour change)#

A refunded sale keeps its own row and gains a second row with negated amounts, entryType: "sale_reversal" and reversesTransactionId naming the sale it undoes. It is dated when the refund was declared, so it falls in the period the money came back in rather than the one the sale was made in.

If you total sales yourself, read this. Statement buckets already account for it: grossSalesCents counts sale entries only, refundedCents is what the reversal entries took back, reinstatedCents is what won chargebacks restored, and netSalesCents includes both movements. If you sum salePriceCents across GET /finance/api-sales yourself, filter on entryType == "sale" or the reversals will net out of your gross.

2026-09-03#

Contract: GET /activity is now the settlement feed#

  • GET /activity returns settlement entries (sale +1, refund / chargeback −1, custody-only pull +1, keyless reveal 0) with a keyset cursor, from / to, kinds, promoId, counterparty and orderReference filters and format=csv. Each entry carries the counterparty, the promo reference, the buyer-country evidence and the economics, so month-end close needs one cursor instead of joining /finance/api-sales, /transactions and /refunds.
  • The previous merged shape (kind: transaction | webhook_delivery, payload) is still returned when kinds is limited to those legacy kinds, for one release. Webhook deliveries live on GET /events and GET /webhooks/{id}/deliveries.
  • See Finance and settlement § One activity log.

Privacy: the buyer IP is resolved, then discarded#

  • integrationOrderContext.consumerIp is still required on production checkout and still drives the territory cross-check, VPN / hosting block and sanctions screening — but it is no longer stored. Sale, pull and fulfilment rows keep the resolved country (detectedCountryCode, countryMismatch) and consumerIpHash, a peppered truncated sha256. GET /finance/api-sales and statements lines therefore return integrationOrderContext.consumerIpHash instead of consumerIp; rows recorded before this change carry consumerIpRedacted: true.
  • The address captured by the optional checkout-page attest pixel is cleared automatically 7 days after the attest expires.
  • See Data handling.

Contract: PRODUCT_NOT_SELLABLE explains itself (additive)#

  • details now carries reason (PREORDER_NOT_OPEN | PREORDER_CLOSED | PREORDER_DISABLED | LIFECYCLE_NOT_LIVE), productId, launchPhase, preorderStart, preorderEnd, releaseDate where known, and a recommendedAction (wait_for_preorder_window, wait_for_release, request_preorder_capability, delist_sku) on POST /orders/preview, POST /orders and POST /keys/pull.
  • A pre-order becomes its release in place, so the same skuId turns sellable at the instants given — no successor product to look up. Status codes are unchanged (404 on immediate pulls, 422 on pre-order acceptance) and are now both stated in the error reference.
  • Error responses whose cause the key-owner company can fix in the Console now carry details.consoleUrl (absolute, scoped to that company) and details.consoleAction (review_partner_contracts, review_allocations, manage_api_keys, complete_kyb, top_up_wallet, review_partner_catalog). See Error reference § The error envelope.
  • POST /orders and POST /keys/pull no longer flatten territory, activation, price-guard and geo failures to { pullError }: the structured details preview already returned (skuId, countryCode, allowedCountryCodes, declaredCountry / detectedCountry, …) are now present on commit too. pullError is unchanged.

Contract: declared vs detected buyer country on sale rows (additive)#

  • GET /finance/api-sales and GET /finance/statements lines carry detectedCountryCode (resolved from the buyer IP by the geo gate at pull time), countryMismatch and warnings (COUNTRY_MISMATCH) next to the declared customerRegionCode. GET /transactions rows carry salesCountryCode, detectedCountryCode, countryMismatch, warnings.
  • The api-sales CSV gains three trailing columns: customerRegionCode, detectedCountryCode, warning.
  • Values are null on rows recorded before this change or when geo ran in off mode; the raw buyer IP is never returned.

Contract: activation set returned with the key (additive)#

  • POST /orders (fulfilled, keyless and pre-order bodies), POST /keys/pull and POST /orders/{orderId}/fulfill now carry activation ({ type, countries }), the same SkuActivation object already on GET /allocations, GET /products/{id} SKUs and preview lines. Show "activates in" at delivery time without a second lookup.
  • The value is the guaranteed intersection across the SKU's inventory batches, not the batch the delivered key came from. It is resolved after the pull commits and degrades to { "type": "unknown", "countries": null } if inventory metadata cannot be read, never failing a delivered order.

Contract: promo provenance on quoted and billed prices (additive)#

  • POST /orders/preview lines and POST /orders/hold now carry initialUnitPriceCents (catalog list price), promo (sourceType, sourceId, discountPercent, priceEffect, startDate, endDate, or null) and promoResolution (applied | none | unavailable) next to the existing unitPriceCents, which stays the effective figure to echo as expectedUnitPriceCents.
  • GET /finance/api-sales and GET /finance/statements lines carry initialSalePriceCents and promo (sourceType, sourceId) so a discounted line can be attributed to the share or deal that caused it.
  • Fix: POST /orders/hold previously bound the list price while preview quoted the promo price, and a hold or price-commitment snapshot could have the promo applied a second time at POST /orders. Holds now bind the effective price, snapshots are compared as-is, and the sale row records the price the store was quoted.
  • See Promotions § Promo in the price. The scheduled discount calendar (GET /promotions/calendar) is documented there as shipped rather than roadmap.

2026-08-30#

Contract — whoami.settlement.invoiceWithinDays is now always null (value change, schema unchanged)#

  • GET /whoami previously reported invoiceWithinDays: 7 for automated_invoice settlement as a committed invoicing SLA. The platform does not automate invoice issuance: report approval accrues the share into the running balance and the vendor raises the commission invoice as a separate, deliberate act, so no invoicing deadline can honestly be committed. The field now returns null in every mode.
  • No wire-format change per Versioning and compatibility: the field is neither removed nor renamed, its schema has been nullable since launch (prepaid_wallet and report_only already returned null), and clients were already required to handle the null case. Treat null as "no committed invoicing latency"; the field is reserved for a future committed SLA. If your month-end close automation branched on the number, key it off report.ready / invoice.created webhooks instead of a fixed day count.

2026-08-29#

Contract — GET /partners reports paused agreements truthfully (additive)#

  • Agreements can now be paused (suspended but signed, governing, and resumable). The contracts summary reports this state instead of misfiling it: a paused MCA returns mcaStatus: "paused" (previously "missing"), and a paused BMA appears in the new pausedBmaTypes array (previously listed under pendingBmaTypes as if never signed).
  • Both changes are additive per Versioning and compatibility: ignore the enum value and field if you do not handle them. While paused, pulls and orders under the agreement are refused; do not prompt a re-sign, the agreement resumes in place.

2026-08-24#

Contract — pre-order gates every commercial stage and fails closed#

  • POST /orders/hold and POST /orders/reserve now apply the same lifecycle/pre-order gate as preview and commit: a pre-order-phase SKU (with the capability off) or a discontinued SKU rejects with PRODUCT_NOT_SELLABLE before any hold or reservation is taken, instead of only failing later at commit.
  • On the enabled path, acceptance is decided by the effective window (preorderStart / preorderEnd / preorderUnlocked) — outside the window the order rejects; it is never converted into a silent live pull. Commit now honours the capability the same way preview does.
  • Unverifiable pre-order state is a retriable 503 PREORDER_STATE_UNAVAILABLE on every path — including inside the key-pull transaction, which previously proceeded to reveal keys when the state lookup found nothing. Retry-After is now consistently 5s (the pull path used to say 2s while the docs and preview said 5s).
  • whoami.capabilityDetails.preorder.verifiedAt is now stamped by the modern awaiting_release acceptance path, not only the legacy key-locking reserve.

Contract — price binding locks the price, not the offer#

  • A priceCommitment token or checkout hold keeps honouring the previewed price for its window, but no longer lets a commit settle into a country the publisher just de-listed: if the sale country's price entry or territory is removed after preview, the bound commit fails closed (422 CATALOG_PRICE_NOT_SET / territory rejection). Unbound commits already failed closed on any price change (CATALOG_PRICE_MISMATCH).
  • POST /orders/hold and POST /orders/reserve now compare your expectedUnitPriceCents echo against the promotion-adjusted price — the same figure preview returns — instead of the raw list price, so an active promotion no longer produces a spurious CATALOG_PRICE_MISMATCH.
  • Platform territory edits invalidate cached territory snapshots immediately instead of after the cache TTL.

Contract clarification — the catalog delta feed covers unshare and partial delists#

  • Unshare now emits on GET /catalog/changes: removed when the revocation ends your catalog access to the product (it also drops from GET /products / snapshot), or updated with changedFields: ["availability"] when whole-catalog sharing keeps it browse-visible but its SKUs stopped being sellable.
  • Release- and SKU-level delists that leave the product live emit updated (availability) so mirrors refetch instead of selling a dead offer. Full delist and archive keep emitting removed.
  • Emission table added to Catalog and allocations.
  • Unshare now lands immediately: cached catalog/allocation reads for the affected seller are invalidated and open checkout holds / hot-drop reservations on the revoked SKUs are cancelled best-effort (commit re-checks the share and fails closed regardless).

2026-08-20#

Contract — 2026-09-01 becomes the stamped default automatically on that date#

  • The stamped default contract for unpinned requests flips to 2026-09-01 at 2026-09-01 00:00 UTC — no deploy, no separate announcement. From then an omitted strict on POST /orders/bulk defaults to true (whole-cart atomicity). Pin X-Avrix-Api-Version: 2026-04-29 or send strict: false explicitly to keep partial success.
  • POST /orders/bulk responses now echo meta.contractDate and meta.strict so the effective behavior profile is visible in the payload, not only the X-Avrix-Api-Version header.
  • All bulk examples now lead with explicit strict: true (and the example payloads were corrected to the real request shape: items, item-level orderReference).

2026-08-17#

Contract — stock split, catalog export, lifecycle events#

  • GET /availability adds dedicatedAvailable, sharedPoolAvailable (sum stays inventoryAvailable), plus backorderEligible / backorderIneligibleReason.
  • POST /catalog/exports → 202 { exportId }; poll GET /catalog/exports/{exportId} for a gzip NDJSON artifact (checksum, expiry, signed URL). catalog.export_ready fires on completion. 410 EXPORT_EXPIRED after the artifact TTL.
  • redemption.expired fires when a keyless link passes expiresAt. product.delisting_scheduled fires only when archived_at is in the future.
  • refundPolicy (platform default, source: "platform") is echoed on GET /allocations and GET /products/{id} as well as GET /whoami.
  • GET /platforms adds version and updatedAt — poll version for registry drift.

Contract — durable preorder/backorder fulfill and settlement promotions#

  • POST /orders can accept a catalog pre_order SKU against allocation headroom when whoami.capabilities.preorderEnabled is true (awaiting_release). Customer-order backorderOnUnavailable creates awaiting_stock only when backorderEnabled is on and the vendor grant allows request_mode_backorder; otherwise BACKORDER_NOT_ALLOWED.
  • Inventory arrival emits order.ready. Reveal keys with POST /orders/{orderId}/fulfill (seller:orders:fulfill, also seller:keys:pull / seller:orders:write in v1). Cancel releases headroom.
  • Promotions add priceEffect (list_price default, settlement_price, both). Catalog pricing stays list. Preview/commit settlement drops only for settlement-affecting windows. GET /promotions/calendar lists live/upcoming windows.

Contract — consumer geo monitor/enforce and reserve/hold gates#

  • CONSUMER_GEO_UNAVAILABLE is now 503 with Retry-After (was 422). Retry the same Idempotency-Key. Business denials (CONSUMER_GEO_MISMATCH, CONSUMER_IP_HIGH_RISK, CONSUMER_IP_REQUIRED, CONSUMER_IP_INVALID) stay 422 and include declaredCountry / detectedCountry — never the raw buyer IP.
  • During monitor mode, successful preview / reserve / hold / commit responses may include additive geoWarning: { code, enforcementDate? }.
  • POST /orders/reserve and POST /orders/hold now run territory + consumer-geo gates on API-model allocations. Hold accepts integrationOrderContext.
  • GET /whoami adds capabilities.consumerGeoMonitorEnabled.
  • Consumer geo enforce is the default for production keys. Sandbox keys stay off. A missing buyer IP returns 422 CONSUMER_IP_REQUIRED; missing geo data returns 503 CONSUMER_GEO_UNAVAILABLE.

2026-08-12#

Contract — new opt-in date 2026-09-01 (bulk strict default)#

  • Added contract date 2026-09-01: POST /orders/bulk with omitted strict defaults to true (whole-cart atomicity). The stamped default stays 2026-04-29 (partial success) until a future announced rollout — pin via X-Avrix-Api-Version: 2026-09-01 or dry-run with next. Responses now echo the effective contract date.
  • Recommendation unchanged: send strict explicitly on every bulk cart so defaults never affect you. See Versioning and compatibility.

2026-08-10#

Documentation — Journey IA and gap closure#

  • Reordered the public docs sidebar into a verb-shaped integration sequence (Welcome → Get started → Connect a partner → Sync your catalog → Sell an order → Stay in sync → Operate → Go live → Reference). Section labels carry no numeric prefixes; order is the reading spine.
  • Added guides: OAuth tokens, Partner onboarding, Promotions, API key management.
  • Filled endpoint coverage on existing guides (regions, transactions, media download, keys pull/export, bulk orders, reservation extend, webhook event feed / management).
  • Added CI guard verify:docs-endpoint-coverage so every OpenAPI operation maps to a published guide (or an explicit allowlist).

2026-08-07#

Documentation — Wave 3 (precision remediation)#

Contract notes reflected in guides (behaviour unchanged; docs aligned to runtime / OpenAPI):

  • Catalog sync: GET /catalog/changes?since= is exclusive of since; paginate with limit (no nextCursor); wire shape is data.changes[]. No published tombstone retention — cold-start on checksum drift. Checksum covers visible product IDs + updated_at (sha256-sorted-product-rows-v1); treat digest change as a cold-start signal.
  • Allocations cache: published ~60s TTL; orders rate class.
  • Fulfilment: deferredReveal when immediateFulfilment: false; persist keyIds from POST /orders (authoritative); GET /orders never returns plaintext.
  • Returns: technical eligibility = owned + status revealed (quarantine; not redeemed) — no invented calendar window.
  • Finance: named endpoints /finance/summary, /finance/api-sales, /finance/invoices; settlement cadence agreement-dependent; chargebacks via refunds.
  • Versioning: clients MUST ignore unknown fields and enum values; deprecations list Sunset when scheduled (no invented fixed-day SLA).
  • Rate limits: exact headers X-RateLimit-Limit / Remaining / Reset + Retry-After; default tier standard; budgets per company (keys share); upgrade via Avrix contact.

2026-08-06#

Documentation — Wave 2#

  • Published dedicated guides: event reference, idempotency, creating orders, checkout holds, hot drop, fulfilment/keys, integration tutorial, overview, commercial model, glossary, finance, reconciliation, security, rate limits, data handling, monitoring, and polling recovery.
  • Light refresh of key return policy (chargeback statuses and quarantine eligibility).

Partner note — environment-aware API key prefixes#

Newly minted Seller API secrets encode key type in the token prefix:

Key typeExample prefix
Live (production)avrix_sk_live_…
Sandboxavrix_sk_sbx_…

Authentication remains hash-based. The key’s environment field and Console badge remain authoritative. Legacy plain avrix_sk_… secrets continue to work until rotated. Placeholders in these guides use avrix_sk_sbx_your_key_here.


2026-08-05#

Documentation — Wave 1#

  • Portal guides for authentication, catalog and allocations (four-gate model), order lifecycle, webhooks (signature verification), error reference anchors, and sandbox-to-production cutover.
  • Mermaid diagrams and Note / Warning admonitions enabled in the public docs renderer.
  • PSP-neutral checkout language (“your PSP”) standardised across published order guides.

Earlier#

Partner-facing contract history remains on Versioning and compatibility.

What links here

Published guides that link to this page.

Search docs

Search documentation…