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

What it means

A subscription's trial is close to its end. The event exists so you can warn the customer before the first charge or before the subscription lapses. Stripe's own advice is to check that the customer has a payment method you can bill, and optionally to tell them they will be charged.

When Stripe sends it

Three days before the trial's scheduled end, by default. For trial offers, Stripe's docs describe the lead time as a Trial ending events setting in the Dashboard that starts at 3 days. Once for each trial.

It also fires at once when a trial is ended early, for example with trial_end set to now or when a plan change in the Customer Portal ends it, and when a trial is shorter than the lead time. That can happen in the same moment the payment is collected, so check the subscription's status and its latest invoice before you send anything that reads as a payment reminder.

The usual delivery rules apply: the same event can arrive twice, and Stripe promises no order.

Does Stripe email the customer?

Yes, if you turn it on. Under Email notifications and customer management in Stripe's billing settings, Send a reminder email 7 days before a free trial ends makes Stripe send one, with a link to add or update a payment method and the cancellation link. When a trial is shorter than 7 days Stripe sends it as soon as the trial begins.

So with Stripe's reminder on and the default lead time, yours comes four days after it and is the second one. That suits a short, plain note. If you send your own in place of Stripe's, Stripe's compliance page says meeting the card networks' requirements for trials is still yours to do.

The email to send

At the moment the event arrives. Say when the trial ends, what happens then and what it costs, and give two ways forward: add a card, or tell you it was not the right fit. Whether a card is on file decides the first line. The subscription's default_payment_method shows it, and so does the customer's own default.

Subject: Your [your app] trial ends on [date]

Hi {{first_name}},

Your trial of [your app] ends on [date]. [If a card is on file: on that day it will be charged [amount] for [plan], and there is nothing you need to do. If not: to keep going you will need to add a card here: [link].]

If it was not the right fit, I would like to hear why. One line is plenty, and you can reply to this email.

[Your name]

More wording and the code to send it yourself are in customer.subscription.trial_will_end: email before a Stripe trial ends and the trial ending email template.

Fields worth reading

• trial_end and trial_start: unix seconds. Turn trial_end into the date you print.
• status: still trialing when the event is sent for a trial that is running out.
• default_payment_method: the subscription's own card. Empty does not mean no card, because the customer's default is used next, so look there before you say none is on file.
• trial_settings.end_behavior.missing_payment_method: what happens at the end without a card, one of create_invoice, cancel or pause.
• items.data[].price: the plan's nickname, unit_amount and recurring.interval, for what they will pay and how often.
• customer: the Stripe customer id. A subscription carries the id and not the email, so fetch the customer for the address.
• latest_invoice and cancel_at_period_end: whether payment has already been collected, and whether they have already cancelled.

if (event.type === "customer.subscription.trial_will_end") {
  const subscription = event.data.object;
  const endsAt = subscription.trial_end; // unix seconds
  const ownCard = subscription.default_payment_method; // an id, or null
}

The Stripe CLI's stripe trigger does not list this event. To see one, start a subscription in a sandbox with a trial shorter than the lead time, since Stripe then sends the event at once. Kicklace ignores that one, as the section on what it does says.

What Kicklace does

With Stripe connected, the event lands on the person as a trial ending, trial_ending, and the subscription on the account is brought up to date. A trial moves nobody on your Lifecycle map.

Kicklace leaves out one that Stripe sends at once. A trial with under twelve hours left, one already ended, and one that began within the hour are no reminder anybody can act on, so those are answered and ignored and no side road starts. Twelve hours is low on purpose: the lead time is a setting, and an account that asks for one day should still get its reminder. The time is read from the event, not from when it arrives, so a delivery Stripe retried is judged as it was made.

A side road with Trial ending as its way in starts from it. The first-run setup offers one that rejoins the road at Paying, and it stays off until you switch it on. It is an account email, so Stop these emails on a tip does not hold it back. Nothing sends until you switch it 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, where your site offers a trial, it writes the trial ending email in your site's voice, ready to copy, with no sign-up.

Sources

• Types of events
• Stripe CLI: trigger
• Configure trial offers on subscriptions
• Use free trial periods on subscriptions
• Manage compliance requirements for trials and promotions
• Automate customer emails
• Using webhooks with subscriptions