Stripe event: customer.subscription.trial_will_end, three days to convert or lose them

TL;DR

Say what happens next (first charge amount and date, from the upcoming invoice), and link to update the payment method. Check the customer has a usable payment method attached.

Steps

1. Stripe fires this three days before the trial ends, or immediately if the trial was shortened to under three days. It is a heads-up, not a payment.
2. Before you email anyone, check the subscription's current status and its latest invoice. Stripe's own docs warn about this: the payment may already be collected, and a "your trial is ending" email to someone who already paid is embarrassing.
3. If unpaid and the trial is genuinely ending: send the reminder. Say what happens next (first charge amount and date, from the upcoming invoice), and link to update the payment method.
4. Check the customer has a usable payment method attached. A trial that converts with no payment method on file just becomes past_due on day one.
5. Return 200.
6. Blasting reminders without checking state. Trials get converted early, extended, or canceled, and this event does not know. Every reminder must be conditional on a fresh read of the subscription. The other trap: treating this as a dunning event. Nobody owes you money yet; the tone is "heads up," not "pay now."
7. - The three-day lead is documented; if you need more warning, schedule your own earlier reminder from trial_end on the subscription object.

• Pair this with invoice.payment_failed handling. The trial ends, the first invoice fails, the subscription goes past_due: that whole chain starts here if you do nothing.

When to use

You are seeing this: Stripe fires this three days before the trial ends, or immediately if the trial was shortened to under three days. Use this skill when you run into "Stripe event: customer.subscription.trialwillend, three days to convert or lose them".

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.trialwillend occurs three days before a subscription's trial period is scheduled to end, or immediately when a trial is ended early, and advises checking the subscription status and latest invoice before sending payment-reminder communications. Verified live at https://docs.stripe.com/api/events/types.