← Back to blogTry free

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

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:

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.

Quick check: list your subscriptions in 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.

Is your Stripe out of sync with your app?

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