Stripe event: payment_method.detached, the next invoice may have nothing to charge

TL;DR

If the default left: email the customer promptly to add a new one, and flag the account. The next invoice will fail with no payment method, which is the most avoidable kind of churn there is.

Steps

1. Read data.object.id and compare it against the customer's invoice_settings.default_payment_method and each active subscription's default_payment_method. If it matches any of them, the customer now has no working default.
2. If the default left: email the customer promptly to add a new one, and flag the account. The next invoice will fail with no payment method, which is the most avoidable kind of churn there is.
3. If it was not the default, just log it. A customer tidying their wallet is not an emergency.
4. Return 200.
5. Silence. Detach events look boring, so nobody handles them, and the failure surfaces weeks later as invoice.payment_failed with "no payment method," by which time the customer has no idea why. Catching it at detach time turns a failed renewal into a two-minute fix.
6. - Detach can come from the customer via the portal or from your own code. Either way, the default check is the same.

• Do not auto-attach a replacement or pick another method as the default unprompted. Choosing which card gets charged is the customer's decision.

When to use

You are seeing this: A payment method was detached from a customer. Use this skill when you run into "Stripe event: payment_method.detached, the next invoice may have nothing to charge".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Stripe's event reference says payment_method.detached occurs whenever a payment method is detached from a customer. Verified live at https://docs.stripe.com/api/events/types.