customer.subscription.deleted: what it means and what to email

What it means

A subscription has ended. It is the moment a paying customer stops being one, and Stripe's advice is to take their access away when you see it. The subscription's status is now canceled, which is final: a canceled subscription cannot be reactivated, so a customer who comes back starts a new one.

When Stripe sends it

Once for each subscription, when it ends, and that can happen three ways.

• At once. A subscription canceled immediately, from the Dashboard or the API, sends it right away. Immediate is what Stripe does by default.
• At the end of the period. When cancel_at_period_end is set to true, the customer keeps what they paid for. Stripe sends customer.subscription.updated when it is set, and this event when the period runs out, which can be weeks later.
• After failed payments. When the retries run out and your settings say to cancel, the subscription ends the same way, and Stripe sets cancellation_details.reason to payment_failed.

That last one matters, because somebody whose card kept failing never decided to leave. Read the reason before you send anything.

Delivery follows the usual rules. The same event can arrive twice, and Stripe promises no order.

Does Stripe email the customer?

Yes, if you turn it on. Stripe's list of customer emails includes one on cancellation of a subscription, set under Email notifications and customer management in the billing settings. Its manage-subscription link can go to the Stripe-hosted customer portal or to a page of your own.

Stripe's email uses your branding settings. If you want the customer asked why they left, in your own words, that is the email below.

The email to send

Short, from you, with nothing to sell. Say it has ended, say what happens to their data, and ask why in one line. Send it when this event arrives, not when they press cancel, because that is when it is true.

If cancellation_details.reason is payment_failed, send a different email, one that says the card kept failing and how to start again.

Subject: Your [your app] plan has ended

Hi {{first_name}},

Your [your app] plan has ended, so you will not be charged again. [Say what happens to their account and their data, and for how long.]

If you have a minute, I would like to know what you were hoping it would do. One line is plenty, and you can reply to this email.

[Your name]

More wording is in customer.subscription.deleted: email a customer when Stripe ends it and the cancellation survey email template, and win-back emails cover what to send weeks later.

Fields worth reading

• cancellation_details.reason: cancellation_requested for a cancel made through the API or Dashboard, payment_failed or payment_disputed for an automatic one, or canceled_by_retention_policy for a test mode subscription Stripe expires.
• cancellation_details.feedback and cancellation_details.comment: what the customer picked and wrote, when they canceled themselves through a portal that asks. Your email should not ask again.
• ended_at: when it ended.
• canceled_at: when the cancellation was asked for. With cancel_at_period_end, this is the time of the request and not the end of the period.
• customer: the Stripe customer id. A subscription carries the id and not the email, so fetch the customer for the address.
• items.data[].price: the plan they were on.

if (event.type === "customer.subscription.deleted") {
  const subscription = event.data.object;
  const reason = subscription.cancellation_details?.reason;
  const endedAt = subscription.ended_at; // unix seconds
  const customerId = subscription.customer; // an id; fetch the customer for the email
}

To see a real payload, run stripe trigger customer.subscription.deleted in a sandbox and read the event it sends.

What Kicklace does

With Stripe connected, the event lands on the person as a subscription cancelled, subscription_cancelled, and the subscription on the account is brought up to date with its end. It moves nobody on your Lifecycle map, because the road is what somebody reached and cancelling does not undo having paid. The account reads Churned from its own money.

Kicklace reads cancellation_details too. The reason Stripe gives is kept on the event, with what the customer picked in a portal that asks. A subscription that Stripe ended because payments kept failing (payment_failed) lands as a failed payment, payment_failed, instead, since that person is already on the Card failed road and did not choose to go.

A side road with Cancelled as its way in starts from a cancellation, and the first-run setup offers one. It does not start for a subscription Stripe ended after failed payments. A subscription Stripe ended for another reason, a dispute say, still lands as a cancellation with the reason kept, so write that email so it suits them too.

Kicklace only reads Stripe and never changes a subscription. Nothing sends until you switch a sequence on, and Kicklace shows who would have got it over the last 30 days first.

Write yours from your URL. Paste your site's address into the welcome email generator and it writes the cancellation email in your site's voice, ready to copy, with no sign-up.

Sources

• Types of events
• Stripe CLI: trigger
• Cancel subscriptions
• The Subscription object
• Send customer emails
• Automate payment retries