Stripe Subscription Past Due: How to Handle It (And Recover Revenue)

// Get all subscriptions currently in past_due status
const pastDueSubs = await stripe.subscriptions.list({
  status: 'past_due',
  limit: 100,
  expand: ['data.latest_invoice'],
});

for (const sub of pastDueSubs.data) {
  const invoice = sub.latest_invoice;
  const error = invoice?.last_payment_error;
  const amount = sub.items.data[0]?.price?.unit_amount / 100;

  console.log(`Subscription: ${sub.id}`);
  console.log(`  Customer: ${sub.customer}`);
  console.log(`  MRR: ${amount}`);
  console.log(`  Decline code: ${error?.decline_code || 'none'}`);
  console.log(`  Past due since: ${new Date(sub.current_period_start * 1000).toISOString()}`);
  console.log('---');
}

console.log(`\nTotal past_due: ${pastDueSubs.data.length} subscriptions`);

// Option A: Retry the invoice (for soft declines)
try {
  const invoice = await stripe.invoices.pay('in_xxx');
  console.log(`Invoice ${invoice.id}: ${invoice.status}`);
  // "paid" = success, subscription moves back to "active"
} catch (err) {
  console.log(`Retry failed: ${err.message}`);
}

// Option B: Send card update link (for hard declines)
const session = await stripe.billingPortal.sessions.create({
  customer: 'cus_xxx',
  return_url: 'https://yourapp.com/account',
});
console.log(`Card update link: ${session.url}`);
// Send this URL to the customer via email

// Option C: Send the invoice directly to the customer
const sentInvoice = await stripe.invoices.sendInvoice('in_xxx');
console.log(`Invoice sent: ${sentInvoice.hosted_invoice_url}`);
// Customer receives email with a hosted payment page

// Listen for payment failures to catch past_due subscriptions
app.post('/webhooks/stripe', async (req, res) => {
  const event = stripe.webhooks.constructEvent(req.body, sig, secret);

  if (event.type === 'invoice.payment_failed') {
    const invoice = event.data.object;
    const decline = invoice.last_payment_error?.decline_code;
    const customer = await stripe.customers.retrieve(invoice.customer);

    // Generate card update link
    const portal = await stripe.billingPortal.sessions.create({
      customer: invoice.customer,
      return_url: 'https://yourapp.com/account',
    });

    // Triage: soft vs hard decline
    const isSoftDecline = ['insufficient_funds', 'processing_error']
      .includes(decline);

    // Send immediate email based on decline type
    await sendEmail({
      to: customer.email,
      template: isSoftDecline ? 'soft_decline_notice' : 'card_update_needed',
      data: {
        name: customer.name,
        amount: invoice.amount_due / 100,
        cardUpdateUrl: portal.url,
      },
    });

    // Schedule follow-up dunning sequence
    await scheduleDunningEmails(invoice.customer, invoice.id, portal.url);
  }

  // Catch successful recovery
  if (event.type === 'invoice.paid') {
    const invoice = event.data.object;
    // Cancel any remaining dunning emails
    await cancelDunningSequence(invoice.customer, invoice.id);
    console.log(`Recovered: ${invoice.amount_paid / 100} from ${invoice.customer}`);
  }

  res.json({ received: true });
});

// SaveMRR handles all of this. plus email templates,
// retry optimization, and real-time recovery tracking.