Payments Preflight · Check 8 of 15
Handle failed payments and dunning
Listen for invoice.payment_failed, turn on Smart Retries and failed payment emails, and decide what access a past_due subscription keeps.
What it is
Renewals fail, for example when a card expires or is declined. Stripe can retry the charge and email the customer. Your app has to decide what happens to access meanwhile.
Why it matters
If you ignore failures, customers keep paid access for free, or lose access with no warning when the subscription changes status.
How to check
- Search your handler for
invoice.payment_failed. - In Billing settings, check your retry schedule and what happens after the last retry (the subscription can become
canceled,unpaidor staypast_due). - Check whether customer emails for failed payments are turned on.
How to fix it
- Handle
invoice.payment_failed: notify the user in-app and link to a page where they can update their card. - Decide and code access rules per status, for example keep access while
past_due, remove it atunpaidorcanceled. - Use Smart Retries or a custom retry schedule, and enable the failed payment emails in the Dashboard.
Prompt for your AI coding tool
Paste into Cursor, Claude Code, Lovable or similar. Review the diff before you accept it.
Add failed payment handling for my Stripe subscriptions. Handle invoice.payment_failed by flagging the account and showing an in-app banner with a link to update the payment method. Gate access on subscription status: keep access for active, trialing and past_due, remove it for unpaid, canceled and incomplete_expired. Show me where status is read and the diff.
Sources
- Smart Retries Stripe docs
- How subscriptions work: statuses Stripe docs
- Using webhooks with subscriptions Stripe docs
Sponsor this page: get in touch.