Avrix never moves money at your payment processor. Refund the buyer at your payment provider first, then tell Avrix, so the keys of that sale leave circulation and the sale is adjusted in settlement.
Which call to use#
| What happened | Call |
|---|---|
| You refunded the buyer | POST /refunds with type: "refund" and your refundReference |
| The buyer's bank charged the payment back | POST /refunds with type: "chargeback" and your chargebackReference, then POST /chargebacks/resolve when the bank decides |
| A payment dispute is open and the outcome is not known yet | POST /disputes/freeze, then release it or declare the refund or chargeback |
| A key is faulty and you want the Content Owner to refund or replace it | POST /returns (a return request the Content Owner decides) |
| A pre-order was never fulfilled | POST /orders/cancel (not a refund) |
POST /refunds is the one call for every refund and chargeback you give a buyer. POST /keys/return
does the same, but its refund records carry no reference you can look them up by. It is deprecated
and keeps working for integrations that already use it; no removal date is set. Refunds work the same for keys delivered by POST /orders and by
POST /keys/pull.
Where key ids come from#
Send the keyIds from the original POST /orders (or POST /keys/pull) response: persist them
with your order line, they are the source of truth. GET /orders/{orderId} lists them again. You
can also refund by count: quantity with orderReference refunds the newest live keys of that order.
Check eligibility before you refund#
POST /refunds/preview answers, per key, whether POST /refunds would accept it, why not, until
when (refundableUntil), what would happen to the key (keyDisposition) and whether it is frozen in
a dispute. It changes nothing and takes no Idempotency-Key. Send keyIds, or orderReference
alone for every live key of the order.
curl -s -X POST "https://api.avrix.io/api/seller/v1/refunds/preview" \
-H "Authorization: Bearer $AVRIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "refund",
"orderReference": "store-order-10432"
}'Which keys can be refunded depends on how they were sold:
| Business model | Key states a refund accepts | What happens to the key |
|---|---|---|
revenue_share | revealed, redeemed | held: it stays with you, the allocation headroom does not change |
| Every other model | revealed | quarantined: never sold again, the allocation headroom is restored |
revealed means the key was delivered to you. redeemed means Avrix has recorded the key as
activated. The preview answers each key's current state in keyStatus.
A key in any other state is refused with 409 KEY_NOT_RETURNABLE (details.keyId,
details.keyStatus, details.businessModel). A key you never sold is 404 NOT_FOUND. The preview
does not evaluate the refund limit, which depends on every other refund on the
allocation at the moment you call.
Declare a refund#
curl -s -X POST "https://api.avrix.io/api/seller/v1/refunds" \
-H "Authorization: Bearer $AVRIX_API_KEY" \
-H "Idempotency-Key: refund-store-10432" \
-H "Content-Type: application/json" \
-d '{
"type": "refund",
"refundReference": "re_store_10432",
"orderReference": "store-order-10432",
"keyIds": [
"3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
]
}'The request is all-or-nothing and takes 1 to 100 keys. With quantity, the response lists in
skipped (reason: "no_live_key") each unit that had no live key left; add strict: true to refuse
the whole request instead (409 REFUND_QUANTITY_EXCEEDS_LIVE_KEYS). Send an Idempotency-Key: a
retry with the same key replays the first response.
{
"data": {
"type": "refund",
"requested": 1,
"returned": 1,
"skipped": [],
"refundReference": "re_store_10432",
"chargebackReference": null,
"orderReference": "store-order-10432",
"occurredAt": null,
"keyDisposition": "quarantined",
"refunds": [
{
"id": "7c1e2a90-4b3d-4f6e-9a8b-5d4c3b2a1f0e",
"keyId": "3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"keyDisposition": "quarantined"
}
]
}
}
Each refunded key sold under the API model gets a refund record: refunds[].id is the id
GET /refunds/{refundId} reads. Avrix keeps no sale record for keys sold under the other business
models, so they get no refund record, refunds leaves them out and GET /refunds does not list them.
What happens to the keys#
keyDisposition says what the refund did. On contract date 2026-12-01 and later it is the real
outcome: quarantined, held (revenue share) or mixed (both in one call; see
refunds[].keyDisposition). Earlier contract dates always answer quarantined, whatever happened.
A quarantined key never re-enters the sellable pool: a key that reached a buyer cannot be proven
unused. Your allocation headroom is restored, but the Content Owner's stock is not, so on
GET /availability allocationRemaining rises while inventoryAvailable stays put.
A key whose order failed on Avrix's side before it reached you was never delivered: it goes straight back to stock, and no refund record or refund webhook is written for it.
Refund windows#
A Content Owner can set a refund window, for all its products or per SKU. refundPolicy on
GET /allocations and GET /products/{id} shows it (windowDays, and source: platform for no
window, publisher or sku). Within the window POST /refunds with type: "refund" and
POST /keys/return are accepted; after it they answer 422 REFUND_WINDOW_EXPIRED with each late
key's soldAt and refundableUntil, and nothing is refunded. The window runs to the moment Avrix
receives the call, not to a declared occurredAt. Chargebacks are never windowed: the bank decides
them.
refundPolicy.revealedKeysRefundable is true: a delivered key can be refunded within the window.
The older field keyRevealForfeitsRefund is deprecated and keeps its value.
Rehearse it in sandbox. Keys sold on SANDBOX-REFUND-EXPIRED-001 are already outside a refund
window of 0 days, so POST /refunds for them answers 422 REFUND_WINDOW_EXPIRED. Keys sold on
SANDBOX-REDEEMED-001 are marked redeemed right after delivery, so a refund or POST /keys/return
for them answers 409 KEY_NOT_RETURNABLE. To rehearse the retry logic of these writes, send
X-Avrix-Sandbox-Simulate: internal_error, service_unavailable or rate_limit with contract
date 2026-12-01. See Sandbox.
Refund limit#
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. A call that would go over answers 422 REFUND_LIMIT_REACHED
with the figures in details (soldInWindow, refundedInWindow, refundLimit, requested), and
nothing is refunded. Send fewer keys to use what is left of the limit. If you have a genuine wave of
refunds above it, contact Avrix support with the requestId. Sandbox keys are not limited.
Find a refund#
GET /refunds lists refund records, one per refunded API-model key. Find one by the reference you sent
(refundReference, chargebackReference), by orderReference, keyId, status or type; the
filters combine. GET /refunds/{refundId} reads one record.
curl -s -X GET "https://api.avrix.io/api/seller/v1/refunds?refundReference=re_store_10432" \
-H "Authorization: Bearer $AVRIX_API_KEY"status | Meaning |
|---|---|
completed | The refund or return is recorded |
chargeback_open | A chargeback was declared and is not decided |
chargeback_won | You won the chargeback |
chargeback_lost | The chargeback stands |
pending | Reserved; no refund is recorded in this state today |
Each record carries type (refund, chargeback or return), keyId, skuId, orderReference,
refundReference or chargebackReference, the sale price with currencyExponent, and timestamps.
GET /orders/{orderId} groups the order's refunds under refunds[], with refundIds per refund.
Chargebacks#
A chargeback declared with POST /refunds (type: "chargeback") opens at chargeback_open and
sends chargeback.opened. You own the dispute at your payment provider, so you report its outcome
with POST /chargebacks/resolve:
| Field | Type | Notes |
|---|---|---|
chargebackReference | string, required | The chargebackReference you sent on POST /refunds |
outcome | "won" or "lost", required | Won: you kept the buyer's money. Lost: the chargeback stands |
occurredAt | ISO 8601 datetime, optional | When your payment provider decided the dispute |
The outcome applies to every refund record sharing that chargebackReference, in one atomic update.
The response reports resolved, the number of records moved, and Avrix sends chargeback.resolved.
A won outcome restores the Content Owner's revenue share and the platform commission on a later
settlement. The keys stay out of circulation either way.
404when thechargebackReferencematches no chargeback of yours.409when the chargeback is no longerchargeback_open;details.currentStategives its state. A resolved chargeback cannot be resolved again.422for a malformed body.
Dispute freezes#
While a payment dispute is open, freeze the delivered keys with POST /disputes/freeze (keyIds,
reason: payment_dispute, fraud_review or chargeback_inquiry, optional disputeReference and
expiresInDays, default 30, at most 90). Frozen keys are withheld from POST /orders/recover-keys
(listed under frozen[]) and cannot be replaced. The freeze ends:
- when you release it with
POST /disputes/{freezeId}/release(dispute withdrawn or won); - when
POST /refundsrefunds or charges back its keys (status: converted); on contract date2026-12-01and laterPOST /keys/returnends it too; - at
expiresAt.
GET /disputes lists your freezes (filters status, disputeReference, keyId) and
GET /disputes/{freezeId} reads one, with its keys and how it ended. key.frozen and key.unfrozen
(with resolution: released, expired, refunded or chargeback) report every change.
curl -s -X GET "https://api.avrix.io/api/seller/v1/disputes?status=active" \
-H "Authorization: Bearer $AVRIX_API_KEY"Return requests to the Content Owner#
A return request asks the Content Owner to refund or replace keys, for example a key that does not
activate. The Content Owner decides; you do not refund the buyer through Avrix. File it with
POST /returns (keyIds, reasonCode, requestedResolution: refund or replacement, optional
details). The Content Owner is taken from the keys: file one request per Content Owner and per
business model. Return requests cover keys sold under the api and revenue_share models, within 90
days of the sale; reasonCode: "unused_keys" always resolves as a refund.
curl -s -X POST "https://api.avrix.io/api/seller/v1/returns" \
-H "Authorization: Bearer $AVRIX_API_KEY" \
-H "Idempotency-Key: return-request-10432" \
-H "Content-Type: application/json" \
-d '{
"keyIds": [
"3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
],
"reasonCode": "key_invalid",
"requestedResolution": "replacement",
"details": "The buyer reports the key is rejected on activation."
}'status | Meaning |
|---|---|
pending | Waiting on the Content Owner, due by respondBy |
info_requested | The Content Owner asked you a question (return.information_requested) |
approved, resolved | Accepted; resolution says how (return.decided) |
rejected | Turned down (return.decided) |
cancelled | You withdrew it with POST /returns/{returnRequestId}/cancel |
To answer a question, attach files with POST /returns/{returnRequestId}/evidence
(multipart/form-data, one image or PDF of at most 10 MB in the file field), then reply:
curl -s -X POST "https://api.avrix.io/api/seller/v1/returns/0b6e4f1a-2c3d-4e5f-8a9b-1c2d3e4f5a6b/reply" \
-H "Authorization: Bearer $AVRIX_API_KEY" \
-H "Idempotency-Key: return-reply-10432" \
-H "Content-Type: application/json" \
-d '{
"message": "Screenshot of the activation error attached."
}'GET /returns lists your requests and GET /returns/{returnRequestId} reads one with its keys, the
message thread and the evidence. A refusal names the cause in details.reason: 422 KEY_NOT_RETURNABLE (for example claim_window_expired, key_status_ineligible,
publisher_mismatch, mixed_business_model), 409 CONFLICT (key_in_open_request, or
illegal_transition when the request is not in a state that allows the call) and 404 NOT_FOUND
(key_not_owned).
Order status after a refund#
On contract date 2026-12-01 and later an order's status follows its keys: a partial refund leaves
the order fulfilled, and it reads refunded once every key is refunded. Earlier contract dates mark
the orderReference you send on POST /refunds as refunded as soon as one key is refunded.
Webhooks#
refund.completed: the refund record, withrefundReferenceorchargebackReference,refundIds,keyDispositionandsaleTotals.order.keys_returned: the inventory side, the keys that left circulation.chargeback.openedandchargeback.resolved: the chargeback's life.key.frozenandkey.unfrozen: dispute freezes.return.information_requestedandreturn.decided: return requests.
See the event reference for every field.
Scopes#
Reading refunds, disputes and return requests accepts any one of seller:refunds:read,
seller:refunds:write, seller:finance:read or seller:orders:write. Declaring a refund or
chargeback, freezing keys and filing or answering a return request accept seller:refunds:write or
seller:orders:write. Keys that hold the legacy seller:keys:pull keep working on all of these. The
scope matrix lists every operation with its scopes.
Returning keys without a reference#
POST /keys/return takes delivered keys out of circulation with the same rules as POST /refunds
(eligibility, refund window, refund limit) but records no refund or chargeback reference. It is kept
for existing integrations and is deprecated; new integrations use POST /refunds.
curl -s -X POST "https://api.avrix.io/api/seller/v1/keys/return" \
-H "Authorization: Bearer $AVRIX_API_KEY" \
-H "Idempotency-Key: return-store-10432" \
-H "Content-Type: application/json" \
-d '{
"orderReference": "store-order-10432",
"keyIds": [
"key_replace_me"
],
"reason": "customer_refund"
}'