Renewals, funding and dunning

1. When Invo charges

• Billing is in advance: a period is charged at its start. The first period is charged inside /subscribe (or at /steam/finalize); each later period is charged at next_charge_at, which is the end of the period just paid.
• At creation Invo adds up to one hour of random offset to the first period’s end, so a cohort of members who subscribed in the same minute renews spread across an hour a month later. The offset carries forward for the life of the subscription.
• The renewal engine runs every minute in both environments. A subscription is picked up within a minute or two of next_charge_at, not at the exact second.
• Invo charges at most one period per subscription per run. If Invo ever falls behind by whole periods (an outage on Invo’s side), the elapsed periods are forgiven, never back-billed; you see the gap as a jump in period_seq on the next subscription.renewed.

2. Funding order, card rail, worked examples

Price 9.99 USD per month, so a period is worth 99.90 coins. Shortfall is converted to USD rounded up to the cent, and never below the 1.00 USD minimum top-up.

The funding block on subscription.renewed reports balance_applied_coins (the pre-existing wallet portion), card_charged_usd, minted_coins and new_balance for every renewal.

3. Funding order, Steam rail, worked examples

Price 9.99 USD per month, US member, so a period is worth 69 coins. Period 1 always charges the full price (that is what creates the agreement). From period 2 the wallet goes first, and Steam is charged the smallest amount that buys the missing coins, never above the price and never below the 1.00 USD minimum top-up.

For a German member the same price is worth 58 coins and the partial top-up above would be 6.46 USD. The country is fixed at init, so every period of a subscription is worth the same coins. On Steam the split is computed on what the coins are worth (basis: "steam_net"), not on the price; the top-level amount_usd on the event is always the price.

4. When a charge fails

Failure schedule, per game, default retry after 2 days, then 3 days, then 2 days, then expire: three retries over seven days.

grace_period_end is computed from the live schedule at the moment of each failure, so it is always the date Invo will actually honour. Access is retained through the whole grace window; only subscription.expired revokes it. A member who fixes their card during the window (through /payment-method, or on Steam by topping up their wallet) is charged at the next retry; you can also force an immediate retry in sandbox (advance-clock with intervals: 0).

Failure codes

failure_message is a short human-readable string beside every code.

5. Card authentication (awaiting_authentication)

Some card issuers require the cardholder to authenticate a recurring charge. When that happens:

1. Nothing is charged. No retry is consumed. Access is retained.
2. The subscription moves to awaiting_authentication and next_charge_at is pushed to the challenge deadline.
3. Invo mints a single-use confirmation link and sends subscription.authentication_required carrying confirmation_url and expires_at. On the first charge the same link is also on the /subscribe 201 (first_charge.confirmation_url).
4. You relay the link to the member (email, in-game message). The link opens an Invo-hosted page at /subscription-auth?token=... on Invo’s checkout host; the member authenticates with their issuer there. Do not frame it, and do not log the URL beside identifiers you publish; it is a bearer link.
5. On success the renewal resumes: subscription.renewed fires, the subscription is active. The page tells a member who refreshes that the payment is confirmed.
6. The link lives at most 72 hours, and never past the next scheduled charge. If it lapses, the page says so, Invo tries the card again on its own, and ordinary dunning resumes. A card that asks for authentication on more than two consecutive attempts for the same period is treated as declined.

The card_amount_usd on the event is what the card is being asked for (the wallet shortfall), which differs from amount_due_usd (the period price) whenever the member holds a balance.

6. Deferrals you will not be told about

A few renewal outcomes are deferrals rather than failures. No event is sent, no retry budget is consumed, and the member’s access is unaffected. You can see them on GET as an unchanged (or past_due) status with next_charge_at about 24 hours out:

• The price is above the platform’s per-charge ceiling of 500.00 USD. Such a subscription is never charged; keep prices at or below 500.00.
• The member’s wallet holds value that cannot be spent in this game, and the shortfall cannot be topped up around it. The subscription reads past_due. After seven consecutive daily deferrals it expires: you receive subscription.expired with failure_code: "steam_containment" and final_period_end set (no subscription.payment_failed precedes it, because no charge was attempted). Revoke at final_period_end as for any expiry.
• On Steam, Invo cannot issue currency for your title right now (billing setup incomplete, rail suspended, credit unavailable), or the title’s Steam configuration is unusable. The deferral repeats daily until it is fixed on your side.