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

customer.subscription.trialwillend: work the three-day window

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.

What to do on receipt

1. 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.
2. 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.
3. 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.
4. Return 200.

The trap

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."

Checklist

• 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.

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.