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.

Other 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

const receipt = 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",
});
// receipt.isFullRefund, receipt.cardRefundedUsd, receipt.balanceDeltaCoins,
// receipt.partnerRevenueReversedUsd, receipt.revenueShareAttribution?.netAttributedAmountUsd

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 (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
}

receipt = 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",
)
# receipt.is_full_refund, receipt.card_refunded_usd, receipt.balance_delta_coins,
# receipt.partner_revenue_reversed_usd, receipt.revenue_share_attribution.net_attributed_amount_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 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. What is reversed

A renewal can have been funded from the wallet alone, from the card alone, or both. The refund puts the member back where they were:

• Partials that add up to the full amount compose correctly: the completing refund returns the card charge and reclaims the coins handed out earlier.
• 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).
• 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. The subscription itself is not cancelled; cancel it separately if that is what the member wants.

3. Receipt (200)

{
  "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": "mixed",
  "balance_delta_coins": "20.00",
  "card_refunded_usd": "7.99",
  "processor_refund_reference": "<opaque reference>",
  "processor_refund_adopted": false,
  "invo_fee_retained": true,
  "partner_revenue_reversed_usd": "8.69",
  "partner_revenue_reversal_mode": "full",
  "reason": "member request",
  "refunded_at": "2026-11-10T09:12:44+00:00",
  "new_balance": "20.00",
  "revenue_share_attribution": {
    "recipient_player_id": 4242, "percent": "70.00",
    "original_attributed_amount_usd": "6.08", "refunded_attributed_amount_usd": "6.08",
    "net_attributed_amount_usd": "0.00", "settled_by_invo": false
  }
}

• funding_shape is wallet, card or mixed.
• 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.

4. 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": "mixed", "balance_delta_coins": "20.00", "card_refunded_usd": "7.99",
    "processor_refund_adopted": false, "new_balance": "20.00", "invo_fee_retained": true,
    "partner_revenue_reversed_usd": "8.69", "partner_revenue_reversal_mode": "full"
  },
  "revenue_share_attribution": { ...as on the receipt... },
  "metadata": {"guild_id": "42"}
}

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. Delivery, signature and dedupe are on the webhooks page.

5. Steam