# invoice.payment_failed: run your dunning playbook

An invoice payment attempt failed: declined card, soft decline, or no payment method on file. The subscription is now `past_due`, not canceled. There is still time.

## What to do on receipt

1. Read `attempt_count` and `next_payment_attempt` on the invoice. If Stripe will retry soon on its own, your first email can be gentle: "we'll try again, or update your card now."
2. Email the customer with a link to update their payment method. Make it one click. Every extra step here costs you the subscription.
3. Track dunning state yourself: how many failures for this invoice, when the last reminder went out. Escalate the tone as attempts climb.
4. If the customer updates the method, you can retry the invoice immediately via the API instead of waiting for the next automatic attempt.
5. Return 200.

## The trap

Treating this as terminal and deprovisioning. `past_due` still has access in most setups; killing the account on the first failed renewal manufactures the churn you were trying to avoid. The other trap: ignoring `next_payment_attempt` and emailing "final notice" language before Stripe has even retried once.

## Checklist

- Smart Retries and your retry settings in the Dashboard decide the automatic schedule. Your handler should read `next_payment_attempt` rather than assuming a cadence.
- After the final failed attempt, the subscription moves to `canceled` or `unpaid` per your settings, and you get `customer.subscription.deleted`. That is when deprovisioning happens, not here.