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:
| Type | Meaning | Can it affect a running integration? |
|---|---|---|
Breaking | An existing request stops working as it did. Released only behind a contract date, which the heading names | Yes, once you pin that date |
Changed behaviour | An existing request gets a different status, error code or field. Released only behind a contract date, which the heading names | Yes, once you pin that date |
Deprecated | Still works, with a replacement and, when scheduled, a sunset date | Not until the sunset |
Added | New operation, field, parameter, event or header | No |
Fixed | The API, the reference, an SDK or the Postman collection did not do what the documentation said, and now does | Only where the entry says |
Documentation | A guide said something wrong or unclear; the API did not change | No |
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(andallocation.updatedon approval) can be rehearsed. Approvals need your store's isolated sandbox environment and follow the production stock rule; rehearse them onSANDBOX-ALLOC-REQUEST-001. - POST /sandbox/allocations/{allocationId}/stock-events: sends
allocation.low_stockorallocation.depletedfor one of your allocations without selling anything. - POST /sandbox/promotions/deals/{responseId}/window: starts or ends a deal now, with
promotion.startedorpromotion.endedfor 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_REQUIREDand nothing is read or changed; a control that would change data every store on the shared sandbox reads answers422 SANDBOX_ISOLATED_ENVIRONMENT_REQUIREDthere.Idempotency-Keyis 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 answers422 REFUND_WINDOW_EXPIRED),SANDBOX-REDEEMED-001(keys marked redeemed right after delivery, so a refund or return answers409 KEY_NOT_RETURNABLE) andSANDBOX-ALLOC-REQUEST-001(an allocation of 5 over 30 keys, so an approved request fits). The whoami response lists them undersandboxCatalog. - 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.missingFixturesuntil 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 date2026-12-01) makes a checkout call behave as if the Content Owner required the confirmation, so422 CONSUMER_GEO_ATTEST_REQUIREDand 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_UNKNOWNbefore any work, withdetails.honoured, instead of being ignored. - Every write honours
rate_limit,internal_errorandservice_unavailable, answered before any work. This includes POST /orders/cancel,/orders/recover-keys,/keys/export,/keys/return,/refundsand/chargebacks/resolve, which ignored the header. - Each operation's
X-Avrix-Sandbox-Simulateparameter in the API reference lists exactly the values it honours (SandboxSimulateWriteandSandboxSimulateCheckoutare 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-01and send the header on every call: send it only on the calls you mean to fail, with a value fromdetails.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-01and 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, withSANDBOX-NOSHARE-001left 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-01and later, answering a share or a deal whose state no longer allows it answers409 CONFLICTwithdetails.reasoninstead of400 BAD_REQUEST:SHARE_EXPIRED,PROMOTION_STARTEDorRESPONSE_DEADLINE_PASSED(too late; the offer is nowexpired, named indetails.currentStatus) andPROMOTION_WITHDRAWN(the vendor withdrew the deal).GET /promotions/shares/{shareId}/discountsfor a share you have not accepted answers409 CONFLICTwithdetails.reason: NOT_ACCEPTEDanddetails.currentStatus. POST /promotions/deals/{responseId}/respondfor a deal offered to another company answers404 NOT_FOUND, the same as an unknown id, instead of400.- A storage failure on
GET /promotions/deals/{responseId},POST /promotions/deals/{responseId}/respondandGET /promotions/shares/{shareId}/discountsanswers503 SERVICE_UNAVAILABLEor504 HOT_PATH_TIMEOUTwithRetry-After(or a500without the database text), like every other read.GET /promotions/summaryfails the same way when the deals cannot be read, instead of answering200with zero deal counts. - Earlier contract dates keep their answers.
- Who must act: integrations that pin
2026-12-01and branch on400from these operations: treat409withdetails.reasonas "the offer's state changed; read it again", and retry503and504afterRetry-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-01and later,GET /promotions/shares/{shareId}/discountsreturns the rows of an accepted share before and after its window too, withmeta.active: false. Earlier dates answer an emptydataoutside the window, as before. - Who must act: integrations that pin
2026-12-01and apply every row they receive: apply the rows only whilemeta.activeistrue.
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.startedandpromotion.ended. Each names the offer bysourceTypeandsourceId(the share id or the deal response id) and carries itsstatus, window andrespondBy. An answer given in the console sends the same event as one given over the API. They are in your event log withresourceType: promotionand 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/sharesandGET /promotions/dealstakefromandto(offers whose window overlaps),updatedSince(offers that changed since) andsort(-offeredAt, the default and the order they always had,offeredAt,-updatedAt,updatedAt).GET /promotions/sharesalso takesvendor, andstatus=vendor_withdrawn.- Shares and deals carry
respond_by(the last instant an answer is taken: the answer deadline or the start, whichever is earlier) andupdated_at. Share and deal products carryprice_effect; deal products carryproduct_id. Discount rows carryskuIdandpriceEffect. The summary countsexpired(shares and deals) andvendor_withdrawn(shares). GET /promotions/calendartakesfrom,to,skuId,productId,sourceId,vendorandwindow(live,upcoming,ended), and its entries carryname,vendorCompanyIdandproductId. Without the new parameters it answers as before.- Who must act: nobody.
Added: promotions on catalogue prices#
skus[].prices[]onGET /products/{productId}andGET /products/{productId}/pricingcarrylistPromo,advertisedPriceCents(the list price with the live list-price promotion applied),promoandpromoResolution. Each SKU carriespromotions: the accepted promotions on it whose window is live or upcoming.basePriceCentsis unchanged.- Who must act: nobody. Show
advertisedPriceCentsas the sale price; keep charging whatPOST /orders/previewquotes.
Fixed: shares a vendor had not sent were visible#
GET /promotions/shares,GET /promotions/shares/{shareId}andGET /promotions/summaryshowed 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
draftshare you stored can be dropped: it reappears aspending, with apromotion.offeredevent, 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, withdate-timeformats and the status values. - The
500ofGET /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 /refundsandPOST /keys/returnanswer withrefunds[]: one entry per refunded key sold under the API model, with the refund recordid(GET /refunds/{refundId}reads it),keyIdand 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 /refundstakesrefundReference,chargebackReference,status,typeandkeyId, next toorderReference; the filters combine, and a value outside the documented set answers422 VALIDATION_FAILEDnaming the field. Each record also carriesrefundReferenceandchargebackReference, the reference you sent split by type (adjustmentReferenceis unchanged).- On
GET /orders/{orderId}, each entry ofrefunds[]carriesrefundReferenceandrefundIds. - Who must act: nobody. Store
refunds[].idto read a refund back without listing.
Added: POST /refunds/preview says whether a key can be refunded#
- Per key: whether
POST /refundswould 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 noIdempotency-Key. The rolling refund limit per allocation is not evaluated. - Who must act: nobody.
Added: read your dispute freezes#
GET /disputeslists your freezes newest first (filtersstatus,disputeReference,keyId) andGET /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 /returnsfiles a return request (refund or replacement, decided by the Content Owner),GET /returnsandGET /returns/{returnRequestId}read them with the message thread and the evidence,POST /returns/{returnRequestId}/replyanswers the Content Owner's question,POST /returns/{returnRequestId}/evidenceattaches a file andPOST /returns/{returnRequestId}/cancelwithdraws the request. Until now this was possible only in the console.return.information_requestedandreturn.decidedreport the Content Owner's side.- Who must act: nobody.
Added: chargeback.opened, key.replacement_rejected and refund fields on refund.completed#
chargeback.opened:POST /refundsrecorded a chargeback; report the outcome withPOST /chargebacks/resolve.key.replacement_rejected: the Content Owner turned down a key replacement you requested; the original key stays delivered.refund.completedalso carriesrefundReference,chargebackReference,refundIds,keyDispositionandsaleTotals.- Who must act: nobody. Add the new events to an endpoint's
eventsto receive them.
Changed behaviour (contract date 2026-12-01 only): keyDisposition gives the real outcome#
- On
POST /refundsandPOST /keys/return,keyDispositionisquarantined,held(keys sold under revenue share stay with you) ormixed(both in one call). Earlier dates keep answeringquarantinedwhatever happened. - Who must act: integrations that pin
2026-12-01and treat every refunded key as gone: keepheldkeys in your records, and readrefunds[].keyDispositiononmixed.
Changed behaviour (contract date 2026-12-01 only): a partial refund leaves the order fulfilled#
- On
2026-12-01and later, an order's status follows its keys afterPOST /refunds: it readsrefundedonce every key is refunded and staysfulfilledafter a partial refund. Earlier dates mark theorderReferenceyou send asrefundedas soon as one key is refunded. - Who must act: integrations that pin
2026-12-01and readrefundedonGET /ordersas "a refund happened": readrefunds[]on the order instead.
Changed behaviour (contract date 2026-12-01 only): POST /keys/return ends dispute freezes#
- On
2026-12-01and later,POST /keys/returnends any dispute freeze on its keys, asPOST /refundsalways did (key.unfrozen, resolutionrefunded). 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/pullreadspriceCommitmentToken, andPOST /keys/exportreadspriceCommitmentToken,expectedUnitPriceCentsandexpectedWholesaleUnitPriceCents, with the rules ofPOST /orders: the token must be yours and for this SKU (422 PRICE_COMMITMENT_INVALIDorPRICE_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 answering422 EXPECTED_UNIT_PRICE_REQUIREDthere.- Who must act: integrations that pin
2026-12-01and send these fields on a pull or export: send a current token, or drop the field.
Deprecated: POST /keys/return#
POST /refundsis the one call for every refund and chargeback. It does whatPOST /keys/returndoes and also records your refund or chargeback reference, so the refund can be found again withGET /refunds?refundReference=.POST /keys/returnkeeps working unchanged and is marked deprecated in the API reference. No sunset date is set, and no response carries aDeprecationheader until one is announced here.- Who must act: integrations that call
POST /keys/return: move toPOST /refundswithtype: "refund"and yourrefundReference. Nothing breaks if you do not.
Deprecated: refundPolicy.keyRevealForfeitsRefund#
- Read
refundPolicy.revealedKeysRefundableinstead. 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: readrevealedKeysRefundable.
Fixed: POST /keys/pull declares immediateFulfilment#
- The API always accepted
immediateFulfilmentonPOST /keys/pull, as onPOST /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 /refundssample lackedtypeandrefundReference, both required; it has them now. It no longer sayspendingis a refund status you will see: no refund is recorded in that state today. POST /keys/returnis documented as the call kept for existing integrations;POST /refundsis the one to use. Nothing aboutPOST /keys/returnchanges or is removed.- The
RefundPolicydescription no longer says Content Owners cannot set a refund window: they can, per product or per SKU. The409ofPOST /chargebacks/resolvedocumentsdetails.currentState. - Who must act: nobody.
Changed behaviour (contract date 2026-12-01 only): GET /events serves your event log#
- On contract date
2026-12-01and later,GET /eventslists your events, one row per event, whether or not any webhook endpoint subscribes to it, kept 30 days. Each row hasid(the same value aseventLogId),eventType,eventVersion,occurredAt,createdAt,resourceType,resourceIdandpayload(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 answers422 VALIDATION_FAILED),resourceTypeandresourceId. Paging,cursor,since,meta.nextCursorandmeta.headCursorwork 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 with422 VALIDATION_FAILEDnaming them, as before they existed. - Who must act: integrations that pin
2026-12-01and read delivery fields (endpointId,status,attempts,responseStatus) fromGET /events: read delivery status fromGET /webhooks/{id}/deliveriesinstead. A store with no webhook endpoint can now follow its events fromGET /eventsalone.
Added: one id per event on every webhook delivery, and a delivery id header#
- Every webhook delivery carries
eventLogIdin the body and theX-Avrix-Event-Log-Idheader: the event's own id, the same on every endpoint that receives it, on retries and on replays, and theidof the event inGET /events. Deduplicate on it. eventIdandX-Avrix-Event-Idkeep their meaning: the id of one delivery.- Every delivery also carries
X-Avrix-Delivery-Id, the delivery row asGET /webhooks/{id}/deliverieslists it. - Test deliveries, and deliveries created before this release, carry no
eventLogId. - Who must act: nobody. Deduplicate on
eventLogId ?? replay?.originalEventId ?? eventIdso 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 OpenAPIwebhookssection. - 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.addedis 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_changedwithsellable: trueand the new fieldfirstSeen: true. Flips between sellable and not sellable carryfirstSeen: 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_changedwhose handler looks the SKU up locally: afirstSeen: trueevent can name a SKU you do not have yet; read it withGET /allocations.
Deprecated: order.returned, an older name of order.cancelled#
order.returnedis sent for a cancellation before delivery (POST /orders/cancel), not for a return of delivered keys (order.keys_returned).order.cancellednow names that change. Endpoints subscribed toorder.returnedkeep receiving it, with the same payload and the sameeventLogIdas theorder.cancelleddelivery of the same cancellation. The event log records the cancellation once, asorder.cancelled. No sunset date is set.- Who must act: nobody yet. Subscribe to
order.cancelledand then removeorder.returnedfrom the endpoint, or deduplicate the two oneventLogId.
Fixed: the sandbox chargeback.resolved test event sends resolved as an integer#
POST /webhooks/{id}/testwitheventType: chargeback.resolvedsentresolved: 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
resolvedas a number.
Fixed: the webhook helper package states the 8-second delivery timeout#
- The comments of
@avrix/seller-api-helperscreateWebhookConsumersaid 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
2xxwithin 8 seconds and do the work afterwards.
Documentation: order lifecycle transitions and event examples#
- Order lifecycle said
POST /orders/reservesendsorder.reserved(it sends no event: the response is the answer), that a commit rejection sendsorder.failed(it answers an HTTP error;order.failedis sent only when an automatic pre-order fulfilment could not deliver keys), and drew a cancel fromreserved(a hot-drop reservation expires at its TTL;POST /orders/canceldoes 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 /usagenow counts in the database, sototalRequests,totalErrorsandtotalLookupMissescover 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 errorcode),byDay(UTC day) andbyKey(API key), all complete;maxEndpointBuckets; andkeyId. A new optional query parameter,keyId, counts one of your keys only. - The call log behind
GET /usageandGET /requests/{requestId}now stores the errorcodeof every error response (VALIDATION_FAILED,RATE_LIMIT_EXCEEDED, ...). Responses recorded before this release reportHTTP_<status>. byEndpointis unchanged and lists at mostmaxEndpointBuckets(50,000) entries, largest first;truncatednow 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
maxCountedRequestshas 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
truncatedandmaxEndpointBucketsinstead.
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:
callLoggives the method, endpoint, status, latency, error code and key of each response with that id, andcoveragesays what was found (detailed,summaryornone). 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-01and later, an id with no call-log row, no trace and no webhook delivery in the last 90 days answers404 NOT_FOUNDwithdetails.lookupRequestIdanddetails.retentionDays. Earlier dates answer200withcoverage: "none"and empty lists. - Who must act: integrations that pin
2026-12-01and treat the empty200as "no trace kept": handle the404.
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 newX-RateLimit-Bucketheader. A429from the limiter repeats it indetails.rateLimitBucket, withdetails.limitanddetails.retryAfterSeconds. GET /whoamireturnsdata.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 correctsx-avrix-tier, which saidcatalogfor operations counted inordersandfinancefor one counted ingeneral. - Reference correction:
GET /transactions,GET /allocations/requests,POST /allocations/requestsandGET /activityare counted inorders, andGET /finance/statementsingeneral; theirx-avrix-tiernow says so. The API did not change. - Who must act: nobody. Pace from
X-RateLimit-Bucketif 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-01and later,GETandPOST /keys,DELETE /keys/{id},POST /keys/{id}/rotateandPATCH /keys/{id}/allowed-ipsare counted in thegeneralrate-limit class, so they report its numbers and no longer spend the checkout budget. Earlier dates keep counting them inorders. - Who must act: integrations that pin
2026-12-01and pace key management from theordersnumbers: readX-RateLimit-Bucket.
Changed behaviour (contract date 2026-12-01 only): X-Request-Id has one format#
- On contract date
2026-12-01and later, anX-Request-Idrequest header that is not 8 to 128 characters fromA-Z,a-z,0-9,_,.,:and-is refused with400 INVALID_REQUEST_IDbefore anything runs. Every id in that format can be looked up withGET /requests/{requestId}. Earlier dates echo any value, as before. - Who must act: integrations that pin
2026-12-01and 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-01and later, a database timeout onGET /products/{productId},GET /products/{productId}/pricingorGET /catalog/snapshotanswers504 HOT_PATH_TIMEOUT, an unavailable dependency503 SERVICE_UNAVAILABLE, both withRetry-After, and any other failure500 INTERNAL_ERRORwith a generic message. Earlier dates keep500 INTERNAL_ERROR; there, a message that would show database internals is replaced byInternal 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: retry503and504afterRetry-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 sendX-Avrix-Api-Version: 2026-12-01(ornext) they now redirect too (307, method and body kept). Other requests are served in place.- Who must act: integrations that pin
2026-12-01and 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}/completeandGET /geo/attest/{attestId}/pixelnow sendX-Request-Id(equal to the body'srequestId),X-Avrix-Api-Version,X-Api-VersionandCache-Control: no-store, and the JSON call sendsRetry-Afteron429,503and504.- 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
500answers ofGET /whoamiwere built by hand; they now carry the same fields as every other error body. The code and message are unchanged. - Who must act: nobody.
Fixed: the legacy /api/external pointer links the public quickstart#
- Its
quickstartlink pointed into a private repository; it now points tohttps://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-01and later,sellableandblockedReasonon every price ofGET /products/{productId}/pricingare the order path's answer for that SKU in that country, the samePOST /orders/preview,POST /ordersandGET /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.blockedReasoncan be any ofFOOTPRINT_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_COUNTRYandSRP_MISMATCH_FOR_CURRENCY. - Earlier dates keep the currency-only answer: a priced country outside your footprint still
reads
sellable: truethere, and an order in it is refused. - Whether you hold an allocation for the SKU is not part of the answer;
GET /allocationssays so. - Who must act: integrations that pin
2026-12-01and show every price withsellable: trueas purchasable: expect morefalsevalues, and hide those countries or showblockedReason.
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-01and later,GETandHEAD /products/{productId}/media/download:- answer errors on the standard error body, with
timestampandrequestId, instead of the short{ code, message, requestId }; - answer
404 PRODUCT_NOT_SHAREDfor a product that exists but is not shared with you (NOT_FOUNDbefore), as product detail does; - answer the Seller API
401(withX-Request-Idand an error body) to a request without an API key, onGETand onHEAD; - end the archive with
avrix-media-manifest.json,{ "complete", "entries": [{ "filename", "included" }] }. A file that cannot be read from storage is left out after the200has been sent;complete: falsesays so. That archive has its ownETag.
- answer errors on the standard error body, with
- Earlier dates keep the short body,
NOT_FOUND, the bare401onHEADand the archive without a manifest. - Who must act: integrations that pin
2026-12-01and parse media errors: readcodefrom the standard body, and treatPRODUCT_NOT_SHAREDas "remove from your listing". Readcompletein 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-01and later,POST /catalog/exportsrefuses a body that is not valid JSON, is not an object, has a key other thanpricing, or has apricingother than"territory", with422 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-01and send a body withPOST /catalog/exports: send{}or{ "pricing": "territory" }, or no body.
Added: territory prices in catalog exports#
POST /catalog/exportstakes an optional body{ "pricing": "territory" }, on every contract date. The export then carriesterritoryPriceson every shared SKU, asGET /catalog/snapshot?pricing=territorydoes, andGET /catalog/exports/{exportId}reportspricing: "territory"(nullotherwise). 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 /productstakesplatform,externalReference(withexternalReferenceSource),releaseDateFrom,releaseDateTo,launchPhase,tradingState,productTypeandsort(-createdAt, the default and the order the list always had,createdAt,-updatedAt,updatedAt,name,-name), on every contract date.meta.totalcounts the filtered list. Acursorbelongs to the sort it was issued with; sent with anothersortit answers422. 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, andmeta.requested,matchedandunmatched.- Who must act: nobody.
Added: lighter product detail and credits#
GET /products/{productId}?omit=leaves outassets,eula,localizedDescriptions,systemRequirements,relatedProductsorreleasePricing(the deprecated release-levelpricing[]). Without it the body is unchanged.- Product detail carries
developerandcreditedPublisher, the studio and publisher the store page credits;nullwhen not set. - Who must act: nobody. A store that syncs prices or stock can send
omit=assets,eula,localizedDescriptionsto cut most of the body.
Added: currency digits for the suggested retail price, and facets on product.updated#
- Catalog
sharedSkus[]carrysrpCurrencyExponentbesidesrpPriceCentsandsrpCurrencyCode, as every other money field has its exponent;nullwhen there is no SRP. product.updatedcarrieschangedFields(theGET /catalog/changesvocabulary, once each) when the change that sent it names what changed. It is absent otherwise.- Who must act: nobody. Divide
srpPriceCentsby10^srpCurrencyExponent, not by 100; onproduct.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}/pricingsends a weakETagon every contract date. Send it back asIf-None-Matchto get304 Not Modifiedwithout a body or areadbudget charge.GETandHEAD /products/{productId}/media/downloadsendX-Avrix-Media-Entries, the number of files the archive is built from, on200and304, 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#
publisherCompanyIdis the older spelling ofpartneron these two operations. It keeps working, with no sunset date; a request that uses only it gets anX-Avrix-Deprecated-Parameterheader namingpartner. Sending both with different values answers422, as before.- Who must act: nobody now. Send
partnerwhen 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-RemainingandX-RateLimit-Reseton the media download, and the route did not send them. It sends them now on200,304andHEAD, 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.downloadProductMediadeclares theETagheader 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:
listProductsandPartnerProduct.listPriceFromCentssaid 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
listPriceFromCentsas a US price, readlistPriceCurrencyCodewith 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
discontinuedas a launch phase and said apre_orderproduct cannot be ordered.discontinuedis atradingState; apre_orderproduct 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
ETagand that a304costs no database work. It lists the routes that send one; a304saves 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 carryhint,recoverableanddoc_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
economicsonGET /ordersor fromGET /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}/documentreturns a five-minute download link for the invoice PDF.GET /finance/paymentslists 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}andGET /finance/reports/{reportId}/linesreturn 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/invoicesgains 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 filtersstatus,kind,invoiceType,publisherCompanyId,reportMonth,issuedFrom,issuedToandupdatedSince. Without a filter it answers exactly as before.GET /finance/summarygainscurrentPeriod.activityTotals: the running month's sales per vendor and currency, the same figures asmeta.balancesonGET /finance/ledgerfor that period.- The statement CSV (
GET /finance/statements?format=csv) gainscurrencyExponentand the key, report and settlement columns the api-sales CSV has, after its first twelve columns. The reconciliation CSV gainspaymentCurrencyExponentandsaleCurrencyExponentas its last two columns. TheGET /finance/api-salesreference now declares itstext/csvresponse. - 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.overduefires once when a monthly invoice passes itsdueAtunpaid; it stays payable.invoice.disputedfires when you dispute an invoice in the console, andinvoice.dispute_updatedwhen the vendor answers or you withdraw it (outcome:accepted,rejected,withdrawnorescalated). All three carry the fields ofinvoice.issued, and appear in the event log onGET /events.invoice.issuedandinvoice.paidcarryreplacesInvoiceIdwhen 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/statementsrefuses an unknownformatwith422 VALIDATION_FAILEDnamingformat(earlier dates serve JSON), nameslimitin the422for a badlimit, and answers an infrastructure failure with503or504andRetry-Afterinstead of500.GET /finance/invoices/{invoiceId}/reconciliationfor an invoice you owe that has no settlement answers409 CONFLICTwithdetails.reason: RECONCILIATION_NOT_AVAILABLEanddetails.invoicePath, instead of404. An invoice that is not yours still answers404.- Who must act: integrations that pin
2026-12-01and send aformatother thanjsonorcsvto the statement, or treat the reconciliation404as "not yet": checkreconciliationAvailableon the invoice before asking, and retry a503afterRetry-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-01and later,PUT /me/footprintanswers with the footprint as stored, duplicates removed and sorted, which is whatGET /me/footprintreturns next, and refuses a code that names no country or no current ISO 4217 currency (for exampleZZorXXQ) with422 VALIDATION_FAILED,details.issues[].fieldnaming 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
500fromGET /finance/statementscarried 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/requeststookpublisherAvailableKeysfrom the request body as the Content Owner's free stock when their rules decide a request automatically. A request could change its own outcome:0sent 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
422as 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}/cancelwithdraws a pending one (no body;Idempotency-Keyoptional; cancelling it again answers the same200; a request the Content Owner already decided answers409 CONFLICTwithdetails.reason: ALLOCATION_REQUEST_ALREADY_RESOLVEDanddetails.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 asallocationGrantId),skuCodeandupdatedAt. Existing fields are unchanged. GET /allocations/requestsfollows the list contract:limit(1 to 100, default 100, the page size it always had),cursor,metawithnextCursor,hasMoreandcount, and the filtersstate(comma-separated) andallocationId.POST /allocations/requestsacceptsallocationId, the name every other surface uses for the allocation;grantIdstays accepted (send one, or both with the same value). Its answer addsallocationIdandstate, and a second request on an allocation that already has a pending one names it indetails.pendingRequestId.- New webhook event
allocation.request_cancelled.allocation.request_decidedis 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_decidedandallocation.request_cancelled.
Added: GET /allocations/{id}#
- Reads one of your allocations: the row
GET /allocationsreturns, whatever its status, so an allocation a webhook names can be read even when it is paused or revoked.404when 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
remainingfalls to or below its low-stock threshold: yourreplenishThreshold(PATCH /allocations/{id}) when you set one, otherwise 10% ofquantityLimit, rounded down. It carriesthresholdandthresholdSource. It is sent again only afterremaininghas risen above the threshold and fallen to it again. allocation.low_stockis unchanged: a fixed 10%, sent with every allocation update while the allocation stays there. Its deliveries now state that number inthreshold. Webhook deliveries carry no contract date, so its timing was not changed;allocation.running_lowis 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_lowinstead ofallocation.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, asGET /allocations/{id}/replenishmentsshows them) andeffective: 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}/replenishmentsaddseffectivetoo. - Who must act: nobody.
Changed behaviour (contract date 2026-12-01 only): allocation request create and revoked allocations#
POST /allocations/requestsanswers201 Createdinstead of200 OKfor a request it files or grants at once. The body is the same.PATCH /allocations/{id}on a revoked allocation answers409 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-01and test for exactly200on the create: accept any2xx.
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_FOUNDwithdetails.holdState(released,consumedornot_found);503 STORE_UNAVAILABLEwhen 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}/replenishmentsanswered404or an empty history when a database read failed, andPATCH /allocations/{id}returned the database's own message in a500. Both now answer500,503or504like every other read, withRetry-Afteron503and504.GET /availability/changesgives its500the same envelope andRetry-Afterhandling. The replenishment history also sends the rate-limit headers.- Who must act: nobody. A client that deleted its copy of an allocation on a
404during an outage no longer sees one.
Fixed: the allocation and checkout hold reference#
- Reference correction:
GET /allocations/requestsandPOST /allocations/requestsdeclare their200bodies; the create's409lists everydetails.reason;publisherAvailableKeysis described as ignored;POST /orders/holddescribesholdId,expiresAt,expiresInSeconds,allocationId,maxFulfillableQuantity,currencyCode,salesCountryCodeandpriceBoundAt;allocation.low_stockis 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, notsince. - 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-01and later, a JSON token request that fails carries the RFC 6749 error code inerror(invalid_client,invalid_request,unsupported_grant_type,unauthorized_client,temporarily_unavailable,server_error) instead of the message. The status codes andcodedo not change; the message is inmessageanderror_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 theAuthorizationheader. - 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 fromerror: readmessageorerror_description. Clients that sendAuthorization: Basicnext to a JSON body withclient_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 anAuthorization: Basicheader, 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 headerPragma: no-cache. A requestedscopeis ignored. - Every error adds
error_description. A refused HTTP Basic client getsWWW-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 /keystakesscopes: the new key gets exactly those, each of which the calling key must hold. One it lacks is refused with403 INSUFFICIENT_SCOPEnaming it indetails.missingScopes, and no key is created. Withoutscopesthe default set applies as before. Keys wider than the calling key are still created in the console.POST /keystakesexpiresAt: at least a minute ahead (422otherwise) and no later than the calling key's expiry (403otherwise). Without it the new key inherits the calling key's expiry, as before. The response repeatsscopesandexpiresAt.- New scope
seller:keys:read: lists keys (GET /keys) without being able to create, rotate or revoke them.seller:keys:writestill lists them. On contract date2026-12-01a key holding neither getsINSUFFICIENT_SCOPEwith both indetails.requiredScopes. GET /keysrows addscopes,environmentandallowedIps, besidecreatedAt,lastUsedAtandexpiresAt.- Who must act: nobody. To audit keys from a monitoring job, give it a
seller:keys:readkey.
Added: api_key.expiring and api_key.expired#
api_key.expiringis sent once, 14 days before a key's expiry, for keys meant to live longer than that;api_key.expiredonce the expiry passes. Neither is sent for a revoked key. Both carrykeyId,keyName,environmentandexpiresAt, 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 /whoamireturnsproductionAccess: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_APPROVEDaddsdetails.productionAccesswithstatusandrequestedAt: 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/tokenrefused 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/tokensuccess body was declared as a free-form object; the reference now declaresaccess_token,token_type,expires_in,scopeandmeta, 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 /whoamiexample 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 readdata.key.environment. KEY_ENVIRONMENT_MISMATCHis explained by its two real causes: a production key sent withX-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-ipsaccepted an emptyallowed_ipson 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_FAILEDwithdetails.issues[0].fieldallowed_ipsanddetails.issues[0].codePRODUCTION_ALLOWLIST_REQUIRED(an empty list on a production key that is not bound to a trusted workload) orSANDBOX_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 answered409 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'sintegrationOrderContext, which Avrix now keeps with a deferred order. If the allocation's price has changed since, fulfil answers409with a message startingWHOLESALE_PRICE_MISMATCH, no key is delivered and the order keeps its status. Applies on every contract date. The price check onPOST /ordersis 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 sendsorder.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 ofPOST /orders/bulk,POST /keys/pullorPOST /keys/export), whose keys Avrix delivers at the release itself, and sentorder.readyfor 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.readyreceives 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-01and later, preview of an order on a paused or otherwise inactive allocation answers400 BAD_REQUESTwith the message anddetails(orderStage: allocation,allocationResolve: NO_ACTIVE_ALLOCATION) thatPOST /ordersreturns for the same order, instead of404 ALLOCATION_INACTIVE.details.previewErroranddetails.allocationStatusare kept. - Earlier dates and unpinned requests keep
404 ALLOCATION_INACTIVEexactly. - Who must act: integrations that pin
2026-12-01and match preview's404 ALLOCATION_INACTIVE: match400withdetails.allocationResolveNO_ACTIVE_ALLOCATION, the answerPOST /ordersgives.
Fixed: the sandbox catalog in whoami describes SANDBOX-PREORDER-001 as it behaves#
- The sandbox catalog entry for
SANDBOX-PREORDER-001still said the SKU is not sellable and that an order is refusedPRODUCT_NOT_SELLABLE. Since pre-orders are on by default the SKU is sellable: preview quotesfulfillmentType: pre-orderandPOST /ordersanswers200withstatus: awaiting_releaseand no keys. TheexpectedOutcometext 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-01and later,GET /partnerswithoutstatusalso lists connections withstatusterminating(notice given, still live untilterminationEffectiveAt; earlier dates left them out although orders under them still succeed) and your connection requests that wait for an answer, withstatuspending. A request row has no connection yet: itsconnectionIdis the request id, itscontractssummary is empty, and itsconnectionRequestobject says who sent it, whose answer it waits for and where to follow it in the console. - Earlier dates without
statuslistactive,suspendedandterminatedconnections exactly as before. - Who must act: integrations that pin
2026-12-01and treat everyGET /partnersrow as a tradeable connection: skip rows whosestatusispending(or that carryconnectionRequest), and handleterminatinglikeactiveuntilterminationEffectiveAt. Pass only connection ids toGET /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.rejectedrequests come with the vendor's note inconnectionRequest.reviewNoteand are listed only when asked for. An unknown value answers422 VALIDATION_FAILEDwithdetails.issues[].fieldstatus.- Request rows carry
connectionRequest(requestId,initiatedBy,waitingOn,requestedAt,decidedAt,reviewNote,consoleUrl). Requests are still sent and answered in the console;consoleUrlopens 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, witheffectiveFrom,expiresAt,renewalPolicy, termination dates, theterritoryorders are checked against,sellerRevenueSharePercent, the settlement terms and the sale-currency rule, and aconsoleUrlto the signed documents. Requiresseller:products:read. A connection that is not yours, or a connection request id, answers404 NOT_FOUND. - The MCP server has a matching
list_partner_agreementstool, andlist_partnerstakes astatusargument. - 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:managescope,Idempotency-Key, theaccess.proposal_createdevent) and gives the empty-sandbox row a check you can run (GET /whoamisandboxCatalog.tenantReady). - The error reference lists every
details.accessCodean access proposal answer can return. - The
partnerfilter onGET /productsandGET /catalog/checksumtakes a partner row'spublisherCompanyId(a slug-safe company id, not a UUID), never itsconnectionId; the reference now says so onGET /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_decidedfires once when a vendor approves or rejects a connection request your company sent:requestId,decision(approvedorrejected),publisherCompanyId,connectionId(the new connection on approval,nullon rejection),reviewNote(the vendor's note on rejection),requestedAtanddecidedAt. ItsGET /eventsresourceTypeis the new valueconnection_request. Nothing fires for a vendor's invitation you answer yourself.sandbox.certification_passedfires 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,firstPassandpassedAt. 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_decidedto stop pollingGET /partnersfor an answer, and tosandbox.certification_passedto know when to ask for review.
Added: an early warning when a webhook endpoint keeps failing#
- An active endpoint becomes
failingonce 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) andsystem.webhook_endpoint_recovered(the next2xx). Both are on your event log, soGET /events(contract date2026-12-01) shows the warning even when every endpoint is down. Company admins also get a console notification. GET /webhooksrows gainfailing,failingSince,lastSuccessAt,lastFailureAt,consecutiveFailedAttempts,pendingDeliveriesandupdatedAt.- Who must act: nobody. To be warned by webhook, add
system.webhook_endpoint_failing(orsystem.*) 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 theGET /webhooksshape, health included.- The answers of
POST /webhooks,PATCH /webhooks/{id}andPOST /webhooks/{id}/enablealso 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, andattemptHistory, 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}/deliveriesrows gaineventLogId.- Who must act: nobody.
Added: pause an endpoint, and resume without the backlog#
POST /webhooks/{id}/disablepauses an active endpoint (disabledReason: manual). Events are buffered as after a circuit-breaker disable; a pause raises no alert.POST /webhooks/{id}/enableaccepts an optionalreplayFrom: buffered events older than it are closed asfailedwithlastError: 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 futurereplayFromanswers422 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-01and later,POST /webhooks/{id}/teston a disabled endpoint queues one test delivery (202) instead of answering400 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}/enablerefuses a body that is not a JSON object with422 VALIDATION_FAILED; earlier dates ignore it. - Who must act: integrations that pin
2026-12-01and read the400as "endpoint disabled": readstatusfromGET /webhooks/{id}.
Changed behaviour (contract date 2026-12-01 only): at most 16 webhook endpoints per company#
- On contract date
2026-12-01and later,POST /webhooksanswers409 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-01and 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
eventsaccepts*(every event, including ones added later) and<family>.*(for exampleorder.*). One event reaches an endpoint once; the older aliasorder.returnedis sent only to endpoints that name it. GET /webhooks/event-typesentries gaincategory(the family) andschemaRef(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,metagainsretentionDays,retainedFromandpositionBeforeRetention. The last istruewhen yourcursororsinceis 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 (
succeededorfailed) 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}/deliveriesfor history older than 30 days: keep your own copy.
Added: forward events to a local receiver#
@avrix/seller-api-helpersexportsforwardEventsToLocal(also from@avrix/seller-api-helpers/local-forwarder): it readsGET /eventsand 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 barecentsof a per-currency bucket, now also carries it under its...Minorname with the same value:unitPriceMinorbesideunitPriceCents,totalMinorbesidetotalCents,amountMinorbesidecents. Amounts already named...Minorare unchanged. GET /finance/summaryreports (recentReports,attentionReports) gaintotalNetRevenueMinorandcurrencyExponentbesidetotalNetRevenue, the one total the API gave in major units.- Request fields and CSV columns keep their names: send
expectedUnitPriceCentsas before. - The convention is in Naming conventions.
- Who must act: nobody. Read the
...Minornames in new code.
Added: paths that name what they act on#
GET /keys/pulls(listKeyPulls) lists key pulls, the listGET /transactionsserves.- API keys are managed under
/api-keys:GETandPOST /api-keys(listApiKeys,createApiKey),DELETE /api-keys/{id}(deleteApiKey),POST /api-keys/{id}/rotate(rotateApiKey) andPATCH /api-keys/{id}/allowed-ips(updateApiKeyAllowedIps)./keyspaths act on game keys everywhere else. DELETE /orders/hold/{holdId}(releaseHold),POST /orders/reservations/{reservationId}/commit(commitReservation) andPOST /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 with422 VALIDATION_FAILED.- Each new path runs the same handler as its older path: same scopes, rate limit,
Idempotency-Keyrule, 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/pullsandGET /transactionsrows gainkeyPullId(the same value asid),transactionId(the sale row the pull produced, the idGET /finance/api-sales/{transactionId}reads;nullwhen the pull has no sale row) andskuId.GET /finance/invoices,invoice.issuedandinvoice.paidgainplatformInvoiceNumber(the number Avrix gives the invoice) andsupplierInvoiceNumber(the number on the Content Owner's own document,nullwhen they use none).invoiceNumberkeeps 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.rotatedandapi_key.revokedgainapiKeyId, the same value askeyId:keyIdnames a game key everywhere else.GET /finance/api-salesrows gainrefundStatus, the refund state in the vocabularyGET /refundsuses forstatus(nullwhen nothing took the sale back).adjustmentStatuskeeps the ledger's own values.pendingis 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 /transactionsrow'sidtoGET /finance/api-sales/{transactionId}got404: pass the row'stransactionId. Match invoice events toGET /finance/invoicesonplatformInvoiceNumber, notinvoiceNumber.
Deprecated: the older names of those amounts, ids and paths#
- The
...Centsnames (andcents) beside each new...Minorname, andtotalNetRevenue. GET /transactions, and its rows'idandreadableId(readableIdis not an order id; look the order up withorderReference).GETandPOST /keys,DELETE /keys/{id},POST /keys/{id}/rotateandPATCH /keys/{id}/allowed-ips.DELETE /orders/hold,POST /orders/commitandPOST /orders/{orderId}/extend.invoiceNumberonGET /finance/invoices,invoice.issuedandinvoice.paid;keyIdonapi_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 (
@deprecatedin TypeScript and PHP, the docstring in Python). No sunset is set, noDeprecationheader 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-01and later,PATCH /allocations/{id}andPOST /orders/{orderId}/keys/{keyId}/replacecompare the path parameters, as well as the body, with an earlier use of the sameIdempotency-Key. The same key and body sent to another allocation or another key answers409 IDEMPOTENCY_KEY_MISMATCH. Earlier contract dates replay the first answer, so the second target was never changed although the call answered200. - A true retry (same path, same body, same key) still replays.
- Who must act: integrations that pin
2026-12-01and reuse one key across targets: use one key per target, and retry with the sameX-Avrix-Api-Versionyou first sent.
Added: updatedAt on GET and DELETE /me/integration-presets#
GET /me/integration-presetsreturnsupdatedAt, the time of the lastPUT, asPUTalready did.DELETEand aGETwith no presets saved returnupdatedAt: 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-Idand the others on Webhooks). - Reference correction:
listAllocationsRequestsandcreateRequestdeclare their200bodies (SellerAllocationRequest,SellerAllocationRequestCreated);getRequestdeclares its422body;getAvailabilityandgetFinanceApiSaleTransactiondeclaredatawith the fields they return. - Reference correction: the finance status fields list their values with what each means:
invoice
statusandinvoiceType, sales reportstatusandmodelType, statementaggregationStatusand reconciliationpaymentState. 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/tokenreaches the token operation as/api/seller/oauth/tokendoes; neither checksX-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-enumin 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-clientreturns every operation as a typed method bound to one configuration. Given thecreateSellerClient()result of@avrix/seller-api-helpers, every typed call runs on the helpers transport (retries, throttling, automaticIdempotency-Key). See Official SDKs. - Python:
avrix_seller_api.modelshas aTypedDictfor every request body and every responsedata;iter_items()anditer_pages()followmeta.nextCursorfor any list method. - PHP:
Generated\Shapesdeclares a PHPStan array shape for every request body and responsedata;Paginator::items()andPaginator::pages()followmeta.nextCursor. - All three: readable method names next to the generated ones, for example
pullKeysforpullKey,revokeApiKeyfordeleteKeyandsendTestWebhookforcreateTest. 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 onlist_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_toolsandexplain_toolname 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_ordersreturned key pull transactions (GET /transactions), one row per key, although it is described as listing orders. It now readsGET /orders: one row per order, filtered bystatus,fromandto, or the single order fororderReference.- The previous rows stay available: pass
source: "transactions"tolist_orders, or calllist_transactions. seller_api_export_keysnow checks for theseller:keys:exportscope, the scope the route requires, instead ofseller:keys:pull. Key export stays off on the hosted connector.- Who must act: agents or prompts that read per-key rows from
list_orders: passsource: "transactions"or uselist_transactions.
Documentation: the helpers README used a base URL that doubled the path#
- The
@avrix/seller-api-helpersREADME configured the generated client withhttps://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 hosthttps://api.avrix.ioandcreateSellerApi(). - 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 /keysandPOST /keys/{id}/rotate. A retry with the same key and body replays the first answer withIdempotency-Replayed: trueand acts once; the same key with a different body answers409 IDEMPOTENCY_KEY_MISMATCH, and a retry while the first call still runs409 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 /keysomitskey, a replayedPOST /keys/{id}/rotateomitssecret, and both carrysecretRedacted: true. A replayedPATCH /webhooks/{id}rotation returns the secret the first call minted while it is still the endpoint's secret, andsecretRedacted: trueonce 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}/rotatetakes an optional body,{ "overlapSeconds": n }(60 to 86400). The replaced secret then keeps working untilpreviousSecretExpiresAt, 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 withoutoverlapSecondsor a revoke ends the window. The window coversAuthorization: Bearerwith the secret, notPOST /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
overlapSecondsoutside 60 to 86400 answers422 VALIDATION_FAILED. - Who must act: nobody. Rotate with
overlapSecondsso a lost response never locks you out.
Added: paging and state fields on webhook and promotion writes#
POST /webhooks/{id}/deliveries/replayreturnshasMoreandnextSince: when the window held more deliveries thanlimit, call again withsinceset tonextSince.PATCH /webhooks/{id}withrotateSecret: truereturnspreviousSecretExpiresAt: until when deliveries are also signed with the replaced secret.- Share accept and decline, and deal respond, return the promotion's
statusafter the call. - Who must act: nobody.
Fixed: a refund that fails part-way changes nothing#
POST /refundsquarantined the keys and then stamped the sale in a second write. When that second write failed the request answered500with the keys already quarantined, and a retry answered409 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 answers5xxcan be retried with the sameIdempotency-Key.- Who must act: nobody. If a refund answered
500and then409 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/requestssent 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, or409 CONFLICTon contract date2026-12-01and 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-01and later,POST /promotions/shares/{shareId}/accept,.../declineandPOST /promotions/deals/{responseId}/respondon a promotion that already has an answer return200with itsstatuswhen the answer is the same (a retry of a call that worked), and409 CONFLICTwithdetails.reason(SHARE_ALREADY_RESPONDEDorRESPONSE_ALREADY_ANSWERED) anddetails.currentStatuswhen it is different. Earlier dates keep400 BAD_REQUESTfor both. - Who must act: integrations that pin
2026-12-01and branch on the400of a repeated answer: treat the200as success and handle the409.
Changed behaviour (contract date 2026-12-01 only): webhook replay does not clone replays or test deliveries#
- On contract date
2026-12-01and later,POST /webhooks/{id}/deliveries/replayleaves out deliveries that are themselves replays (their payload carriesreplay) 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-01and replay a replayed delivery on purpose: replay the original delivery instead.
Documentation: POST /allocations/requests never required Idempotency-Key#
- Idempotency listed
POST /allocations/requestsamong 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=andPOST /orders/{orderId}/fulfilllooked 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 answered404 NOT_FOUNDalthough 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 a404on 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/bulklines,POST /orders/commit,GET /orders(lookup, cart and list),GET /orders/{orderId}, and theorder.fulfilledandorder.preorder_fulfilledwebhooks. For an order placed from this release on it is the same value everywhere; store it, and use it withGET /orders/{orderId},GET /orders?orderReadableId=andPOST /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 andGET /orders/{orderId}could name the same order with a differentord_value. Both values of an order placed before this release keep resolving on every lookup. - The pre-order variant of
POST /ordersalready returnedorderIdandstatus; the API reference now declares them. Reference correction:createOrder(SellerOrderPreorderData). - Who must act: nobody. New integrations: store
orderId.
Deprecated: orderReadableId on order responses#
orderReadableIdon order responses, bulk lines, the aggregate'sfulfilledlines and theorder.fulfilledwebhook is deprecated in favour oforderId. It stays in every response; no sunset date is set. On contract date2026-12-01and later it carries the same value asorderId.- The
orderReadableIdquery parameter ofGET /ordersis not deprecated: it takes any order id. - Who must act: nobody now. When you next touch the code that stores the order id, read
orderIdinstead.
Changed behaviour (contract date 2026-12-01 only): orderReadableId holds the order's one id#
- On contract date
2026-12-01and later, everyorderReadableIdin an order response (POST /orders,POST /orders/bulk,POST /orders/commit,GET /orders,GET /orders/{orderId}) holds the same value as the response'sorderId, and aGET /orderslist row'sorderIdis the order's one id in both read models. - On earlier dates and unpinned requests,
orderReadableIdkeeps 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 asorderId. 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 sendsnext) and comparesorderReadableIdvalues stored before this release with values read afterwards: compare onorderReference, or look the stored value up withGET /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 withCache-Control: private, max-age=60, so a client with an HTTP cache polling an order forready, or after a refund, could read a state up to a minute old. On contract date2026-12-01and later it is sent withCache-Control: private, no-store, likeGET /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 sendsnext) and relies on its HTTP cache to absorb repeated order reads: expect each read to reach the API and count against theordersrate 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'seconomics(currencyCode,currencyExponent,quantity,unitPriceCents,initialUnitPriceCents,totalPriceCents,promo,publisherShareCents,sellerShareCents,platformFeeCents,revenueSharePercent,vatMinor,netMinor,transactionIds). It is on the fulfilledPOST /ordersresponse, each deliveredPOST /orders/bulkline, and theGET /ordersandGET /orders/{orderId}aggregates. - It is
nullwhen 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'srefundsand in the finance reads. - Who must act: nobody. To record cost of goods at checkout, read
economicsinstead of a second call toGET /finance/api-sales.
Added: GET /whoami says which order read model the environment uses#
capabilities.orderReadModelisdurable(orders are read from the order table, which holds every status) orreconstruction(orders are rebuilt from delivered keys, so the order listing holdsfulfilled,returnedandrefundedorders 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 /ordersaccepts anorderReferenceof up to 255 characters, butPOST /orders/recover-keysrefused one over 128 with422, 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 theGET /ordersandPOST /orders/cancelreference fields: a longer value matches no order.- Who must act: nobody.
Documentation: GET /orders and the order guides give one answer per question#
GET /ordersis 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; its404and422descriptions 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
metakeys, described once on the new Lists and pagination page. Keys a list already had keep their names and values; only missing ones were added:hasMoreonGET /partners,GET /keys,GET /webhooks,GET /webhooks/{id}/deliveries,GET /promotions/shares,GET /promotions/deals,GET /activity,GET /refundsandGET /events;nextUrlonGET /activity,GET /finance/ledger,GET /events,GET /catalog/changesandGET /availability/changes;limitonGET /events,GET /catalog/changesandGET /availability/changes;- a
metaobject on theGET /finance/statementsJSON response, besidedata.nextCursoranddata.truncated, which keep their meaning.
GET /catalog/changesandGET /availability/changesalso send theX-RateLimit-*headers.- Reference correction:
listPartners,listPromotionsShares,listPromotionsDealsandlistWebhooksDeliveriesalready returnedmetawithlimit,count,nextCursorandnextUrl; the API reference now declares it. - Who must act: nobody. New code can loop on
meta.hasMoreeverywhere.
Added: X-Next-Cursor on every CSV export, readable from a browser#
- The
GET /finance/statementsandGET /finance/api-salesCSV downloads send the next cursor inX-Next-Cursor, like the ledger and activity exports. The statement keepsX-Avrix-Statement-Next-Cursor, with the same value. X-Next-CursorandX-Avrix-Statement-Next-Cursorare now listed inAccess-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/sharesandGET /promotions/dealspaged 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}/deliveriesstopped 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
cursorofGET /finance/api-saleswas a numeric offset string. It is the opaquemeta.nextCursorvalue, 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.nextCursorunchanged instead.
Changed behaviour (contract date 2026-12-01 only): an unreadable list cursor answers 422#
- On contract date
2026-12-01and later, a paged list refuses acursorit cannot read with422 VALIDATION_FAILED,details.issues[].fieldcursor: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 /transactionsandGET /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 sendsnext) 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
cursororsinceolder 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 date2026-12-01and later,GET /catalog/changesandGET /availability/changesanswer409 CATALOG_RESYNC_REQUIREDwithdetails.reasonretention_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/changesrefuses alimitthat is not a whole number from 1 to 5000 with422, and both feeds give their422thedetails.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 keepdetails.field. - Positions deleted before this release are not recorded, so the
409covers rows deleted from this release on. - Who must act: an integration that pins
2026-12-01(or sendsnext): handle the409by taking a freshGET /catalog/snapshotand continuing from itsmeta.changesCursorandmeta.availabilityCursor(error reference). If you already handleCATALOG_RESYNC_REQUIREDfor 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 whilemeta.hasMorewas true. On contract date2026-12-01and later each page is filled with sellable allocations up tolimit. 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
metakeys, 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 fromsinceand stop whennextCursoris absent: start from the snapshot'smeta.changesCursorand loop onmeta.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 stablenoticeId, acategory,actionRequired, a plain-texttitleandsummary,effectiveAt, thecontractDateit concerns, the operations or events itaffects, and aurlwith the details. See the event reference. - It is sent only to endpoints whose
eventsinclude it, so no existing endpoint receives anything new.GET /webhooks/event-types,POST /webhooksandPATCH /webhooks/{id}accept it, and a sandbox key can test-fire it withPOST /webhooks/{id}/test. The catalog now has 41 events. - Who must act: nobody. To hear about changes without reading this page, add
platform.noticeto an endpoint'sevents.
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 aLinkto the explanation. A request that sends noX-Avrix-Api-Versioncan 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.versionwas2026-09-08, which is not a contract date. It is now2026-09-01: the date an unpinned request is served, the date the SDKs pin and the date in their version number. A newinfo.x-avrix-contract-datesobject 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_VERSIONconstant (Python and PHP) moves to2026-09-01with the next regeneration; method signatures do not change. - Who must act: nobody, unless a tool of yours compares
info.versionto 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,FixedorDocumentation) and ends with who must act;BreakingandChanged behaviourentries 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 withX-Avrix-Api-Version: 2026-12-01, or sendnext, which now resolves to it. The stamped default for unpinned requests stays2026-09-01. The new date includes everything on2026-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
nexton 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-01and later, a write that requiresIdempotency-Keyand receives none, or a malformed one, answers400 IDEMPOTENCY_KEY_REQUIRED.details.idempotencyiskey_missingorkey_invalid, anddetails.maxLengthanddetails.patternstate the format (1 to 64 characters fromA-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_REQUESTwith the message "Idempotency-Key header is required for this operation." - Who must act: only an integration that pins
2026-12-01(or sendsnext) and matches onBAD_REQUESTfor this refusal: match onIDEMPOTENCY_KEY_REQUIREDas 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(holdIdis a UUID),POST /refundsandPOST /keys/return(keyIdsare UUIDs),POST /promotions/deals/{responseId}/respond(decisionisapprovedorrejected),POST /api/seller/oauth/token(client_idis the key's UUID).POST /keysnow leads with an example that is accepted as written; the allowlist examples say that203.0.113.10is a documentation address to replace with your own. - Corrected response examples that did not match their schema:
GET /orders(lookup mode), the409examples ofPOST /orders, andGET /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}andGET /promotions/shares/{shareId}/discountslistedlimit,cursorand (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 /transactionsto Orders;/me/footprintand/me/integration-presetsto 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}acceptedseller:products:readonly, so a key holding the documentedseller:orders:readlisted orders but was refused403 FORBIDDENon a single order. It now accepts the same four scopes asGET /orders:seller:orders:read,seller:orders:write,seller:products:readandseller: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
403now namesseller:orders:readas the missing scope. - Who must act: nobody. If you added
seller:products:readto 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-RemainingandX-RateLimit-Resetare 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 and429. 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-Resetwas missing onPOST /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, andPOST /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 allowlist403) 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,returnedandrefundedorders only. Astatusfilter 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-01and later that request answers422 VALIDATION_FAILED:details.issues[0].fieldisstatus, the message names the value, anddetails.issues[0].allowedValueslists 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:
200withdata: []andmeta.nextCursor: null. - Who must act: only an integration that pins
2026-12-01(or sendsnext) and filters the listing on one of those statuses: handle the422, or look the order up byorderReference. 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-01and later, a request whose key lacks the scope the operation needs answers403 INSUFFICIENT_SCOPE.details.requiredScopeslists every scope the operation accepts, preferred first, anddetails.scopeModesays whether one of them is needed (anyOf) or any Seller API scope will do (any).details.missingScopenames the preferred scope. See the error reference. - Unpinned requests and every earlier contract date keep the response they have today:
403 FORBIDDENwith the same message and the samedetails.missingScopeanddetails.requiredScopes. Scopes added to an operation in this release do not appear in that older body. POST /keysalready answeredINSUFFICIENT_SCOPEwhen 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 sendsnext) and matches onFORBIDDENwithdetails.missingScopefor a scope refusal: match onINSUFFICIENT_SCOPEas well.
Added: scopes that match the action#
- New scope
seller:allocations:writefor the two allocation writes,POST /allocations/requests(ask a vendor for more stock) andPATCH /allocations/{id}(top-up settings). Both still acceptseller:orders:writeandseller: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 acceptseller:orders:write, as the scope matrix said they did. GET /activity, the settlement feed, now acceptsseller:finance:read, the scope of the other finance reads.seller:products:readis still accepted.GET /me/footprintandGET /me/integration-presetscan be read by any Seller API key. Changing either still needsseller: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 /orderscarries:keyIds,totalCents,currencyCode,currencyExponent,createdAt,fulfilledAtandupdatedAt. Each has the value the order's listing row has, includingnullwhere 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, andseller:products:readon 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 /usageresponse 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 carriestruncated(boolean) andmaxCountedRequests(50000). Whentruncatedistrue, narrowfromandtountil it isfalseand 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 routes429and recorded5xxresponses always, other4xxabout 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 answers200withtraces: [], 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-MethodslistedGET, POST, PATCH, OPTIONS, DELETE, so a browser client on an allowed origin could not callPUT /me/footprintorPUT /me/integration-presets.PUTis 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 neverseller:orders:readorseller:orders:write: it now shows, for example, thatGET /ordersacceptsseller:orders:read,seller:orders:write,seller:products:readandseller:keys:pull, and thatGET /whoami,GET /access/proposals,POST /geo/attestandGET /sandbox/certificationaccept a key with any seller scope. - Headers.
X-Avrix-Api-Version,X-Request-Idand the sandbox-onlyX-Avrix-Sandbox-Simulateare declared as request headers on the operations that read them, with their accepted values. Responses declareX-Request-Id,X-Avrix-Api-Version,Idempotency-Replayed,Retry-Afterand theX-RateLimit-*headers. The threeX-RateLimit-*headers are required on every success response of an operation that counts requests against a limit and declared on its429(not required there: a sandbox429simulated withX-Avrix-Sandbox-Simulate: rate_limitcarries none). On operations that count nothing (GET /health,GET /webhooks/egress-ips, the two/geo/attest/{attestId}operations and the OAuth token exchange) the429keeps itsX-RateLimit-*entries, marked not required and described as not sent by that operation; the OAuth token exchange's429sendsRetry-After. - Status codes. Operations now declare the statuses they already returned and the reference
left out:
400 UNSUPPORTED_API_VERSION,409for a reused or in-flightIdempotency-Key,413for a body over 100 KB,422for a refused path, query or body value, and the retryable503and504. Also, among others:409 NO_ACTIVE_BMAonPOST /webhooks,404on the webhook management operations,410onPOST /orders/{orderId}/extend,412onPOST /orders/commit,304onGET /productsandGET /products/{productId}. A strictPOST /orders/bulkcart that is refused when the keys are taken answers the refusing line's own code and status withdetails.strictCart; the reference now says so. Operations that read no API key say which of their listed statuses they never return. - Response fields.
GET /whoamideclaressandboxTenant,sandboxCatalogandcapabilities.requireProductionAllowlistEnabled.POST /keys/{id}/rotatereturns the new secret asdata.secret, notdata.keyas the reference said.relatedProductson product detail is insidedata.GET /keysreturnsmeta.resolvedon thechargeback.resolvedevent is the number of sales resolved, not a boolean. - Corrections a breaking-change check will flag. The reference changes, not the API:
resolvedon thechargeback.resolvedevent 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 sendstrue.data.keyonPOST /keys/{id}/rotatestays 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 therollback_incompleteoutcome of a refused strict cart, which the guide reported asrolled_backin every case. The scope matrix points tox-avrix-scopesin 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'sauthoption. - Who must act: nobody, unless you generated a client from the earlier reference: generate
it again. If your code reads
data.keyafter rotating a key, readdata.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 /refundsandPOST /keys/returnanswer the new422 REFUND_LIMIT_REACHEDabove that, with the figures indetails; nothing is refunded. Sandbox keys are not limited. See Refunds and key returns. POST /keys/returnnow honours the Content Owner's refund window, likePOST /refundswithtype: "refund": a late return answers422 REFUND_WINDOW_EXPIRED.- If the refund window cannot be read, both routes answer
503withRetry-Afterinstead of accepting the refund.
Health no longer counts a disabled endpoint's buffer as backlog#
GET /healthcomponents.webhookDelivery.pending(andbacklog.webhookDeliveriesPending) now count only deliveries that are waiting to be sent. Deliveries buffered for a disabled endpoint are reported apart asbufferedand never degrade the status. Before, one disabled endpoint with a full buffer kept the statusdegradedfor everyone.
API keys manage only keys within their own reach#
POST /keys/{id}/rotate,PATCH /keys/{id}/allowed-ipsandDELETE /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 /keyslists 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 answers403 FORBIDDEN. Add an address in the console, or with a key that is not IP-restricted. GET /keysrows carrystatus(activeorrevoked) andrevokedAt. 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.returnedis your cancel of a pre-order or backorder, not a buyer return. The registration sample shows the real response (idis a UUID, plusdeliveryProbe), the guide no longer points at a single-endpoint read that does not exist (use theGET /webhookslist), the secret rotation sample no longer sends anIdempotency-KeythatPATCHignores, and a change of pinned egress addresses is announced 14 days ahead, not 30. - Event reference. New sections for
order.activated,order.readyandchargeback.resolved.occurredAtis documented as present on every delivery.allocation.low_stockis described as it works: a fixed 10% ofquantityLimit, sent with every allocation update whileremainingis at or below it, and unrelated toreplenishThreshold. - Default contract date. Every page now says the same thing: a request without
X-Avrix-Api-Versionis served2026-09-01.nextis 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 /allocationslists it withsellable: true. An allocation without a share is not sellable (NO_SKU_SHARE); the catalog guide said it was. TheGET /allocationssample useslimit=100(the maximum) and rows keyedid, 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 FORBIDDENwithdetails.missingScope. The guides showedINSUFFICIENT_SCOPE, which onlyPOST /keysreturns. 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 toPOST /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#
currencyExponentbesidecurrencyCodeon the finance and order objects that did not carry it yet:GET /finance/api-salesrows (also statementlines[]), every statement bucket, approved settlement, settlement invoice and outstanding balance onGET /finance/statements,GET /finance/ledgerentries andmeta.balances[],GET /finance/invoicesrows,GET /finance/summaryper-currency items,GET /orderslist rows, each sale ofGET /finance/invoices/{invoiceId}/reconciliation, and theinvoice.createdandpayout.file_readywebhooks. The reconciliation file also gainspaymentCurrencyExponentfortotalCentsand the movement amounts.integrationOrderContextas echoed on finance rows and order webhooks gainscurrencyExponentfor its*Minoramounts. It is response only: do not send it.GET /productsand catalog snapshot rows gainlistPriceCurrencyExponentbesidelistPriceFromCentsandlistPriceCurrencyCode.- 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}releasepricing[]andskus[].prices[]now carrysellableandblockedReason, 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 carrycurrencyExponent, like every other price since 2026-10-10. Additive.- The
priceonGET /availability?country=andGET /availability/{skuCode}?country=rows (priceCents,currencyCode,currencyExponent,zone;nullwhen 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". OnGET /partners, the field states how the governing API agreement was signed, and a pause does not change that. Before, it readselectedwhile the agreement was paused. The pause itself is reported bypausedBmaTypes. Values and field name are unchanged.
2026-10-16#
Fallback prices say which store currency they replace#
fallbackFromCurrencyon every price object (GET /catalog/snapshot?pricing=territorysharedSkus[].territoryPrices[],GET /products/{id}/pricingprices[]andskus[].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 incurrencyCode(the highest tier cell, or the highest Steam zone, in that currency over every country of the platform), and it sells (sellable: true).nullon every other price. Additive.
2026-10-15#
Every price says whether it can sell#
sellableandblockedReasonon every price object:GET /catalog/snapshot?pricing=territorysharedSkus[].territoryPrices[],GET /products/{id}/pricingskus[].prices[]and the release-levelprices[]. 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, withsellable: falseandblockedReason: "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 saysellable: 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/reserveandPOST /ordersnow all name the first in one order, the same orderGET /availability?country=reportsblockedReasonin: 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 answersFOOTPRINT_COUNTRY_NOT_DECLARED; a SKU-locked country outside your agreement's territory answeredREGION_LOCKED_FOR_SKU, and now answersTERRITORY_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}/reconciliationreturns the reconciliation file for one payout, as JSON orformat=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. Scopeseller: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 thereconciliationPathto download. See Event reference.
A finance ledger that ties to the statement#
GET /finance/ledgerreturns 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.balancesholds the closing balances, which for a month equal the statement'sactivityTotalsfield for field. Keyset paging, acurrencyfilter andformat=csv. Scopeseller:finance:read. See The ledger.
Launch-window reservations on allocations#
launchWindowonGET /allocations. A Content Owner can reserve keys for your store during a launch window. While the window isopen,setAsidekeys 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-001and 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 freshGET /catalog/snapshotafter the move. A change-feed cursor from the shared feed, or asincefrom before the move, answers 409CATALOG_RESYNC_REQUIREDonGET /catalog/changesandGET /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_UNAVAILABLEwhile your environment is being prepared or repaired (details.retryAfterSeconds; requests are never routed elsewhere), 503SANDBOX_ENVIRONMENT_PAUSEDfor writes while Avrix repairs it (reads keep working), 422SANDBOX_SCENARIO_UNAVAILABLEand 422SANDBOX_KEY_REQUIRED. These four andCATALOG_RESYNC_REQUIREDare in theApiError.codeenum and the Error reference.
Stateful fault scenarios#
X-Avrix-Sandbox-Simulatetakes five scenarios that fail only the first attempt of an idempotent request, so the retry with the sameIdempotency-Keyand body can recover:timeout_then_successanderror_after_commit(the order is committed, then the response is replaced by a 500) onPOST /orders,webhook_delay_duplicate(order.fulfilled30 seconds late and twice with oneeventId),partial_cartonPOST /orders/bulkandsold_out_after_holdonPOST /orders/hold. They run in your store's isolated environment. See Sandbox.
Test-fire any webhook event, with receiver challenges#
POST /webhooks/{id}/testaccepts an optional body witheventType(any Seller API event, sent with a contract-valid sample payload) andchallenge(valid,invalid_signature,stale_timestamp,duplicate,previous_secret_only). Sandbox keys only; production keys keeptest.pingand receive 422SANDBOX_KEY_REQUIREDfor anything else. The202response addsdeliveryIds,eventType,challengeandtestRunId.- Test deliveries carry
testEvent. A top-leveltestEventobject (testRunId,challenge) marks every test event other than a plaintest.ping. Aprevious_secret_onlychallenge without an open rotation overlap fails with the newlastErrorvalueno_previous_secret. See Webhooks.
Automatic certification report#
GET /sandbox/certificationevaluates the 28 certification cases from your sandbox key's traffic over the last 30 days:pass,fail,not_runorneeds_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-Limitreports 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:basePriceCentsonGET /products/{id}/pricingand the snapshot'sterritoryPrices[], thepriceonGET /availability?country=, theexpand=pricingpairs onGET /products,POST /orders/previewlines, total andsettlement, thePOST /orders/holdresponse,declaredRetailon finance rows and thesku.pricing_updatedpayload. An amount iscents / 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 returns404. 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.
catalogShareModekeeps its values (allandselected).PRODUCT_EXCLUDEDstays documented as a readiness blocker but is no longer emitted, because scope is the explicit share list. - Changed:
catalogShareModeis read per connection. OnGET /partners, each connection'scatalogShareModenow comes from that connection's API agreement only. Before, it readallwhen any in-force Full catalog agreement of any model existed with that Content Owner. - Unshare emits
removedwhen it ends your access to the product.GET /catalog/changesreportsremovedwhen a Content Owner stops sharing the last SKUs of a product you can see, unless another agreement still shares that product with you. Theupdatedevent withchangedFields: ["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/changesreports each of those SKUs asupdatedwithchangedFields: ["availability"]and itsskuIdandskuCode, the entry a SKU-level delist already uses. No new event type or field. RefetchGET /products/{productId}and re-readGET /allocations(sellable). A404on 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 checksumchangesCursormoves with it; thedigeststays 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 /whoamigainsaccessByPublisher: 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 witheffectiveFrom) and proposals waiting for your answer.enforcedsays 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/proposalslists a Content Owner's offers of more countries or a currency;POST /access/proposals/{id}/acceptand/declineanswer them (withseller:account:manageand anIdempotency-Key). Nothing changes until you accept. A refusal namesdetails.accessCode, for exampleACCESS_FX_NOT_COVEREDwithdetails.currencyPair. - A narrowing can carry a date. A lock or a removed currency applies from its
effectiveFrom: until then it is listed underpendingand 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 carrydetails.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[].enforcedis false, and accepting a proposal answers409withdetails.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_CURRENCYis deprecated and no longer returned;details.floorMinoris never set. The code stays in the spec so existing clients keep parsing.all_catalog_currenciesinwhoami.permittedCurrenciesByPublisher[].currencyModenow permits exactly whatprimary_onlypermits.- 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}/pricingand the snapshot'sterritoryPricesgain an additivezone: { 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 /availabilityreturns the price per country. Each country answer gains an additiveprice: { 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/reserveon an API allocation now runs the order admission thatPOST /orders/holdandPOST /ordersrun: 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 withCURRENCY_MISMATCH.- A reserve without
countryCodeorsalesCountryCodeis refused with422 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/holdand/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 indetails.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
codeandmessageare the same refusal as before, and its field is first indetails.issues. - Issues carry more. Each issue may include
code(the refusal that field alone would get) and, for an enum,allowedValues(for examplesalesChannel:web,mobile_app,partner_embed,marketplace:<slug>).
2026-10-06#
A price per SKU#
skus[].prices[]onGET /products/{id}andGET /products/{id}/pricing: the price a sale of that SKU charges, per country (countryCode,currencyCode,basePriceCents). It is the same price as the snapshot'sterritoryPricesand 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/previewacceptsexpectedUnitPriceCents(and its deprecated aliasexpectedWholesaleUnitPriceCents). When you send it for an API-model line and it does not match the territory catalog list price, preview refuses with 409CATALOG_PRICE_MISMATCH(details.previewError), the same code and status asPOST /orders/holdandPOST /orders, and returns no quote. Previously the field was ignored and preview quoted the catalog price withcanFulfill: 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/previewdocuments every status it can return. Each refusal answers the same status asPOST /orders(since the shared status table); the spec now lists the 402PAYMENT_NOT_CLEAREDresponse and namesMINIMUM_ORDER_VIOLATION, the declaration codes,PRODUCT_NOT_SELLABLEand the buyer-network outages under 422, 404 and 503. None of these answer 404 "not found" any more.sellablenow includes payment clearance. OnGET /allocationsand the partner product SKUs, a wholesale or pre-order grant whose payment is not confirmed reportssellable: falsewith the newPAYMENT_NOT_CLEAREDreadiness blocker andrecommendedAction: 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
bothby default. The Content Owner funds the discount, so an approved promotion now lowersunitPriceCentson API-model lines onPOST /orders/preview,POST /orders/hold, reservations andPOST /orders, and the sale is billed at the discounted price.promoandlistPromoname the same source andunitPriceCentsequalsadvertisedUnitPriceCents. This includes promotions that were already live on release day.list_priceremains 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
promois alwaysnullon 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
priceCommitmentTokenas opaque, since its length and contents may change. promoon correction rows. Refund, chargeback and reinstatement rows ofGET /finance/api-sales,GET /finance/statementsandGET /activitynow carry the original sale'spromo, and thepromoIdfilter onGET /activitymatches them.initialSalePriceCentsisnullon those rows.- Secondary-currency promo sales. A sale in a permitted secondary currency now records its
promoonly 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, withinitialSalePriceCentsalwaysnull: the pre-promo price exists only in the catalog currency. - Three columns on the api-sales CSV.
GET /finance/api-sales?format=csvappendspromoSourceType,promoSourceIdandinitialSalePriceCents(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 andallocation.replenishedis sent; outside the rules an allocation request is filed for the Content Owner (the manual path is unchanged).GET /allocations/{id}/replenishmentsshows the rules and the history, which the Content Owner sees too.GET /allocationsrows carryreplenishment. 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.itemslists every key'sfulfillmentId,keyIdand link. - New
deliveryMode: "auto"follows the Content Owner's default. New webhookfulfillment.revokedwhen a link is revoked before redemption (manual, refund, chargeback, revoked key). Asking for a platform entitlement provider answers422before 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 stays2026-09-01). With it,keyson order responses andPOST /orders/recover-keysholds 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 keepstring[]. 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.windowDaysonGET /allocationsandGET /products/{id}shows it (source:publisherorsku), andPOST /refundswithtype: "refund"after it answers422 REFUND_WINDOW_EXPIRED. Chargebacks are never windowed. Content Owners set it under Products → Returns → API key replacements and refunds. - New
POST /disputes/freezeandPOST /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 afterexpiresInDays(default 30). New webhookskey.frozenandkey.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,reasonandrecommendedAction(replaceorrefund).GET /orders/{orderId}lists them underrevocations[];POST /orders/recover-keyslists them underrevoked[]instead of returning them. A revoked key can be replaced withPOST /orders/{orderId}/keys/{keyId}/replace. Content Owners revoke from Products → Key finder → Revoke sold keys. Sandbox SKUSANDBOX-REVOKE-001revokes 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-Keyrequired). 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 answers200with the key; otherwise202 pendinguntil the Content Owner approves. New webhookkey.replaced,replacements[]onGET /orders/{orderId}, error409 KEY_NOT_REPLACEABLEand sandbox SKUSANDBOX-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_upwith the allocation's newremaining) and sellability (unsellable/sellablewith the readinessreasons) changes. Start it from the snapshot's newmeta.availabilityCursor. GET /catalog/snapshot?pricing=territoryaddsterritoryPrices(every country list price) to each shared SKU, so a cold sync needs no per-product pricing call.GET /catalog/changesentries now carryskuIdandskuCodewhen the change is about one SKU (a territory price, a SKU pause);nullfor product-level changes.- The TypeScript helpers request territory pricing on
syncSellableCatalogand addsyncAvailabilityChanges. 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) orrefuse_below_reference. Under refuse, a sale whose declaredsalesTaxRatePercentis below the reference rate for the sale country answers422 VAT_DECLARATION_BELOW_REFERENCEon preview and on every committing call, before any key is pulled.GET /whoamilists the policy per Content Owner undervatDeclarationPolicyByPublisher. See Finance and settlement.
Order presets: a production order with only the essentials#
- New
GET/PUT/DELETE /me/integration-presets(scopeseller:account:manage) and a console tab (Settings → Commercial → Order presets). With presets saved, a productionPOST /orders(or bulk line) needs only the SKU, quantity,orderReference, the buyer IP and thepriceCommitmentToken; 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 /whoamishowsintegrationPresetsand lists only what is still required.integrationOrderContext.schemaVersionnow defaults to1when omitted. See Creating orders.
A refunded order reference stays spent#
POST /orders(and bulk, reserve/commit) with anorderReferencewhose order was refunded or returned now answers409 ORDER_REFERENCE_CONFLICT. Before, a fully refunded reference could be sold a second time. Use a neworderReferencefor 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 /orderson 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/previewreuses 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 /allocationsrows carryhotDropMode: true while the Content Owner has the allocation in launch mode (usePOST /orders/reserve→POST /orders/commit). Switching it on or off sendsallocation.updatedwithreason: hot_drop_mode_changedandhotDropMode. 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 andPOST /orders, andGET /availabilityreports 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.preorderEnabledandbackorderEnabledare now true by default. A Content Owner can opt its own products out of either; those requests answerPRODUCT_NOT_SELLABLE(reasonPREORDER_DISABLED) or403 BACKORDER_NOT_ALLOWED.- Send
backorderOnUnavailable: trueon every order placed after payment: when stock runs out the order becomes a backorder (status: awaiting_stock) instead of a409, and the response carriesbackorderExpiresAt. - A backorder still waiting for stock at
backorderExpiresAt(default 14 days) is cancelled, its allocation headroom released, and the neworder.backorder_expiredwebhook tells you to refund the buyer. See Order lifecycle. - New sandbox magic SKU
SANDBOX-BACKORDER-001: never in stock, so every order withbackorderOnUnavailableis 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/changescursor), preview (and an optional hold) at checkout,POST /ordersafter payment through the order recovery helper, keys shown to the buyer, signed webhooks with secret rotation, andPOST /refundson 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 /healthcomponents.consumerGeoisdegradedwhen a deployment has no (or stale) buyer geolocation data, and that degrades the top-levelstatuswith adegradedReasonsentry (still HTTP 200).whoami.capabilities.buyerGeolocationStatusmirrors 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(policyenforce_known, previouslywarn), 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_countriesanddetails.allowedCountries. Rehearse it withSANDBOX-ACTIVATION-LOCK-001(Germany only).
Checkout holds are part of production health#
GET /healthreportscomponents.checkoutHold. A deployed environment without the hold store (or with holds switched off) isdegraded, 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 /healthcarries them ascomponents.orderPathandcomponents.sandbox, andcomponents.webhookDelivery.deliveryP95Secondsreports 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
strictistrueon contract2026-09-01, which unpinned requests have used since 2026-09-01; only a request pinned to2026-04-29keeps 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/snapshotis 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 (
304revalidations are free).X-RateLimit-*reports them. - They start in shadow mode: nothing is refused.
GET /whoamireportsdata.key.rateLimitMode: "shadow". Enforcement (429 withRetry-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 areprivateand 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 themax-ageshown 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 scopeseller:keys:export.seller:keys:pullandseller:orders:writeno 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 gets403 FORBIDDENwithdetails.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_countrynow 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_reasonseparates them.
Readable product ids in paths#
GET /products/{productId},/products/{productId}/pricingand/products/{productId}/media/downloadaccept the readableprd_id that product payloads return asreadableId, as well as the UUID. A well-formedprd_id for a product you cannot see answers404 NOT_FOUND, and any other shape422 VALIDATION_FAILED.
One spelling for the country filter#
GET /products/{productId}/pricingacceptscountryCode, the spelling the availability routes already use.countrystays accepted on pricing and availability. Sending both with different values fails validation. A request that uses onlycountrygets anX-Avrix-Deprecated-Parameter: country; replacement="countryCode"response header. No sunset is scheduled forcountry.
Declared buyer IP must not be the store server#
- At buyer verification level
declared_ip, a production key'sintegrationOrderContext.consumerIpthat equals the calling server's address, or matches the key's IP allowlist, is refused with422 CONSUMER_IP_INVALIDon 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-clientwith@avrix/seller-api-helpers(npm),avrix-seller-api(PyPI) andavrix/seller-api(Packagist) are generated from the OpenAPI document and expose every operation as a method, with typed errors that carrycode,recoverable,requestIdanddetails. See Official SDKs. - Order creation with key recovery. Each SDK ships one helper that retries
POST /orderswith the sameIdempotency-Keyand body, looks the order up withGET /orders?orderReference=, re-reads lost keys withPOST /orders/recover-keys, and reports a refund as safe only when no live keys exist. - Webhook verification and catalog mirror. The verifiers accept any
v1signature during a secret rotation; the catalog mirror seeds from the snapshot and follows theGET /catalog/changescursor. - Versions follow the contract date.
1.20260901.0targets contract2026-09-01and sends it as the defaultX-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 /ordersdeclaresfulfillmentState,transactionIdsandwarningson both the fulfilled and the pre-order shape (warningsused to sit beside them, where generated clients dropped it), plusmeta.requestId; bulk lines declarefulfillmentStateandtransactionIds;POST /webhooksdeclaresdeliveryProbe;GET /webhooksdeclaresconsecutiveFailures,disabledReasonand its paginationmeta;GET /orders/{orderId}declaresmeta. 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_UNAVAILABLEand504 HOT_PATH_TIMEOUTcan arrive after the order was fulfilled and billed. The error playbook, Idempotency and the golden path now carry one rule: retry with the sameIdempotency-KeyandorderReference, checkGET /orders?orderReference=, recover lost keys withPOST /orders/recover-keys, and refund only when no live keys exist. TheHOT_PATH_TIMEOUTentry no longer promises the order did not commit. - 409 shortfalls. The integration profiles name both codes:
NO_AVAILABLE_KEYS(vendor stock empty) andALLOCATION_EXCEEDED(your allocation cap; request more withPOST /allocations/requests). - Catalog deltas. Guides that suggested
GET /products?updatedSince=for polling now point atGET /catalog/changes: price and stock changes never move a product'supdatedAt.
Finance before the monthly report; list-price deals in every currency#
GET /finance/summaryshows the running month.currentPeriodcounts this month's API sales and their totals per currency before any monthly report exists, andpublisherRelationshipCountcounts the publishers you hold a live grant with (it read0until a report existed).noticessays when balances and reports are still waiting on the report. The response is now typed in the OpenAPI spec.- An empty
GET /finance/invoicesexplains itself. Invoices follow report approval; an empty first page while the month has sales carriesmeta.noticespointing 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
listPromoandadvertisedUnitPriceCents, so a store can show the vendor's sale price. CATALOG_PRICE_NOT_SETin 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 /healthreports queue health.components.webhookDeliveryandcomponents.outboxJobscarrypending,dueLagSeconds(how long the oldest due row has waited past its due time) andfailedLast24h. The top-levelstatusisdegradedwhen a queue is overdue or backlogged, or push delivery is not configured in production, withdegradedReasonsnaming each cause (HTTP200; only a database failure answers503). 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}returnsattemptsand, whenstatusisfailed,error { code: "EXPORT_FAILED", message, retryable }. Posting the same export again requeues it and reports its real status (it used to answerpendingwhile the export stayed failed). The gzip artifact upload that caused the failures is fixed. - Order traces.
GET /requests/{requestId}rows carryorderReferenceandoutcome, and the response listswebhookDeliveriesfor 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 (theparentOrderReferenceyou sent in itsintegrationOrderContext), in line order. The order list, order detail andGET /transactionscarryparentOrderReferenceandlineIndex, andGET /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,frkeeps only those languages inlocalizedDescriptionsandeula(a language keeps its regional variants). A single product in one language is a few kilobytes instead of every locale. Withoutlocalesthe response is unchanged.descriptionFormat=textreturns long descriptions as plain text: paragraphs, line breaks and bullet points, without the store's HTML, embedded video players or scripts.- An unknown
expandvalue is422naming it (it used to return the full payload). GET /products/{productId}/media/downloadcarries anETagcomputed from the asset list.If-None-Matchanswers304without a download, andHEADreturns 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}/pricingreports each release'slaunchPhaseandtradingState, and its deprecatedstatusnow matches the product detail. It could readdraftfor 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#
requestableon availability and onGET /allocationsnow says whatPOST /allocations/requestsaccepts: any grant of yours that is not revoked. It used to readfalseunless 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,recommendedActionisrequest_allocation_increase.- A request on a revoked grant is
409 CONFLICTwithdetails.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 /ordersbyskuId. Both now use the grant with headroom, preferring the API model; sendallocationIdto 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, sostatus=refundedcould return an empty page (with a cursor) while refunded orders sat further back. The listing now pages until it haslimitmatches or reaches the end, andmeta.nextCursorisnullwhen nothing more matches.preorderedis accepted as the name pre-orders had beforeawaiting_releaseand selects the same orders.- Unknown query parameters are refused. A
GETwith a parameter its route does not declare answers422 VALIDATION_FAILEDnaming it (?customerReference=onGET /ordersused to be ignored and returned every order). Parameters several routes already read are now declared:limit/cursoronGET /keys,/partners,/webhooks,/promotions/deals,/promotions/shares;cursoron/webhooks/{id}/deliveries;quantityonGET /availability/{skuCode}.GET /finance/api-sales?orderReference=now filters (it was ignored and returned every sale);/catalog/snapshottakes nopartner(scope rows bypublisherCompanyId). Thefilterssyntax 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) andoccurredAt; order events carryskuId,skuCode,quantityandfulfilledAt;order.keys_returnedandrefund.completedcarryorderReference/orderReferencesandkeyIds. Deliveries sendUser-Agent: Avrix-Webhooks/1. Replays and test pings useevt_…ids like live events (replays were bare UUIDs). - Failure reasons. A failed attempt reports
lastErroronGET /webhooks/{id}/deliveriesandGET /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 nonextRetryAt. - Deleting an endpoint keeps its history.
DELETE /webhooks/{id}stops deliveries and removes the endpoint from the listing; its deliveries stay onGET /eventsandGET /webhooks/{id}/deliveries(meta.endpointDeleted: true). - Cursors at the head.
GET /eventsreturnsmeta.headCursor(the resume position, also at the head); make the first call withoutcursor(the guide'scursor=0was never accepted).GET /catalog/changesat the head returns the cursor you sent instead ofnull. - 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 inmeta.notFound;GET /webhooks/egress-ipscarries apolicytext;GET /whoami-ipis limited to 60 requests a minute per IP.
Server-Timing on preview and orders; late sales recorded, not only alerted#
POST /orders/previewandPOST /ordersreturnServer-Timingwith 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
refusegeo-mismatch policy now applies whenever the sale carries evidence (the checkout attest's country, else the IP lookup of theconsumerIp), whether or not consumer geo enforcement is on: 422CONSUMER_GEO_MISMATCH_POLICY_REFUSEDon preview, hold and commit alike, withdetails.evidencedCountryanddetails.evidenceSource. Before, it ran only when enforcement was on, so a checkout pixel from another country than the declared one sold anyway.whoamireports the policy orders are judged under (refusefor an agreement that states none, with the newpolicyStated: false) instead ofnull. - Buyer IP at quote time. On a production key,
POST /orders/previewandPOST /orders/holdrefuse a body without the buyer IP (integrationOrderContext.consumerIporconsumerGeoAttestId) with the same 422VALIDATION_FAILEDPOST /ordersanswers.whoami.requiredDeclarationsByOperationlists it forpreviewandhold. commitRequirements.missingon preview and hold names every field the commit will still refuse without (payment-time fields such aspaymentProcessorReference,checkoutSessionId,salesPriceNetMinor), with aCOMMIT_FIELDS_MISSINGwarning on preview.- Hold replay. Replaying
POST /orders/holdwith the Idempotency-Key of a released, consumed or expired hold answers 404HOLD_NOT_FOUNDwithdetails.holdStateinstead 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 asholdId), andPOST /ordersacceptsholdIdas an alias ofcheckoutHoldId. The documented hold response now listsskuId,skuCode,quantity,orderReference,remainingSlotsandgeoWarning, which it already returned. - Extend by order id.
POST /orders/{orderId}/extendaccepts anord_…id: a placed order is 409ORDER_NOT_EXTENDABLE(only a hot-drop reservation, by itsreservationId, can be extended), an unknown one 404.
orderReference replay is exact; one buyer confirmation per cart#
- A repeated
orderReferencereplays only when the requestedquantityequals the live keys already fulfilled under it. A smaller quantity used to return a subset of the original keys and send a secondorder.fulfilled; it is now 409ORDER_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_EXCEEDEDorNO_AVAILABLE_KEYSinstead of504 HOT_PATH_TIMEOUT. - A
consumerGeoAttestIdis spent in the same transaction as the keys. A refused or failed order leaves it usable for the corrected retry, and a cart-levelconsumerGeoAttestIdonPOST /orders/bulkcovers every line of that cart (it used to be spent by the first line, so line 2 was refusedCONSUMER_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 /refundsorPOST /keys/returnfor a key that is already returned or refunded answers 409KEY_NOT_RETURNABLEwithdetails.keyId,details.keyStatusanddetails.businessModel(was 500INTERNAL_ERROR). A key your account never pulled is 404NOT_FOUND(was 400). POST /refundswithquantityreportsrequested,returnedandskipped[](one{ keyId: null, reason: "no_live_key" }per unit with no live key left) instead of silently refunding fewer keys.strict: truerefuses the shortfall with 409REFUND_QUANTITY_EXCEEDS_LIVE_KEYSand 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}andPOST /geo/attest/{attestId}/completevalidate the id as a UUID: 422VALIDATION_FAILED(was 500, 503 and 404).POST /promotions/shares/{shareId}/acceptand/declinefor an unknown share: 404NOT_FOUND(was 500).POST /allocations/requestsfor an unknown or foreigngrantId: 404NOT_FOUND(was 400); a publisher-side gate is 409CONFLICTwithdetails.reason. The published example now usesgrantId/requestedQuantity.POST /orders/commitwhile hot-drop is off: 412HOT_DROP_NOT_ENABLED, like reserve (was 410RESERVATION_GONE, which now means a reservation that existed and expired).- Keyless fulfilment regenerate / revoke answered the undocumented code
VALIDATION_ERROR; it isVALIDATION_FAILED.
Console links on api.avrix.io#
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 /whoaminow reportsdata.key.rateLimitedinstead ofrateLimitTier. - 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 /orderswith an expired / releasedcheckoutHoldIdcommits as a plain order and reportscheckoutHold: { holdId, status: "expired", committedWithoutHold: true }.HOLD_MISMATCH/HOLD_NOT_FOUNDcarryrecommendedAction: fallback_to_post_orders_without_hold. - Pre-orders transact:
check_pull_contract_authoritynow uses the seller-aware sellability predicate, so a company withseller_api_preorder_enabledcan preview / hold / commit alaunchPhase: pre_orderproduct (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,SunsetandLinkonce 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 afterNO_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-keysand thefirstOrderCompletedgate ofGET /integration/statusloaded the seller's whole grant list and filtered pulls with oneIN (…)over every grant id. Past a few hundred allocations that request was refused and every lookup answered404 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 /eventskeyset cursor: responses carrymeta.nextCursor(keyset oncreatedAt,id) and thecursorquery parameter is honoured. Paging bysincealone could not cross a burst of more than one page of events sharing a timestamp (a poller re-read the same page forever);sincenow also keeps microsecond precision instead of truncating to milliseconds.meta.nextSinceis unchanged for older clients.- Paused agreements answer
CONTRACT_NOT_ACTIVE:POST /orders/preview,/orders/hold,/orders/reserve,/ordersand/keys/exportno longer report a SKU whose agreement is paused asSKU_NOT_FOUND/NOT_FOUND(400/404). They answer 403CONTRACT_NOT_ACTIVEwith the same code inpreviewError/holdError/reserveError/skuResolve, so a paused agreement is not mistaken for a catalog problem.GET /ordersand key recovery keep working for orders whose grant is paused. - Hot-drop commit parity:
POST /orders/commitnow returnskeyIds(key UUIDs, same order askeys) likePOST /orders, so refunds and key returns can target the delivered keys of hot-drop sales. - Key recovery: new
POST /orders/recover-keys(scopeseller:keys:pull) returns the live keys andkeyIdsalready sold under anorderReferencefor stores that lost thePOST /ordersresponse. Never pulls new inventory;GET /ordersstill never returns plaintext.
Fixes: order lookup consistency and call-log metering#
GET /orders?orderReference=right afterPOST /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 gets404 NOT_FOUNDfor an order that exists (loop case D-03).- Usage metering: every terminal response of
POST /orders,/orders/bulk,/orders/cancel,/keys/pulland the other inline-auth routes now produces exactly oneapi_call_logrow; successful orders were previously missing fromGET /usageand the admin API activity views. Routes behind the auth wrapper no longer log error responses twice.
Fixes: price changes now reach sellers#
sku.pricing_updatedwas 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, thepricingfacet onGET /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_updatedper SKU and country written, the product is listed on/catalog/changeswithchangedFields: ["pricing"], andGET /products/{id}/pricingis served fresh. Tier and scheduled-tier changes are a follow-up.
Fixes: refund callback validation detail#
POST /refunds: a request that omitstypeis now refused withdetails.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 withoutrefundReference(or a chargeback withoutchargebackReference) 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:
appliedRatePercentanddeclaredRatePercent, so you can see when the cap bound;rateReason, which says WHY that rate applied.fallback_store_countrymeans 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;vatMinorandnetMinor, 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 /activityreturns settlement entries (sale+1,refund/chargeback−1, custody-onlypull+1, keylessreveal0) with a keysetcursor,from/to,kinds,promoId,counterpartyandorderReferencefilters andformat=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,/transactionsand/refunds.- The previous merged shape (
kind: transaction | webhook_delivery,payload) is still returned whenkindsis limited to those legacy kinds, for one release. Webhook deliveries live onGET /eventsandGET /webhooks/{id}/deliveries. - See Finance and settlement § One activity log.
Privacy: the buyer IP is resolved, then discarded#
integrationOrderContext.consumerIpis 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) andconsumerIpHash, a peppered truncated sha256.GET /finance/api-salesand statements lines therefore returnintegrationOrderContext.consumerIpHashinstead ofconsumerIp; rows recorded before this change carryconsumerIpRedacted: 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)#
detailsnow carriesreason(PREORDER_NOT_OPEN|PREORDER_CLOSED|PREORDER_DISABLED|LIFECYCLE_NOT_LIVE),productId,launchPhase,preorderStart,preorderEnd,releaseDatewhere known, and arecommendedAction(wait_for_preorder_window,wait_for_release,request_preorder_capability,delist_sku) onPOST /orders/preview,POST /ordersandPOST /keys/pull.- A pre-order becomes its release in place, so the same
skuIdturns sellable at the instants given — no successor product to look up. Status codes are unchanged (404on immediate pulls,422on pre-order acceptance) and are now both stated in the error reference.
Contract: fix-it Console links in error details (additive)#
- Error responses whose cause the key-owner company can fix in the Console
now carry
details.consoleUrl(absolute, scoped to that company) anddetails.consoleAction(review_partner_contracts,review_allocations,manage_api_keys,complete_kyb,top_up_wallet,review_partner_catalog). See Error reference § The error envelope. POST /ordersandPOST /keys/pullno longer flatten territory, activation, price-guard and geo failures to{ pullError }: the structureddetailspreview already returned (skuId,countryCode,allowedCountryCodes,declaredCountry/detectedCountry, …) are now present on commit too.pullErroris unchanged.
Contract: declared vs detected buyer country on sale rows (additive)#
GET /finance/api-salesandGET /finance/statementslines carrydetectedCountryCode(resolved from the buyer IP by the geo gate at pull time),countryMismatchandwarnings(COUNTRY_MISMATCH) next to the declaredcustomerRegionCode.GET /transactionsrows carrysalesCountryCode,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
offmode; 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/pullandPOST /orders/{orderId}/fulfillnow carryactivation({ type, countries }), the sameSkuActivationobject already onGET /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/previewlines andPOST /orders/holdnow carryinitialUnitPriceCents(catalog list price),promo(sourceType,sourceId,discountPercent,priceEffect,startDate,endDate, ornull) andpromoResolution(applied|none|unavailable) next to the existingunitPriceCents, which stays the effective figure to echo asexpectedUnitPriceCents.GET /finance/api-salesandGET /finance/statementslines carryinitialSalePriceCentsandpromo(sourceType,sourceId) so a discounted line can be attributed to the share or deal that caused it.- Fix:
POST /orders/holdpreviously 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 atPOST /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 /whoamipreviously reportedinvoiceWithinDays: 7forautomated_invoicesettlement 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 returnsnullin 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_walletandreport_onlyalready returnednull), and clients were already required to handle thenullcase. Treatnullas "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 offreport.ready/invoice.createdwebhooks 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
contractssummary reports this state instead of misfiling it: a paused MCA returnsmcaStatus: "paused"(previously"missing"), and a paused BMA appears in the newpausedBmaTypesarray (previously listed underpendingBmaTypesas 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/holdandPOST /orders/reservenow 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 withPRODUCT_NOT_SELLABLEbefore 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_UNAVAILABLEon every path — including inside the key-pull transaction, which previously proceeded to reveal keys when the state lookup found nothing.Retry-Afteris now consistently 5s (the pull path used to say 2s while the docs and preview said 5s). whoami.capabilityDetails.preorder.verifiedAtis now stamped by the modernawaiting_releaseacceptance path, not only the legacy key-locking reserve.
Contract — price binding locks the price, not the offer#
- A
priceCommitmenttoken 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 (422CATALOG_PRICE_NOT_SET/ territory rejection). Unbound commits already failed closed on any price change (CATALOG_PRICE_MISMATCH). POST /orders/holdandPOST /orders/reservenow compare yourexpectedUnitPriceCentsecho against the promotion-adjusted price — the same figure preview returns — instead of the raw list price, so an active promotion no longer produces a spuriousCATALOG_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:removedwhen the revocation ends your catalog access to the product (it also drops fromGET /products/ snapshot), orupdatedwithchangedFields: ["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 emittingremoved. - 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-01at 2026-09-01 00:00 UTC — no deploy, no separate announcement. From then an omittedstrictonPOST /orders/bulkdefaults totrue(whole-cart atomicity). PinX-Avrix-Api-Version: 2026-04-29or sendstrict: falseexplicitly to keep partial success. POST /orders/bulkresponses now echometa.contractDateandmeta.strictso the effective behavior profile is visible in the payload, not only theX-Avrix-Api-Versionheader.- All bulk examples now lead with explicit
strict: true(and the example payloads were corrected to the real request shape:items, item-levelorderReference).
2026-08-17#
Contract — stock split, catalog export, lifecycle events#
GET /availabilityaddsdedicatedAvailable,sharedPoolAvailable(sum staysinventoryAvailable), plusbackorderEligible/backorderIneligibleReason.POST /catalog/exports→202 { exportId }; pollGET /catalog/exports/{exportId}for a gzip NDJSON artifact (checksum, expiry, signed URL).catalog.export_readyfires on completion.410 EXPORT_EXPIREDafter the artifact TTL.redemption.expiredfires when a keyless link passesexpiresAt.product.delisting_scheduledfires only whenarchived_atis in the future.refundPolicy(platform default,source: "platform") is echoed onGET /allocationsandGET /products/{id}as well asGET /whoami.GET /platformsaddsversionandupdatedAt— pollversionfor registry drift.
Contract — durable preorder/backorder fulfill and settlement promotions#
POST /orderscan accept a catalogpre_orderSKU against allocation headroom whenwhoami.capabilities.preorderEnabledis true (awaiting_release). Customer-orderbackorderOnUnavailablecreatesawaiting_stockonly whenbackorderEnabledis on and the vendor grant allowsrequest_mode_backorder; otherwiseBACKORDER_NOT_ALLOWED.- Inventory arrival emits
order.ready. Reveal keys withPOST /orders/{orderId}/fulfill(seller:orders:fulfill, alsoseller:keys:pull/seller:orders:writein v1). Cancel releases headroom. - Promotions add
priceEffect(list_pricedefault,settlement_price,both). Catalog pricing stays list. Preview/commit settlement drops only for settlement-affecting windows.GET /promotions/calendarlists live/upcoming windows.
Contract — consumer geo monitor/enforce and reserve/hold gates#
CONSUMER_GEO_UNAVAILABLEis now 503 withRetry-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 includedeclaredCountry/detectedCountry— never the raw buyer IP.- During monitor mode, successful preview / reserve / hold / commit responses may include
additive
geoWarning: { code, enforcementDate? }. POST /orders/reserveandPOST /orders/holdnow run territory + consumer-geo gates on API-model allocations. Hold acceptsintegrationOrderContext.GET /whoamiaddscapabilities.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 returns503 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/bulkwith omittedstrictdefaults totrue(whole-cart atomicity). The stamped default stays2026-04-29(partial success) until a future announced rollout — pin viaX-Avrix-Api-Version: 2026-09-01or dry-run withnext. Responses now echo the effective contract date. - Recommendation unchanged: send
strictexplicitly 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-coverageso 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 ofsince; paginate withlimit(nonextCursor); wire shape isdata.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:
deferredRevealwhenimmediateFulfilment: false; persistkeyIdsfromPOST /orders(authoritative);GET /ordersnever 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 type | Example prefix |
|---|---|
Live (production) | avrix_sk_live_… |
| Sandbox | avrix_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/Warningadmonitions 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.