Subscriptions

1. The ownership model

There are no plan objects

The price lives on the subscription. You pass amount_usd at signup and that is the agreement — there is nothing to create in advance, nothing to keep in sync, and nothing to garbage-collect when a tier is retired. Two members on "the same plan" at different prices is simply two subscriptions with two amounts. Prices are always in USD; the currency granted on each renewal is derived from it (see Virtual Currency Setup).

One live subscription per member, per item

A given member can hold at most one live subscription to a given item_id in your game. A second create attempt returns 409 ACTIVE_SUBSCRIPTION_EXISTS with the id of the one that already exists. This is the guard that survives the most common integration bug there is — regenerating your idempotency key inside your own retry loop — and stops a member being billed twice a month forever. Canceled and expired history does not block re-subscribing.

2. Lifecycle and status values

3. Dual funding — balance first, card for the shortfall

This is the part that differs most from a conventional subscription rail, and it is the part that decides your retention. On renewal day Invo spends the currency the member already holds. If that covers the renewal, no card is touched at all. If the balance is short, the difference is charged to the card on file, minted, and settled from the balance in the same transaction.

Opting out: wallet_only

Pass wallet_only: true at creation and Invo will never touch a card for that member — the renewal succeeds only if the balance covers it, and fails into ordinary dunning if it does not. The flag is deliberately sticky: attaching a card to a wallet_only subscription is refused with 409 WALLET_ONLY_SUBSCRIPTION unless you explicitly send wallet_only: false in the same call, so nobody ends up holding a billable card they believed was disabled.

4. What a successful renewal does

Every renewal produces one retrievable record — the subscription equivalent of an invoice — and one webhook. The currency grant, the fee split, the ledger entries and the webhook are all committed together: if you received subscription.renewed, the money moved.

subscription.renewed

{
  "event": "subscription.renewed",
  "data": {
    "subscription_id": "SUB_...",
    "item_id": "guild_gold",
    "period_seq": 4,
    "transaction_id": "TXN_...",
    "order_id": "ORD_...",
    "player_email": "member@example.com",
    "identity_id": "...",
    "amount_usd": "9.99",
    "amount_coins": "99.90",
    "period_start": "2026-08-01T09:14:22.481-04:00",
    "period_end":   "2026-09-01T09:14:22.481-04:00",
    "current_period_start": "2026-09-01T09:14:22.481-04:00",
    "current_period_end":   "2026-10-01T09:14:22.481-04:00",
    "next_charge_at": "2026-09-01T09:14:22.481-04:00",
    "funding": {
      "balance_applied_coins": "40.00",
      "card_charged_usd": "5.99",
      "minted_coins": "59.90",
      "new_balance": "0.00"
    },
    "split": {
      "total_usd": "9.99",
      "invo_fee_usd": "...",
      "partner_revenue_usd": "...",
      "invo_fee_percent": "..."
    },
    "revenue_share_attribution": null,
    "metadata": { }
  }
}

5. When a charge fails

Invo retries on a schedule — by default 3 retries over 7 days, then the subscription expires. The schedule is configurable per game, and the full mechanics live in Renewals & Dunning. Two things about it routinely surprise integrators:

• subscription.payment_failed fires on the FIRST failure, not the last — while the member still has access and can still fix it. That is the entire point of a grace window. The payload carries grace_period_end, retries_remaining, retry_at, and access_retained: true. Send the "top up or update your card" message here.
• Access is retained through the whole window. Neither payment_failed nor past_due is a revocation signal; both carry access_retained: true. Soft-degrade if you like, but keep the member's row. Only subscription.expired revokes.

subscription.past_due is the state transition and fires once; payment_failed is per attempt and fires on each one, with first_failure distinguishing them. If you only want "this member is in arrears", handle past_due and ignore the per-attempt traffic. subscription.expired carries final_period_end — the last instant the member actually paid for — and access_retained: false.

6. When the member must re-authenticate

What the member sees: a page Invo serves, at that exact link, that asks their bank for the confirmation and then completes the renewal. They do not re-enter card details and they do not create anything new — the page confirms the charge that already exists, which is why a double-click, a refresh, or a stale tab cannot take money twice.

What is true while a challenge is open:

• The subscription sits at awaiting_authentication, not past_due.
• No retry budget is consumed (retry_consumed: false) and the member is not expired while it is live.
• access_retained is true. Do not wire this event to your cancellation flow.
• card_amount_usd is what the card is actually being asked for — the balance shortfall, not the full renewal price.

The link is a bearer capability with its own token: single-use in effect, expiring, and not derivable from subscription_id. Relay the one in the event, never construct your own, and do not log it next to identifiers you publish. If it expires unused, the subscription returns to ordinary dunning rather than being stranded.

7. Cancellation and the paid-through date

8. Changing the price

POST /api/subscriptions/{subscription_id}/amount (see Manage a Subscription) stages a new price. It applies from the next period and there is no proration — the current cycle bills at the price it opened with. Until then the queued value is visible as pending_amount_usd on every read, and the response reports applies_from_period_seq. Sending the current price withdraws a queued change.

applies_from is null until something has actually been paid, because before the first successful charge there is no settled boundary to quote.

Two guardrails sit on the renewal itself, and both refuse rather than clamp — a refused renewal is recoverable, a wrong charge is not. A single renewal above $500 is not charged, and a queued price rise of more than 2× what the member was last disclosed is not promoted (the subscription keeps billing the old price until a human confirms). Sending consent.disclosed_amount_usd at signup is what makes the second guardrail tight, because it baselines against what the member was actually shown.

9. Revenue attribution (reporting, not remittance)

If a third party in your game earns a share of a membership — a guild founder, a creator — you can record that arrangement with revenue_share at signup. On every settled renewal Invo computes what that recipient earned, records it, ships it on subscription.renewed as revenue_share_attribution, and exposes it through three reporting endpoints — see Subscription Reporting.

10. The endpoints

Reads and writes are both scoped to the authenticated game — a subscription id from another tenant simply does not exist to you. Creating a subscription additionally requires a live game; a game in testing can read and cancel, but cannot open standing authority to charge a real consumer (403 GAME_NOT_LIVE).

11. Events to handle

12. What you build vs what we handle