Stripe invoice.payment_failed: what to do with access when a payment fails
November 10, 2026
A renewal charge fails. Stripe fires invoice.payment_failed, the subscription moves to past_due, and now your app has to answer a question Stripe will not answer for you: does this customer still get in?
Get it wrong in one direction and paying customers with an expired card are locked out on day one. Get it wrong in the other and people keep full access for weeks without paying. Most integrations quietly do the second one, because they only ever check whether a subscription exists.
What actually happens after a failed renewal
- invoice.payment_failed fires for every failed attempt, not just the first.
- The subscription status becomes
past_duewhile Stripe is still retrying. A customer who fixes their card during this window is simply back toactive. - When the retries run out, the outcome depends on a setting in your Billing dashboard: the subscription can be canceled, marked unpaid, or left
past_due. Check what yours is set to, because your access logic has to match it. - If the bank requires authentication, you may see
invoice.payment_action_requiredinstead of a plain decline. The customer has to act, so an email to them matters more than a retry. - On recovery you get
invoice.paidand acustomer.subscription.updatedback toactive.
How long retries last and how many there are depends on your retry settings (Stripe’s smart retries or a custom schedule), so look at your own dashboard rather than assuming a number.
The mistake: past_due is treated as either “fine” or “broken”
past_due is a business decision, not a technical state. Three policies are reasonable:
- Strict: no access the moment the status is not
activeortrialing. Simple, but you will lock out people with a temporary card problem. - Grace period: keep access for N days after the first failure, then close. This is what most SaaS products want.
- Lenient: keep access until Stripe finally cancels or marks unpaid. Fine if retries are short, expensive if they are long.
Whatever you pick, write it down in one function. Access scattered across route handlers is how two parts of the app end up disagreeing.
Webhook handling that supports a grace period
The grace period needs a timestamp for when trouble started, because the subscription object alone does not tell you how long it has been past due. Store it on the first failure and clear it on recovery:
// app/api/stripe/webhook/route.ts (excerpt, after signature check + idempotency guard)
switch (event.type) {
case 'invoice.payment_failed': {
const invoice = event.data.object as Stripe.Invoice
// Remember WHEN trouble started, only the first time.
await db.markPastDueSince(String(invoice.customer), event.created)
await notifyCustomerPaymentFailed(String(invoice.customer))
break
}
case 'invoice.paid': {
const invoice = event.data.object as Stripe.Invoice
await db.clearPastDue(String(invoice.customer)) // recovered, access continues
break
}
case 'customer.subscription.updated':
case 'customer.subscription.deleted': {
const sub = event.data.object as Stripe.Subscription
await db.saveSubscriptionStatus(sub.id, sub.status)
break
}
}The access check
// One place that answers "does this user get in?"
const GRACE_DAYS = 3
export function hasAccess(user: {
subscriptionStatus: string
pastDueSince: number | null // unix seconds of the first failed payment
}) {
switch (user.subscriptionStatus) {
case 'active':
case 'trialing':
return true
case 'past_due': {
if (!user.pastDueSince) return false
const graceEnds = (user.pastDueSince + GRACE_DAYS * 86400) * 1000
return Date.now() < graceEnds // grace period, then the door closes
}
default:
// unpaid, canceled, incomplete, incomplete_expired, paused
return false
}
}Note the default branch: unpaid, canceled, incomplete, incomplete_expired and paused all deny access. A whitelist of statuses that grant access is safer than a blacklist of statuses that do not.
past_due and unpaid right now, then look each customer up in your own database. Anyone in that list who still has full access with no grace logic behind it is revenue leaking today.Failed payments depend on webhooks that must not be missed
The whole pattern above relies on your handler actually receiving and processing invoice.payment_failed and invoice.paid. If a signature check rejects them, or the handler returns 200 without doing the work, the grace timer never starts and the customer is never flagged. See Stripe webhook signature verification failed and your Stripe webhook returns 200, but it didn’t work. The same status logic also explains ghost customers when subscription.deleted never fires, and the full list of states is mapped in the Stripe subscription lifecycle.
Check whether it is already happening to you
Run the reconciliation script once to see who is past due in Stripe but still inside your app. Or let Venwai compare the two every day with a read-only Stripe key and alert you in Slack, Discord, Telegram, or email when they stop agreeing.
Free while it’s in beta, no card required: venwai.com.
Venwai compares Stripe with who your app actually lets in, once a day, using a read-only key. It alerts you the moment they disagree. Free while in beta, no card required.
Check my Stripe for free