Refunds

1. POST /api/subscriptions/<subscription_id>/refund

Refunds a billed period. Card rail, plus wallet-covered periods on Steam. Idempotent on client_request_id.

Responses

• 200, status: "refunded": the refund ran. The receipt is in section 4.
• 202, status: "pending_approval": the refund would exceed your game’s daily self-serve limit, so nothing moved and it became a refund request for Invo to review (section 2). Branch on status; a 202 is not a refund. Refunds are authenticated with your game’s secret key, so a refund request your server did not make means that key was used by someone else: rotate your keys.
• An error, in the usual {"message", "error_code", ...} envelope (below).

Refusals

curl -sS -X POST "$BASE/api/subscriptions/SUB_1757155200_A1B2C3D4/refund" \
  -H "X-Game-Secret-Key: $GAME_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "client_request_id": "refund-2026-11-guild-42-member-7",
    "period_seq": 2,
    "reason": "member request"
  }'
# add "amount_usd": "3.00" for a partial refund; omit period_seq for the most recent billed period
# 200 {"status": "refunded", ...} or 202 {"status": "pending_approval", "request_id": ...}

import { isRefundPendingApproval } from "@invonetwork/web-sdk/server";

const r = await invo.subscriptions.refund("SUB_1757155200_A1B2C3D4", {
  clientRequestId: "refund-2026-11-guild-42-member-7",   // one per refund; reuse on retry
  periodSeq: 2,                                           // omit for the most recent billed period
  // amountUsd: "3.00",                                   // omit for the full remaining amount
  reason: "member request",                               // recommended; will become required
});
if (isRefundPendingApproval(r)) {
  // HTTP 202, over the daily limit: nothing moved; Invo reviews request r.requestId
} else {
  // r.isFullRefund, r.cardRefundedUsd, r.subscriptionCanceled,
  // r.partnerRevenueReversedUsd, r.processingFeeUsd, r.partnerTotalReversedUsd,
  // r.revenueShareAttribution?.netAttributedAmountUsd
}
// r.warnings?.[0]?.code === "REASON_RECOMMENDED" when no reason was sent

const { status, json } = await invo("POST", "/api/subscriptions/SUB_1757155200_A1B2C3D4/refund", {
  client_request_id: "refund-2026-11-guild-42-member-7",
  period_seq: 2,
  reason: "member request",
});
if (status === 200) {
  // json.status "refunded"; json.idempotent_replay true on a repeat
} else if (status === 202) {
  // json.status "pending_approval"; json.request_id; nothing moved
} else if (json.error_code === "REFUND_WINDOW_CLOSED") {
  // json.period_charged_at, json.window_closed_at
} else if (json.error_code === "REFUND_REQUEST_PENDING") {
  // json.request_id is waiting for Invo
} else if (json.error_code === "AMOUNT_EXCEEDS_REMAINING") {
  // json.remaining_refundable_usd, json.already_refunded_usd
} else if (json.error_code === "STEAM_REFUND_NOT_SUPPORTED") {
  // a Steam-charged period; nothing moved
}

r = invo.subscriptions.refund(
    "SUB_1757155200_A1B2C3D4",
    client_request_id="refund-2026-11-guild-42-member-7",   # one per refund; reuse on retry
    period_seq=2,                                           # omit for the most recent billed period
    # amount_usd="3.00",                                    # omit for the full remaining amount
    reason="member request",                                # recommended; will become required
)
if r.is_pending_approval:
    pass   # HTTP 202, over the daily limit: nothing moved; Invo reviews request r.request_id
else:
    pass   # r.is_full_refund, r.card_refunded_usd, r.subscription_canceled,
           # r.partner_revenue_reversed_usd, r.card_fee_charged_to_partner_usd, r.partner_debited_usd

status, res = invo("POST", "/api/subscriptions/SUB_1757155200_A1B2C3D4/refund", {
    "client_request_id": "refund-2026-11-guild-42-member-7",
    "period_seq": 2,
    "reason": "member request",
})
if status == 200:
    pass   # res["status"] == "refunded"; res["idempotent_replay"] True on a repeat
elif status == 202:
    pass   # res["status"] == "pending_approval"; res["request_id"]; nothing moved
elif res.get("error_code") == "REFUND_WINDOW_CLOSED":
    pass   # res["period_charged_at"], res["window_closed_at"]
elif res.get("error_code") == "AMOUNT_EXCEEDS_REMAINING":
    pass   # res["remaining_refundable_usd"], res["already_refunded_usd"]
elif res.get("error_code") == "STEAM_REFUND_NOT_SUPPORTED":
    pass   # a Steam-charged period; nothing moved

