customer.subscription.deleted: email a customer when Stripe ends it

The short answer

When a subscription ends, Stripe sends an event called customer.subscription.deleted. It is the moment a paying customer stops being one, and the best thing to send is short: say it has ended, ask why in one line, and leave the door open.

When Stripe sends it

It depends on how the subscription was cancelled.

• At the end of the period. Most cancel buttons, Stripe's customer portal included, cancel at the end of the period the customer already paid for. Stripe sends customer.subscription.updated with cancel_at_period_end set to true when they press it, and customer.subscription.deleted when the period runs out.
• Straight away. A subscription cancelled at once sends customer.subscription.deleted right away.
• After failed payments. If payments keep failing and your Stripe settings cancel the subscription when retries run out, it ends the same way, with cancellation_details.reason set to payment_failed.

That last one matters. Somebody whose card expired never decided to leave, and "sorry to see you go" is the wrong email for them. Check the reason before you send anything.

Your own webhook

1. Add a webhook endpoint in Stripe that listens for customer.subscription.deleted.
2. Check the signature on every request. Stripe signs each one in a Stripe-Signature header and needs the raw body untouched.
3. Return a 2xx fast and send the email after. Keep the event ids you have handled, because an event can arrive twice.

const event = stripe.webhooks.constructEvent(rawBody, signature, endpointSecret);

if (event.type === "customer.subscription.deleted") {
  const subscription = event.data.object;
  const reason = subscription.cancellation_details?.reason; // "cancellation_requested", "payment_failed", ...
  const customer = await stripe.customers.retrieve(subscription.customer as string);
  // customer.email, customer.name
}

The subscription carries the customer's id rather than their email, so fetch the customer. If your portal asks why they're leaving, cancellation_details.feedback and cancellation_details.comment hold the answer, and your email shouldn't ask again.

With Kicklace

1. Go to Settings → Connections → Stripe → Connect, and paste one restricted key. Kicklace adds its own webhook to your Stripe account and keeps the secret Stripe hands back.
2. Stripe's customer.subscription.deleted now lands in Kicklace as a subscription cancelled, on the person with the email Stripe holds for the customer.
3. On your Lifecycle map, add a side road that starts from a cancellation, and write the email, or let Kicklace write it from your site.
4. Switch the sequence on. First Kicklace shows who would have got it over the last 30 days. Send yourself a test before you do.

Kicklace only reads Stripe and never changes a subscription. Payments from Stripe lists every event it hears. You can see the map on your own site in the demo, with no sign-up.

What the email should say

Keep it to a few lines, from you, with nothing to sell.

Subject: Your [your app] plan has ended

Hi {{first_name}},

Your [your app] plan has ended, and you won't be charged again. Your account and everything in it is still here if you come back.

Could you tell me why you left? One line is plenty, and you can reply to this email.

[Your name]

The reply is the useful part. A cancellation survey email template has more ways to ask, and win-back emails cover what to send weeks later.

FAQ

Is customer.subscription.deleted the same as a cancellation?

It's the end of the subscription. A customer who cancels at the end of the period has cancelled before this event arrives, and is still paying until it does.

Should I email when they press cancel, or when it ends?

When it ends is the safer default, because it's when the change is real. You can also send a short "got it" when they press cancel and keep the question about why for when it ends.

What if a failed payment ended it?

Send the failed payment email instead, with a way to update the card. That customer may want to stay.