Write the policy before implementing it
Define the permitted features for each plan and what happens during trial, initial payment requiring action, renewal failure, grace period and cancellation. A newly created subscription can be incomplete. Granting access solely because a subscription object exists can unlock a product before the required payment or authentication is complete.
- Map stable application user IDs to Stripe customers; email text alone is a fragile identity rule.
- Name the price IDs and plan permissions in test mode.
- State whether cancel-at-period-end retains access until the paid period ends.
Read current state, not just the event name
Stripe documents using invoice.paid together with the relevant subscription status when extending access. A failed renewal is not automatically identical to permanent cancellation: retry and final-status settings affect what happens next. Your product's grace policy must be explicit rather than inferred from the latest-arriving webhook.
- Handle customer.subscription.updated when rules or status change.
- Handle ended subscriptions and the owner-approved unpaid/canceled behaviour.
- Do not treat paused payment collection and a paused subscription as interchangeable.
Check both permitted and denied behaviour
Testing only the successful purchase leaves the dangerous cases unexamined. Use disposable accounts and synthetic data to test renewal, payment requiring action, failed renewal, scheduled cancellation and actual subscription end. Inspect protected server routes as well as visible screens; hiding a button does not enforce access.
- An unrelated account must never inherit another customer's plan.
- Replay a processed event and check that access and subscription rows are not duplicated.
- Deliver older events after newer ones and verify the agreed current state remains authoritative.
What to send for an access repair
Describe expected versus observed access and the redacted event type, mode and response. State the membership platform and whether the issue affects purchase, renewal or cancellation. Do not send member identities, card data or secret keys. Recovery of real customers and any financial action require separately agreed authority.
Sources and limits
- Stripe: subscription webhooks Checked 2026-10-10.
- customer.subscription.created can be incomplete.
- invoice.paid should be considered with current subscription status for access.
- past_due handling depends on subscription settings; canceled and unpaid require access handling.
- customer.subscription.deleted indicates the subscription ended.