2. Refund limits

Refunds are self-serve, inside four limits:

1. Enabled per game. Refunds are enabled for every game by default. Invo can turn them off for a specific game, and then /refund answers 403 REFUNDS_NOT_ENABLED.
2. 30 days. A period can be refunded for 30 days after it was charged. After that, 409 REFUND_WINDOW_CLOSED. A retry of a refund that already ran still returns its receipt.
3. A daily limit per game. Self-served refunds per game per UTC day are limited. By default the limit is never lower than the largest single subscription charge (25000.00 USD today), in sandbox and production, so any single period can always be refunded on its own. If Invo raises the per-charge maximum, the limit rises with it. Invo can set a specific limit for your game, and that limit applies as set, even if it is lower. Reaching the limit exactly still runs; a refund that would exceed it does not run and becomes a refund request (below). A single refund larger than the limit always becomes a request.
4. A reason. Recommended now, required after a notice period (section 1).

Refund requests (the 202)

A refund over the daily limit answers 202. The body carries every key of the 200 receipt, with the values of a refund that has not happened, plus the request, so a decoder built for the receipt keeps working and simply sees that nothing moved:

{
  "status": "pending_approval",
  "idempotent_replay": false,
  "request_id": "SRR20260917150211AB12CD",
  "request_status": "pending",
  "requested_amount_usd": "40.00",
  "requested_at": "2026-09-17T15:02:11+00:00",
  "daily_cap_usd": "25000.00",
  "executed_today_usd": "24980.00",
  "message": "This refund would exceed the game's daily self-serve refund limit. ...",
  "refund_key": "subrefund:SUB_...:2:<digest>",
  "client_request_id": "refund-2026-11-guild-42-member-7",
  "subscription_id": "SUB_...", "period_seq": 2, "transaction_id": null,
  "refunded_amount_usd": "0.00", "total_refunded_amount_usd": "0.00",
  "remaining_refundable_usd": "40.00", "is_full_refund": false,
  "funding_shape": "card", "balance_delta_coins": "0.00", "card_refunded_usd": "0.00",
  "processor_refund_reference": null, "processor_refund_adopted": false,
  "invo_fee_retained": true, "partner_revenue_reversed_usd": "0.00",
  "partner_revenue_reversal_mode": "none", "reason": "member request", "refunded_at": null,
  "new_balance": "0.00", "revenue_share_attribution": null,
  "initiation": "self_serve", "refund_request_id": "SRR20260917150211AB12CD",
  "subscription_canceled": false, "subscription_status": "active",
  "processing_fee_usd": "0.00", "processing_fee_basis": "none",
  "processing_fee_borne_by": "partner", "processing_fee_transaction_id": null,
  "partner_total_reversed_usd": "0.00",
  "card_fee_charged_to_partner_usd": "0.00", "partner_debited_usd": "0.00"
}

• Branch on status. pending_approval means nothing has been refunded yet.
• The same client_request_id returns the same 202 with idempotent_replay: true. While a request is pending, any other refund of that period answers 409 REFUND_REQUEST_PENDING.
• You also receive subscription.refund_requested (section 6).
• Approved: the refund runs exactly as if your call had (the 30 days are measured from when you asked). You receive subscription.refund_approved, subscription.refunded and, for a full refund, subscription.canceled. They are sent together and may arrive in any order. A retry of your key now returns the receipt, with initiation: "approved_request" and refund_request_id set. You still bear the whole refunded amount, Invo’s card fee included. Approved refunds do not count toward your daily limit.
• Rejected: nothing moves. You receive subscription.refund_rejected with decision_reason, and your key answers 409 REFUND_REQUEST_REJECTED. Use a new key to try again; it is a new attempt, subject to the limit.

Your developer console session can list your requests: GET /api/dev/subscriptions/refund-requests?status=pending|approved|rejected|all&game_id=&limit=&offset= (default pending, limit 1 to 100, default 50) returns items (request_id, game_id, subscription_id, item_id, period_seq, client_request_id, amount_usd, reason, status, created_at, decided_at, decision_reason, transaction_id) and total. It reads only games you own (404 GAME_NOT_FOUND otherwise); 400 INVALID_STATUS and 400 INVALID_LIMIT for bad parameters. This is a console read, authenticated by your console session, not by the game key.

3. What is reversed

Card subscriptions are card only (since 2026-09-17): every period is charged to the card in full and the wallet never moves. So a card-only period is refunded in cash, full or partial:

Partials and the refund that completes them add up to exactly the card charge. Periods charged before 2026-09-17 (funded from the wallet alone, from the card alone, or both), and Steam periods the wallet covered, are refunded as they always were:

