Guides · Free check · $9 fix pack

Guides

Stripe renewal payment failed, but the customer still has access

A card expired, the renewal failed, and the customer still has the paid plan a month later. Or the opposite: one failed attempt and your app locked them out while Stripe was still retrying. Both come from the same gap: the webhook only handles the happy path.

What Stripe sends when a renewal fails

Stripe: "Events provide a reliable way for Stripe to notify you of payment failures on subscription invoices. Some payment failures are temporary-for example, a card issuer might decline the initial charge but allow an automatic retry. Other payment failures are final and require action" (Stripe docs: Using webhooks with subscriptions).

If your endpoint is only subscribed to checkout.session.completed and invoice.paid, none of this reaches your app, and the user keeps whatever access they had. Check the endpoint's event list in the Dashboard first.

past_due, unpaid, canceled: what each means for access

Where "still has access" comes from

What happens after the last retry is a Dashboard setting. "If an invoice is still unpaid after all payment retries, you can configure the subscription to move to canceled or unpaid, or to remain past_due" (source). The retry settings page offers the same three options: cancel the subscription, mark it as unpaid, or leave it past-due (Stripe docs: Smart Retries).

So if the setting is "leave the subscription past-due" and your app only removes access on canceled, a customer whose card died can keep the plan indefinitely. Pick one rule and write it down: for example, "access continues while past_due; revoke on unpaid or canceled", with the Dashboard set to cancel or mark unpaid at the end of retries.

How long retries run is also a setting. "For new Stripe accounts, Stripe enables Smart Retries by default and configures it for up to 8 retries within 2 weeks." Stripe doesn't retry payments if, among other cases, "No payment methods are available" or "The issuer returned a hard decline code" (source).

Useful fields on the failed invoice

Stripe can also email the customer for you: with "Send emails when card payments fail" turned on in the revenue recovery settings, "Stripe automatically sends an email to your customer after each failed payment" (Stripe docs: Customer emails).

The fix

  1. Subscribe the live endpoint to invoice.payment_failed, invoice.paid, customer.subscription.updated and customer.subscription.deleted.
  2. On any of them, verify the signature, then retrieve the subscription and store its current status. Don't infer the status from the event type, and don't depend on event order (events out of order).
  3. Decide access from the stored status with one function, used by every page and API route.
  4. On invoice.payment_failed, also store hosted_invoice_url so the app can show "Your payment failed: update your card".
  5. Set the Dashboard's end-of-retries behavior so it matches the rule in step 3.
// After verifying the signature on the raw body
const SUB_EVENTS = ['invoice.paid', 'invoice.payment_failed',
  'customer.subscription.updated', 'customer.subscription.deleted'];

if (SUB_EVENTS.includes(event.type)) {
  const obj = event.data.object;
  const subId = obj.object === 'subscription'
    ? obj.id
    : (obj.parent?.subscription_details?.subscription ?? obj.subscription);
  if (subId) {
    const sub = await stripe.subscriptions.retrieve(typeof subId === 'string' ? subId : subId.id);
    await db.users.update({
      where: { stripe_customer_id: sub.customer },
      data: {
        subscription_status: sub.status,
        ...(event.type === 'invoice.payment_failed' ? { pay_url: obj.hosted_invoice_url } : {}),
        ...(event.type === 'invoice.paid' ? { pay_url: null } : {}),
      },
    });
  }
}

// One rule, used everywhere
function hasPaidAccess(user) {
  return ['active', 'trialing', 'past_due'].includes(user.subscription_status); // past_due = grace period (your choice)
}

Rename the table and fields to match your app. If you don't want a grace period, drop past_due from the list. Either way, unpaid and canceled must not grant access.

Prompt for your AI builder

Handle failed Stripe subscription renewals. 1) Make sure the webhook handles invoice.payment_failed, invoice.paid, customer.subscription.updated and customer.subscription.deleted, after signature verification on the raw body. 2) For each, get the subscription ID (subscription events: object.id; invoices: parent.subscription_details.subscription, or subscription on older API versions), retrieve the Subscription from Stripe, and save its status on the user. 3) On invoice.payment_failed also save the invoice's hosted_invoice_url; clear it on invoice.paid. 4) Create one hasPaidAccess(user) function: true for active, trialing and past_due; false for unpaid, canceled, incomplete, incomplete_expired and paused. Use it in every protected page and API route instead of a boolean is_paid flag. 5) Show a banner with the saved payment link while the status is past_due. 6) Do not change the signature check.

Re-test in a sandbox

  1. Create a sandbox subscription with a test card that succeeds, then switch the customer's default payment method to one of Stripe's test cards that is declined, and advance the billing cycle with a test clock (or create the next invoice and attempt payment).
  2. Confirm the endpoint received invoice.payment_failed with a 2xx and that the user's stored status is now past_due with the payment link saved.
  3. Pay the hosted invoice with a working test card. invoice.paid should bring the status back to active and clear the banner.
  4. Already have customers with stale access? List subscriptions with status=all and resync each one (see subscription status not updating).
Check yours in 10 seconds (free).

Paste your webhook URL. WebhookProof sends 3 harmless test requests and tells you whether Stripe can reach it and whether it rejects unsigned events. If it finds a problem, the $9 fix pack gives you the exact copy-paste fix for your stack (refundable for 14 days).

Run the free check

FAQ

Which Stripe event fires when a subscription renewal fails?

invoice.payment_failed. Stripe also sends invoice.updated (paid is false, status stays open) and, as the subscription changes, customer.subscription.updated with a new status such as past_due.

Should I remove access when a subscription is past_due?

That is your choice. Stripe says to notify the customer and ask them to update their payment details when a subscription becomes past_due, and to revoke access when it changes to canceled or unpaid.

Why does a customer with a failed card still have access?

Usually the webhook only handles checkout.session.completed or invoice.paid, or the app only revokes on canceled while the Dashboard is set to leave subscriptions past_due after all retries. Handle invoice.payment_failed and customer.subscription.updated, store the status, and align the Dashboard setting with your access rule.

How many times does Stripe retry a failed subscription payment?

It depends on your settings. Stripe says new accounts have Smart Retries enabled by default with up to 8 retries within 2 weeks, and that it does not retry after a hard decline or when no payment method is available.

Sources

More guides

Stripe webhook not working? Check these 7 things in order · A customer paid but didn't get access. What went wrong? · No signatures found matching the expected signature for payload · Stripe webhook failing with a 307 or 308 redirect

Last reviewed 2026-11-09. WebhookProof is an independent tool, not affiliated with Stripe, Inc.. Quotes are from the linked documentation.