Launch checklist and traps

The phases, in order

The same eleven phases as the map on the overview, same numbers and names, in the order to do them, each naming the page that covers it. Do the whole list in sandbox first, then repeat phases 1, 2 and 4 against production keys and finish with phase 11. Every phase is self-serve in both environments. Two steps are one way and are called out: the webhook signing secret is shown once, and events fired before a target is registered are not delivered to it later.

Before launch

Card traps

1. Replay before retry. On any timeout or 5xx from /subscribe, send the same body again. A new client_request_id in a retry loop lands on 409 ACTIVE_SUBSCRIPTION_EXISTS at best and a second subscription at worst.
2. requires_action is not paid. Nothing has been charged. Do not grant paid access until subscription.renewed.
3. pending is not failed. Wait for the event; Invo resolves it.
4. current_period_end is not entitlement. Use paid_through.
5. payment_failed and past_due do not revoke access. Only expired (at final_period_end) and canceled (at access_until) do.
6. authentication_required is not a failure. Do not send the member a “payment failed” message; send them the link.
7. Do not poll for renewals. Subscribe to subscription.renewed.
8. One live subscription per item, on either rail. Cancel the old one before creating a new one for the same item_id, or change the price with /amount.
9. At-period-end cancel on an unpaid subscription is immediate. Read terminated_immediately on the response.
10. Price changes apply next period, and big jumps do not apply at all. More than double, or above the 25000.00 per-charge ceiling, stays pending forever.
11. A card saved without off-session consent cannot back a subscription. Cards saved through saved_card_id purchases, or before the consent change, need to be saved again through the hosted card page, /setup-intent, or a save_card: true purchase of a new card. The platform-commerce checkout page never saves one.
12. The card page creates a new member only when you send player_name. Without it the hosted card page answers 404 PLAYER_NOT_FOUND for a member your title has never seen; /setup-intent never creates one. For a new signup, mint the card page with player_name, then /subscribe. That is also the order a paid trial needs, since it needs the card before /subscribe.
13. Coins never pay a card subscription. Since 2026-09-17 the card is charged the full price every period. Save a card before /subscribe; a member with coins but no card fails with no_payment_method.
14. wallet_only is deprecated, and absolute. A card attached later is ignored until you pass wallet_only: false on /payment-method, and a wallet_only card subscription can never be paid. Do not send it.
15. A renewal’s purchase.completed is not a purchase. Every paid card renewal also sends one (data.metadata.source == "subscription_renewal"). Grant nothing from it; grant on subscription.renewed.
16. A 202 from /refund is not a refund. status: "pending_approval" means nothing moved; wait for subscription.refund_approved or subscription.refund_rejected.
17. A full refund ends the subscription. Refund a partial amount if the member keeps the membership.
18. A lost chargeback does not end the subscription. It costs you what a refund of that period does: your share is reversed and Invo’s card fee is charged to you (purchase.disputed, partner_debited_usd), unless the chargeback guarantee covers it (guarantee_covered: true), and the next renewal still charges. Cancel it yourself if you do not want to keep billing that member.
19. A paid trial needs the card first. Without a saved card /subscribe refuses it with 400 PAYMENT_METHOD_REQUIRED; a free trial would have been created card-less.
20. A refused trial charge ends the subscription at once. first_charge.status: "failed", subscription.status: "expired", no retries. Replaying the key will not revive it; subscribe again with a new client_request_id. A temporary error, by contrast, goes to past_due and is retried.
21. skipped_trial means a free trial. A paid trial reports paid (or another first-charge outcome) at the trial price, and its period 1 sends subscription.renewed with is_trial: true.
22. A late trial charge means two charges back to back. If a paid trial is still awaiting_authentication or past_due at trial_end and then succeeds, the full price follows immediately. Cancel it at trial_end if that is not what you want.
23. sub_ is reserved as a prefix for every idempotency key on the platform, not only here.
24. Metadata is yours except _invo. Invo writes cancellation reasons under that key.
25. Send consent. It is what a disputed charge is argued from, trial terms included.
26. Do not store or log confirmation_url beside anything you publish. It is a bearer link.
27. subscription.period_seq is the next period, not the paid one. After a paid first charge it already reads 2. Key entitlement on paid_period_seq and on the period_seq of subscription.renewed.

Steam traps

1. Finalize is your call. Steam does not tell Invo the member authorised; your game must call /steam/finalize after the overlay or checkout closes, and again if it returned not_authorized.
2. Match the client callback on steam_order_id, never on steam_transid. Store it against the subscription_id before you return from init.
3. 24 hours to authorise. An unfinalised subscription expires and must be re-created with a new key.
4. web sessions need player_ip and the checkout URL must open top-level; it cannot be framed.
5. Only the primary key or the steam channel key may start a Steam subscription.
6. No trials, no interval_count other than 1, no wallet_only, no card fields.
7. The price is a ceiling. Increases are refused; start a new Steam subscription. Decreases stage.
8. /payment-method is refused on a Steam subscription.
9. Coins per period depend on the member’s country and are fixed at init. Show amount_coins from the init response, not price times 10.
10. An empty wallet pays the full price; a partial wallet pays only for the missing coins. Both are correct and both appear as funding.steam_charged_usd.
11. A member can cancel from Steam. You learn it from subscription.canceled with canceled_by: "steam"; access runs to access_until.
12. Some Steam renewals are deferred for reasons on your side (billing setup, credit, Steam configuration) with no event. Keep your Invo billing setup healthy and watch next_charge_at.
13. Replaying /steam/init returns the row’s current status, which may already be active, canceled or expired.
14. A second init while one is pending reuses it. Same terms, same Steam account and same usersession: you get the pending row back with pending_reuse: true and the same steam_order_id, and no second agreement is opened. Anything else: 409 STEAM_AUTHORIZATION_PENDING carrying the pending subscription_id.
15. Reuse is deliberately narrow, and narrower is not the same as safer. It would be easy to read the rule as “reuse whenever the price matches, because a duplicate agreement is the danger”. It is not. An authorisation belongs to one Steam account and one session type: hand a member an agreement her current Steam account cannot see, or a web checkout link when she is in the overlay, and she is stuck for a full day with no way to act. A rival agreement she can answer is the lesser harm, so the rule fails toward “she can act” rather than toward “nothing is duplicated”. When you get the 409, show her the pending one and let her finalize or cancel it.
16. Same item_id as the card version of the membership. 409 ACTIVE_SUBSCRIPTION_EXISTS across rails is the guard against double-billing, not a bug.
17. Refunds of Steam-charged periods are not supported yet. /refund answers 409 STEAM_REFUND_NOT_SUPPORTED; wallet-covered periods refund in coins.
18. Sandbox does not exercise the storefront. sandbox_auto_approved: true means the charge was simulated; do one real Steam sandbox authorisation before launch.
19. split.total_usd on Steam is not the price. It is what the coins are worth after the storefront’s share and VAT; the price is the top-level amount_usd.
20. One expiry arrives with no payment_failed before it: steam_authorization_abandoned. Handle subscription.expired on its own. (steam_containment is a second such code; it is not sent at present, and currency bought through a platform store is subject to that store's rules, so keep any handling you have for it.)