• Your revenue is reversed for the refunded portion (partner_revenue_reversed_usd, partner_revenue_reversal_mode full or prorata). Invo’s fee is retained (invo_fee_retained: true).
• You bear the whole refunded amount, Invo’s card fee included (since 2026-09-28), on any refund that returns money to a card, exactly as on a Platform Commerce card refund. Your revenue is reversed, and the rest of the refunded price (Invo’s card fee on that part, net of tax) is deducted from your revenue as its own negative line: card_fee_charged_to_partner_usd. Across partial refunds, and a partial refund followed by a lost chargeback, the fee is charged at most once in total, so the partials of one charge add up to exactly Invo’s fee on it. partner_debited_usd (and partner_total_reversed_usd, the same value) is the revenue reversed plus that fee, which equals the refunded price. A coin refund has no fee.
• No separate payment processor fee. processing_fee_usd stays on the receipt and reads "0.00", with processing_fee_basis: "none" and processing_fee_transaction_id: null. Before 2026-09-28 the payment processor’s fee on the refund was charged to you here, instead of Invo’s card fee.
• The international card fee is not returned. The 1.5% charged on a card issued outside the United States stays charged when the period is refunded.
• Example: a 100.00 USD period on the Open tier, refunded in full. Your share was 96.35 (after the 3.65 card fee); the refund debits 100.00, so you end the period at -3.65. On a card issued outside the United States your share was 94.85 (after the 1.50 international card fee), so you end at -5.15. On Merchant of Record, same non-US card: -6.65.
• The attribution is corrected: revenue_share_attribution on the receipt and the event carries net_attributed_amount_usd, the corrected figure to pay your recipient for that renewal. Nothing moves.
• A fully refunded period no longer counts toward paid_through.
• A full refund cancels the subscription immediately: status canceled, no further charges (subscription_canceled: true, subscription_status: "canceled" on the receipt). You receive subscription.canceled exactly as from the cancel endpoint (canceled_by: "partner"), with the additive cancel_cause: "full_refund". It and subscription.refunded are sent together and may arrive in any order. A partial refund leaves the subscription live. A subscription that was already canceled or expired is not canceled again. (Before 2026-09-17 a full refund did not cancel.)
• Invo emails the member when a refund executes: the amount, where it went (card or balance), and whether the subscription ended. Your reason is not included. No email is sent for a replay, a refund request or a refusal.
• A paid trial’s trial period refunds like any other period. It is period 1, charged at the trial price, so period_seq: 1 refunds up to trial_amount_usd, in cash, within the same 30 days and daily limit. You bear the whole refunded amount on it, Invo’s card fee included, as on any card refund; on a small trial price that fee is a large share of the refund. A full refund of the trial period ends the subscription, as a full refund of any period does.

4. Receipt (200)

A full refund of a card-only $9.99 period:

{
  "status": "refunded",
  "idempotent_replay": false,
  "refund_key": "subrefund:SUB_...:2:<digest>",
  "client_request_id": "refund-2026-11-guild-42-member-7",
  "subscription_id": "SUB_...",
  "period_seq": 2,
  "transaction_id": "TXN_...",
  "refunded_amount_usd": "9.99",
  "total_refunded_amount_usd": "9.99",
  "remaining_refundable_usd": "0.00",
  "is_full_refund": true,
  "funding_shape": "card",
  "balance_delta_coins": "0.00",
  "card_refunded_usd": "9.99",
  "processor_refund_reference": "<opaque reference>",
  "processor_refund_adopted": false,
  "invo_fee_retained": true,
  "partner_revenue_reversed_usd": "9.49",
  "partner_revenue_reversal_mode": "full",
  "reason": "member request",
  "refunded_at": "2026-10-20T09:12:44+00:00",
  "new_balance": "20.00",
  "revenue_share_attribution": {
    "recipient_player_id": 4242, "percent": "70.00",
    "original_attributed_amount_usd": "6.64", "refunded_attributed_amount_usd": "6.64",
    "net_attributed_amount_usd": "0.00", "settled_by_invo": false
  },
  "initiation": "self_serve",
  "refund_request_id": null,
  "subscription_canceled": true,
  "subscription_status": "canceled",
  "processing_fee_usd": "0.00",
  "processing_fee_basis": "none",
  "processing_fee_borne_by": "partner",
  "processing_fee_transaction_id": null,
  "partner_total_reversed_usd": "9.99",
  "tax_refunded_usd": "0.00",
  "card_refunded_total_usd": "9.99",
  "card_fee_charged_to_partner_usd": "0.50",
  "partner_debited_usd": "9.99"
}

