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.
• Trials. The trial window is period 1. A free trial charges nothing for it; a paid trial charges trial_amount_usd for it inside /subscribe. Either way amount_usd is charged as period 2 at trial_end, and from then on the subscription renews like any other. The step from a paid trial’s price to the regular price is not a price change and is never held back by the price-increase limits. If a paid trial’s own charge only succeeds after trial_end (a late authentication or a late retry), period 2 is charged straight after it: two charges back to back. See the card road, trials.

2. Funding, card rail, worked examples

Price 9.99 USD per month, so a period is worth 99.90 coins.

The funding block on subscription.renewed still carries every field it always did. On the card rail balance_applied_coins is always "0.00", card_charged_usd is the full price, minted_coins equals amount_coins, and new_balance is the member’s unchanged balance. A price below the card processor’s own minimum charge is declined by the processor and goes through dunning; Invo does not round a card charge up to a minimum. Save a card before /subscribe: a member with coins but no saved card is not charged from the coins.

3. Funding order, Steam rail, worked examples

The Steam rail is unchanged by the card-only change. 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 title, 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, by saving a new card on the hosted card page, 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). Invo re-resolves the card at every attempt: a subscription whose card is absent, detached or expired adopts the member’s newest saved card and records it, so the next read names the card that was charged. There is no retry-now call in production; the retry runs at next_charge_at.

Failure codes

failure_message is a short human-readable string beside every code. insufficient_funds is never a failure_code: it is the attempt outcome on subscription.payment_failed (one of card_declined, insufficient_funds, error), and on an attempt with no usable card the failure_code beside it names why no card could be charged. A handler branching on failure_code == "insufficient_funds" matches nothing.

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-app 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. Since 2026-09-17 that is the full period price, the same figure as amount_due_usd, on every card challenge (a challenge opened before that date can still show the older wallet-shortfall figure). Both fields stay.

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 25000.00 USD. Such a subscription is never charged. The ceiling is per charge, so an annual plan is measured on the whole annual amount rather than the monthly equivalent: $500 per month billed annually is one $6,000 charge and passes.
• Withdrawn. A renewal was once deferred when the wallet held currency bought through Steam and the game was not a Steam title, expiring after seven consecutive daily deferrals with failure_code: "steam_containment". There is no such deferral. A balance can be spent in any title regardless of where the currency was bought, so a renewal spends the whole wallet and the code is never sent. Nothing to handle.
• 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.