Refunds & returns

Key quarantine, refunds API, and why Avrix never refunds your PSP.

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 happenedCall
You refunded the buyerPOST /refunds with type: "refund" and your refundReference
The buyer's bank charged the payment backPOST /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 yetPOST /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 itPOST /returns (a return request the Content Owner decides)
A pre-order was never fulfilledPOST /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 modelKey states a refund acceptsWhat happens to the key
revenue_sharerevealed, redeemedheld: it stays with you, the allocation headroom does not change
Every other modelrevealedquarantined: 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.

JSON
{
  "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"
statusMeaning
completedThe refund or return is recorded
chargeback_openA chargeback was declared and is not decided
chargeback_wonYou won the chargeback
chargeback_lostThe chargeback stands
pendingReserved; 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:

Diagram
FieldTypeNotes
chargebackReferencestring, requiredThe chargebackReference you sent on POST /refunds
outcome"won" or "lost", requiredWon: you kept the buyer's money. Lost: the chargeback stands
occurredAtISO 8601 datetime, optionalWhen 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.

  • 404 when the chargebackReference matches no chargeback of yours.
  • 409 when the chargeback is no longer chargeback_open; details.currentState gives its state. A resolved chargeback cannot be resolved again.
  • 422 for 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 /refunds refunds or charges back its keys (status: converted); on contract date 2026-12-01 and later POST /keys/return ends 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."
}'
statusMeaning
pendingWaiting on the Content Owner, due by respondBy
info_requestedThe Content Owner asked you a question (return.information_requested)
approved, resolvedAccepted; resolution says how (return.decided)
rejectedTurned down (return.decided)
cancelledYou 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, with refundReference or chargebackReference, refundIds, keyDisposition and saleTotals.
  • order.keys_returned: the inventory side, the keys that left circulation.
  • chargeback.opened and chargeback.resolved: the chargeback's life.
  • key.frozen and key.unfrozen: dispute freezes.
  • return.information_requested and return.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"
}'

What links here

Published guides that link to this page.

Search docs

Search documentation…