Open tier, card issued in the United States: Invo’s card fee on 9.99 is 0.50 (3.5% + 0.15) and your revenue was 9.49. The refund reverses the 9.49 and charges you the 0.50, so partner_debited_usd is the whole 9.99.

• funding_shape is wallet, card or mixed. Every card period charged since 2026-09-17 is card; wallet and mixed appear on earlier periods and on wallet-covered Steam periods.
• The keys from initiation to partner_total_reversed_usd were added on 2026-09-17. A stored receipt from before that date, returned by a replay, does not carry them.
• card_fee_charged_to_partner_usd and partner_debited_usd were added on 2026-09-28. A stored receipt from before that release, returned by a replay, does not carry them; read partner_total_reversed_usd there.
• A replay returns the stored receipt, which never includes new_balance or revenue_share_attribution: those two are on the live response only.
• warnings (a list of {"code", "message"}) appears only when there is something to say (REASON_RECOMMENDED, REASON_TRUNCATED), and is not part of the stored receipt a replay returns.
• initiation is self_serve for your own call and approved_request (with refund_request_id set) when Invo approved a refund request.
• processor_refund_adopted: true means the card refund had already been issued by an earlier attempt that failed before recording it, and this call recorded it; the cash date on your side may differ from refunded_at.
• A repeated client_request_id returns the stored receipt with idempotent_replay: true (or, if the receipt itself was lost, a reduced body with transaction_id and note: "This refund was already processed.").
• revenue_share_attribution is null when the subscription has no share.
• What did I earn: split.partner_revenue_usd on subscription.renewed, minus partner_debited_usd (or partner_total_reversed_usd on a receipt that does not carry it).

5. subscription.refunded

{
  "subscription_id": "SUB_...", "item_id": "guild-42-membership", "period_seq": 2,
  "transaction_id": "TXN_...", "client_request_id": "refund-2026-11-guild-42-member-7",
  "player_email": "member@example.com", "identity_id": "idn_...",
  "amount_usd": "9.99", "total_refunded_amount_usd": "9.99", "period_amount_usd": "9.99",
  "is_full_refund": true, "reason": "member request", "period_status": "refunded",
  "refund": {
    "funding_shape": "card", "balance_delta_coins": "0.00", "card_refunded_usd": "9.99",
    "processor_refund_adopted": false, "new_balance": "20.00", "invo_fee_retained": true,
    "partner_revenue_reversed_usd": "9.49", "partner_revenue_reversal_mode": "full",
    "processing_fee_usd": "0.00", "processing_fee_basis": "none",
    "processing_fee_borne_by": "partner", "partner_total_reversed_usd": "9.99",
    "card_fee_charged_to_partner_usd": "0.50", "partner_debited_usd": "9.99"
  },
  "revenue_share_attribution": { ...as on the receipt... },
  "metadata": {"guild_id": "42"},
  "initiation": "self_serve", "refund_request_id": null, "subscription_canceled": true
}

amount_usd on the event is the amount refunded by this call; total_refunded_amount_usd is cumulative for the period; period_amount_usd is what the period was billed. refund.processing_fee_*, refund.partner_total_reversed_usd, initiation, refund_request_id and subscription_canceled are additive since 2026-09-17; refund.card_fee_charged_to_partner_usd and refund.partner_debited_usd since 2026-09-28. When subscription_canceled is true, asubscription.canceled with cancel_cause: "full_refund" is sent in the same step; the two are sent together and may arrive in any order. Delivery, signature and dedupe are on the webhooks page.

6. Refund request events

subscription.refund_requested fires when a refund over the daily limit becomes a request:

{
  "request_id": "SRR20260917150211AB12CD", "status": "pending",
  "subscription_id": "SUB_...", "item_id": "guild-42-membership", "period_seq": 2,
  "client_request_id": "refund-2026-11-guild-42-member-7",
  "amount_usd": "40.00", "reason": "member request",
  "requested_at": "2026-09-17T15:02:11+00:00",
  "daily_cap_usd": "25000.00", "executed_today_usd": "24980.00",
  "player_email": "member@example.com", "identity_id": "idn_...",
  "metadata": {"guild_id": "42"}
}

subscription.refund_approved is the same with status: "approved", decided_at and transaction_id (the refund). It is sent in the same step assubscription.refunded (and subscription.canceled on a full refund); they are sent together and may arrive in any order. subscription.refund_rejected is the same with status: "rejected", decided_at and decision_reason. These three events do not carry the common subscription block. reason is null when you sent none. Subscribe to them like any other event.

7. Steam