Failed payment handling and grace period disclosed

When a subscription payment fails silently — no email, no in-app alert, no documented grace period — the consumer's access may be revoked without warning while they believe the subscription is active. FTC Negative Option Rule (2025) requires that consumers be informed of failed charges and given an opportunity to resolve payment before losing access. The absence of a invoice.payment_failed webhook handler also means Stripe's Smart Retry window passes without the user knowing they need to update their payment method, converting a recoverable payment failure into a churned subscriber and a potential service disruption dispute.

Handle the invoice.payment_failed webhook and send an immediate notification with grace period disclosure. In app/api/webhooks/stripe/route.ts:

if (event.type === 'invoice.payment_failed') {
  const invoice = event.data.object
  const customer = await stripe.customers.retrieve(invoice.customer as string)
  const email = 'email' in customer ? customer.email : null
  if (email) {
    await sendEmail({
      to: email,
      subject: 'Action required: Payment failed for your subscription',
      template: 'payment-failed',
      data: {
        amount: (invoice.amount_due / 100).toFixed(2),
        updatePaymentUrl: `${process.env.NEXT_PUBLIC_APP_URL}/settings/billing`,
        graceEndDate: formatDate((invoice.period_end ?? 0) + 60 * 60 * 24 * 21),
      },
    })
  }
}

Document the grace period in src/app/terms/page.tsx or the billing FAQ: 'If payment fails, Stripe will retry for up to 21 days. You retain full access during this period. After that, your subscription is cancelled and you move to the free tier.'