Every webhook event the Seller API can deliver: 79 event types, one section each, the same list
GET /webhooks/event-types returns. Subscribe only to events you handle. Delivery is at-least-once: dedupe on eventLogId / X-Avrix-Event-Log-Id, which is the same for one event on every endpoint, retry and replay.
Every event is also recorded in your event log, which GET /events serves on contract date 2026-12-01 and later whether or not an endpoint subscribes.
# Verification is server-side in your webhook handler — not a curl call.# Header: X-Avrix-Signature: t=<unix>,v1=<hex>[,v1=<hex>] (two v1 during a secret rotation; accept either)# Signed payload: "{t}.{rawBody}" with HMAC-SHA256 and your endpoint secret.
Every delivery is one flat JSON object. Five envelope fields are present. Avrix sets
eventId, eventLogId, eventType and eventVersion, and event data can never override them;
occurredAt is the event's own time when it has one. Every other top-level field belongs to the
event:
eventId is the same value as the X-Avrix-Event-Id header. It is minted per delivery: the
same event sent to two of your endpoints carries a different id on each, and a replay carries a
new one.
eventLogId is the same value as the X-Avrix-Event-Log-Id header. It is the event's own id:
one value per event, the same on every endpoint, retry and replay, and the id of the event in
GET /events. Dedupe on it. Test deliveries (POST /webhooks/{id}/test) are not events and
carry none; neither do deliveries created before the event log existed, nor, in rare cases, an
event that could not be recorded. Fall back to replay?.originalEventId ?? eventId when it is
absent.
The X-Avrix-Delivery-Id header names the delivery row, as GET /webhooks/{id}/deliveries lists
it; use it when you report a delivery problem.
eventType is the same value as X-Avrix-Event-Type; switch on it.
eventVersion is a string ("1" today), the same value as X-Avrix-Event-Version.
occurredAt is on every delivery: the time the event happened where the event records one,
otherwise the time the delivery was created.
There is no data wrapper and no envelope-level createdAt. Other timestamps are
event-specific (updatedAt, emittedAt, sentAt, readyAt, …).
A delivery created by POST /webhooks/{id}/deliveries/replay carries a fresh eventId, the
original eventLogId, and a top-level replay object,
{ "sourceDeliveryId": "…", "originalEventId": "…" }. See Webhooks.
Every example below is a full delivery body: the envelope first, then the event's own fields.
Fields are typed per event in the OpenAPI webhooks section.
Every event Avrix raises for your company is recorded once in your event log, whether or not one
of your endpoints subscribes to it, and kept 30 days. On contract date 2026-12-01 and later
GET /api/seller/v1/events serves it, oldest first:
id and eventLogId are the id every webhook delivery of the event carries, so a store that
takes both webhooks and the feed dedupes on one value.
payload is the event's own fields, exactly as the webhook delivery carries them.
Filter with eventType (comma-separated, or the parameter repeated; at most 20 names from
GET /webhooks/event-types), resourceType and resourceId. An unknown event name is refused
with 422 VALIDATION_FAILED.
Store meta.headCursor after every page and send it back as cursor on your next poll. The feed
reads a few seconds behind the present, so an event recorded a moment before another is never
passed over.
meta.retainedFrom is the oldest instant the log still holds. When your cursor or since is
older, meta.positionBeforeRetention is true: events between your position and retainedFrom
may have been deleted. Reconcile from the resources (orders, allocations, catalog), then carry on
from headCursor.
order.cancelled is recorded once; endpoints subscribed to its older name order.returned
receive the same event under that name, with the same eventLogId.
On earlier contract dates GET /events keeps returning webhook delivery rows, one per delivery
to each of your endpoints. The filters are not read there: they are refused with
422 VALIDATION_FAILED naming them, so a filter is never silently dropped.
What each event is about, for resourceType and resourceId:
The body names what was sold (skuId, skuCode, quantity, fulfilledAt), so a store that
queues bodies and processes them later does not need GET /orders/{orderId} per event. Webhook
payloads never include key plaintext.
Preorder or hot-drop reservation accepted; keys not yet delivered
Seller action
Show “reserved / shipping later” to the buyer. For an order placed with POST /orders, wait for order.ready, then call POST /orders/{orderId}/fulfill; for a key-locked pre-order (bulk line), wait for order.preorder_fulfilled. See pre-orders
A backorder now has inventory for its full quantity, or a deferred pre-order has inventory for its full quantity and its release is deliverable (unlocked, or the pre-order window closed and the release date passed); the order moved to ready. Never sent for a key-locked pre-order (preordered), which Avrix delivers at the release
Seller action
Call POST /api/seller/v1/orders/{orderId}/fulfill with the orderId from the payload, then deliver the keys from that response
Duplication
Dedupe by eventId; GET /orders/{orderId} reads status: ready until you fulfil
Related
Order lifecycle, order.backorder_expired, backorderOnUnavailable on POST /orders
A key-locked pre-order (bulk line) was delivered automatically at its release date. Also sent, deprecated, beside order.fulfilled when you fulfil a pre-order placed with POST /orders
Seller action
Carries no keys. For a key-locked pre-order, read them with POST /orders/recover-keys and the orderReference, then deliver them. For an order you fulfilled yourself, act on order.fulfilled and ignore this event
Duplication
Dedupe; may pair with aggregate changes on GET /orders
A customer-order backorder (backorderOnUnavailable) was still awaiting_stock at backorderExpiresAt (default 14 days). Avrix cancelled it and released the allocation headroom
Seller action
Refund the buyer at your PSP and close the store order; no keys will follow
Duplication
Dedupe by eventId; GET /orders/{orderId} then reads status: cancelled
Related
backorderOnUnavailable on POST /orders, order.ready
Older name of order.cancelled: you cancelled a pre-order, reservation or backorder with POST /orders/cancel before its keys were delivered. Despite the name, it is not a buyer return of delivered keys: that is order.keys_returned
Seller action
Reflect cancellation in your OMS; do not expect key quarantine events. Subscribe to order.cancelled instead; an endpoint subscribed to both receives the cancellation twice, with one eventLogId
Duplication
Dedupe by eventLogId
Related
POST /api/seller/v1/orders/cancel, order.cancelled
The same fields as order.returned: reason echoes the cancel call's reason, and a cancelled
backorder or deferred pre-order carries orderId (ord_…) instead.
refundReference or chargebackReference is the reference you sent. refundIds are the refund
records (GET /refunds/{refundId}), one per key sold under the API model; keys sold under other
business models have none. keyDisposition is quarantined, held (revenue-share keys
stay with you) or mixed. saleTotals is the sale value of the refunded API-model keys per
currency, in minor units. These five fields are absent when the call recorded no refund (a return without
adjustment).
You reported the outcome of a chargeback with POST /chargebacks/resolve and the sale lines under that chargebackReference moved to chargeback_won or chargeback_lost
Seller action
Close the dispute in your records; align finance with the outcome
Duplication
Dedupe by eventId; a repeat of the same resolve call with the same Idempotency-Key replays the stored response and sends no second event
A delivered key was replaced by a fresh key from the same allocation (POST /api/seller/v1/orders/{orderId}/keys/{keyId}/replace), at once or after the Content Owner approved it
Seller action
Swap the key in your order record; read the new key from the replace response or POST /orders/recover-keys
Duplication
Dedupe by eventId or replacementId
Related
Key replacement, GET /orders/{orderId}replacements[]
The Content Owner rejected a replacement you requested with POST /api/seller/v1/orders/{orderId}/keys/{keyId}/replace
Seller action
The original key stays delivered; tell the buyer, or refund with POST /refunds or file a return request with POST /returns
Duplication
Dedupe by eventId or replacementId
Related
Key replacement, GET /orders/{orderId}replacements[]
JSON
{"eventId":"evt_1754385262108_3a5c7e9b1d2f4a60","eventLogId":"evt_1754385262101_6f8a0c2e4b6d8f1a","eventType":"key.replacement_rejected","eventVersion":"1","occurredAt":"2026-09-26T08:30:00.000Z","replacementId":"5d2c9e1a-7b3f-4c8d-9e0f-1a2b3c4d5e6f","orderId":"ord_01J8XYZ...","orderReference":"ORDER-10042","keyId":"7c1e2d3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f","reason":"invalid","decisionNote":"The key activates on our side; please ask the buyer to retry.","rejectedAt":"2026-09-26T08:30:00.000Z"}
keyId is the key you asked to replace. reason is the reason you gave; decisionNote is the
Content Owner's note, when they wrote one.
An allocation update left remaining at or below 10% of quantityLimit, and above zero. The 10% is fixed: it is not configurable, and it is not the replenishThreshold you set for automatic top-ups
Seller action
Alert merchandising / pause promotions if needed
Duplication
Sent with everyallocation.updated while the allocation stays at or below 10%, so expect one per pull, not one per crossing. Act on the first and ignore the rest until remaining rises above 10% again; do not decrement local counters blindly. For one event per crossing, subscribe to allocation.running_low instead
Related
Allocations, allocation.running_low, allocation.depleted (sent instead when remaining reaches zero), allocation.replenished
remaining fell to or below the allocation's low-stock threshold. The threshold is your replenishThreshold on the allocation (PATCH /allocations/{id}) when you set one, otherwise 10% of quantityLimit, rounded down; thresholdSource says which
Seller action
Reorder, ask for more keys (POST /allocations/requests), or warn merchandising. One event is one fall, so it is safe to page someone on it
Duplication
Sent once per crossing. It is sent again only after remaining has risen above the threshold (a top-up, a larger ceiling, a returned key) and fallen to it again. Dedupe by eventLogId
Related
allocation.low_stock (fixed 10%, repeated while low), allocation.depleted, allocation.replenished, GET /allocations/{id}
An allocation request you filed with POST /allocations/requests was decided: approved or denied by the Content Owner, or granted at once by the Content Owner's rules (auto_granted)
Seller action
On approved or auto_granted, read the allocation (allocationId) and make the SKU sellable; on denied, stop waiting and show decisionNote to whoever filed the request
Duplication
Dedupe by eventLogId; one request is decided once
Related
POST /allocations/requests, GET /allocations
JSON
{"eventId":"evt_1754385262108_5ff5cb670c0ab31c","eventLogId":"evt_1754385262101_de78a129f7c146fe","eventType":"allocation.request_decided","eventVersion":"1","occurredAt":"2026-12-01T10:00:00.101Z","requestId":"2c7e9b14-5a3d-4f81-b6e2-9d0c1a8f3e57","resolution":"approved","automatic":false,"skuId":"3f9a1c22-7b6d-4e51-9f0a-2c8e4d6b1a35","publisherCompanyId":"content-owner-co","allocationId":"b2c3d4e5-f6a7-8901-bcde-f12345678901","requestedQuantity":500,"grantedQuantity":250,"decisionNote":"Half now, the rest after launch week.","decidedAt":"2026-12-01T10:00:00.101Z"}
grantedQuantity is 0 and allocationId is null when the request was denied.
A pending allocation request was withdrawn by your company, with POST /allocations/requests/{id}/cancel or in the console, before the Content Owner decided it
Seller action
Stop waiting on it. A second integration or a person in the console may have cancelled it, so read GET /allocations/requests/{id} before filing again
Duplication
Dedupe by eventLogId; a request is cancelled once
Related
allocation.request_decided, GET /allocations/requests
Run incremental catalog sync (GET /catalog/changes or products delta)
Duplication
Coalesce into one sync job
Related
Catalog
changedFields names what changed, in the vocabulary of GET /catalog/changes (metadata,
relationships, ...), once each, when the change that sent the event knows it. It is absent
otherwise: refetch the whole product then.
effectiveAt states when the new price takes effect. For immediate changes it equals the
event's updatedAt; scheduled price changes stamp a future instant — apply the new price at
that boundary rather than on receipt. previousPricing / newPricing carry the explicit
old→new pair (previousPricing is null when no prior price existed for the country). Every
price is an integer in minor units with its own currencyExponent (previousPricing can be in
another currency than newPricing); see Money fields.
priceMinor is the price under the name every amount uses; priceCents is its older name, with
the same value.
firstSeen is true when Avrix had not seen the SKU for your company before and it is sellable
now. The very first time Avrix observes your catalog it records every SKU without sending events,
so a new integration is not flooded; use GET /allocations for that first picture.
Your connection with a Content Owner was closed: by the Content Owner (publisher), by your company (seller), or by the platform because no agreement remains (platform)
Seller action
Stop selling that Content Owner's SKUs and remove them from your storefront
A Content Owner approved or rejected a connection request your company sent. Not sent for a Content Owner's invitation, which you accept or decline yourself, or for a request you withdraw
Seller action
approved: the connection exists under connectionId, and its agreements still need signing in the console; you can trade once contract.activated arrives. rejected: read reviewNote; the request stays on GET /partners?status=rejected
A rejection carries decision: "rejected", connectionId: null and the Content Owner's note in
reviewNote (null when they left none). Until the decision, GET /partners lists the request
with connectionId equal to its requestId; after an approval the partner row carries the new
connectionId this event names.
Book it in accounting; status says whether it is payable now (payable) or waits for the commission document (awaiting_commission_document). Read it with GET /finance/invoices/{invoiceId} (lines, payment reference, document)
Duplication
Dedupe by eventLogId
Related
GET /finance/invoices/{invoiceId}, invoice.paid, invoice.overdue
A corrected invoice also carries replacesInvoiceId, the invoice it replaces; that one is now
superseded and must not be paid.
The vendor answered your dispute, or you withdrew it
Seller action
Read outcome. rejected or withdrawn: the invoice is payable again (status: payable). accepted: wait for the corrected invoice (invoice.issued with replacesInvoiceId). escalated: Avrix finance decides, and the invoice stays paused. A dispute raised before dueAt gives you back the days you waited
invoice.created is the pro-forma invoice of an allocation; invoice.issued, invoice.overdue, invoice.disputed, invoice.dispute_updated and invoice.paid follow the monthly invoices a Content Owner raises for your sales.
An invoice has two numbers. platformInvoiceNumber is the number Avrix gives it, the one
GET /finance/invoices lists; supplierInvoiceNumber is the number on the Content Owner's own
document, null when they use none. Match the events to the list on either. invoiceNumber is the
older name and keeps its value: the supplier number when there is one, otherwise the platform
number, while GET /finance/invoices sends the platform number under that name.
A monthly sales report was built for a vendor and month
Seller action
Read it with GET /finance/reports/{reportId} (totals, exchange rates, confirmation) and its lines with GET /finance/reports/{reportId}/lines; confirm or submit it in the console when confirmation.nextActor is seller
The file lists every balance movement the payout settles and every API sale under each movement:
order reference, key id, gross, VAT, net and the three shares. Movement amounts add up to
totalMinor (older name totalCents, same value) in currencyCode, the payment currency; currencyExponent is its number of
minor-unit digits (2 for EUR, 0 for JPY, 3 for KWD).
Delivered to your company's other endpoints; the disabled endpoint's own copy is buffered and
arrives after re-enable. Paired with an in-app console notification and an email to company
admins.
The early warning, about 45 hours before the circuit breaker would disable the endpoint. It is on
your event log (GET /events) whether or not any endpoint can receive it, and is delivered to the
endpoints that subscribe to it. Paired with an in-app console notification to company admins.
Avrix announces a change to the Seller API itself: a contract change, a deprecation, a change of the default contract date, the switch of rate limits to enforced, or planned maintenance
Seller action
Read summary and the page at url; when actionRequired is true, plan the change before effectiveAt
Duplication
One notice has one noticeId. Each endpoint subscribed to the event receives it once (at-least-once delivery), so dedupe on noticeId when several of your endpoints subscribe
Sent only to endpoints whose events include platform.notice; add it with PATCH /webhooks/{id}
or when you register the endpoint. It carries no data about your company, and sandbox endpoints
receive the same notices. A notice points at its changelog entry, which stays the full record.
Field
Meaning
noticeId
Stable id of the notice, the same on every delivery
category
api_change, deprecation, contract_date, rate_limits, maintenance or other. New values may be added: treat an unknown one as other
actionRequired
true when an integration may have to change something before effectiveAt
title, summary
Plain text, at most 140 and 1,000 characters
effectiveAt
When the change takes effect, or null
contractDate
The contract date the notice concerns, or null
affects
Operations (POST /orders) or event names concerned; empty when it concerns the whole API
url
Public page with the details
publishedAt
When Avrix published the notice
JSON
{"eventId":"evt_1754385262108_9b99ab33624a3af9","eventLogId":"evt_1754385262101_7eb81c6e687f0887","eventType":"platform.notice","eventVersion":"1","occurredAt":"2026-11-12T09:00:00.000Z","noticeId":"contract-date-2026-12-01","category":"contract_date","actionRequired":false,"title":"Contract date 2026-12-01 is available as an opt-in pin","summary":"Pin X-Avrix-Api-Version: 2026-12-01 to receive the corrected status codes and error codes listed in the changelog. Unpinned requests are not affected.","effectiveAt":null,"contractDate":"2026-12-01","affects":[],"url":"https://docs.avrix.io/seller-api/changelog#2026-11-12","publishedAt":"2026-11-12T09:00:00.000Z"}
Key events carry the key's id, never its secret: apiKeyId, the id GET /api-keys lists. keyId is its older name, with the same value; everywhere else in the API keyId names a game key. keyName and environment are set on api_key.created and may be null on the others.
An API key reaches its expiry (expiresAt) within 14 days. Sent once per expiry, only for keys meant to live longer than 14 days, never for a revoked key
Seller action
Create a replacement key (POST /keys, or the console), move every system that calls the API to it, then revoke the old key
An API key reached its expiry; calls with it are refused with 401. Sent once, within the hour after expiresAt, never for a key revoked before it expired
Seller action
Stop using the key. If a system still calls with it, give that system a current key
A sandbox key's certification report (GET /sandbox/certification) passed every case: the first time, and again only if it passes after a report with a failed case. Sent to the endpoints registered with that sandbox key
Seller action
Tell your Avrix partner contact or support@avrix.io that the report passes. Passing does not enable production access by itself
Duplication
Dedupe by eventLogId; firstPass is true only the first time the key's report passes
The report is evaluated when it is built (GET /sandbox/certification, the console panel, or Avrix
accepting your evidence), so a pass that comes from new traffic is announced the next time the
report is built.