Stripe event: customer.subscription.deleted, deprovision now, this is terminal

TL;DR

Decide data retention per your policy: keep the data for a grace window or delete it. Keep the record; you will want it for win-back campaigns and for answering "why was I charged" questions.

Steps

1. When this event arrives, the subscription has ended. Period.
2. Look up your user by the subscription id. Revoke the plan's entitlements: downgrade to free, suspend the account, whatever your offboarding is.
3. Decide data retention per your policy: keep the data for a grace window or delete it. Tell the customer which one you did.
4. Mark the subscription canceled in your records with the timestamp. Keep the record; you will want it for win-back campaigns and for answering "why was I charged" questions.
5. Return 200.
6. Deprovisioning on the cancellation request instead of on this event. When a customer cancels with cancel_at_period_end, you get customer.subscription.updated first and deleted only when the paid period actually ends. Cutting access at the request is both wrong (they paid) and a good way to manufacture disputes. The other trap: confusing a paused subscription with a deleted one. Pause is a different state; check pause_collection before you assume.
7. - Subscriptions deleted immediately (no period end) arrive here too. Same handling: the event means it is over now.

• If the customer resubscribes later, that is a new customer.subscription.created with a new id. Do not resurrect the old record; link them by customer.

When to use

You are seeing this: When this event arrives, the subscription has ended. Use this skill when you run into "Stripe event: customer.subscription.deleted, deprovision now, this is terminal".

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 customer.subscription.deleted occurs whenever a customer's subscription ends. Verified live at https://docs.stripe.com/api/events/types.