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

What it means

A customer has been signed up for a plan. The subscription's status tells you what kind of start it is: trialing is a trial, active is a paid subscription, and incomplete means the first payment still needs something, such as the customer confirming it with their bank, or that you created the subscription with payment_behavior set to default_incomplete.

The event says a subscription exists. It does not say the first payment worked. For that, wait for invoice.paid.

When Stripe sends it

Once for each subscription, at the moment it is created, whether you create it from your code, in the Dashboard, or through Checkout in subscription mode. What happens to it later arrives as other events: customer.subscription.trial_will_end before a trial ends, customer.subscription.updated for every change, and customer.subscription.deleted when it ends.

Stripe does not promise to send events in the order they happened, so invoice.paid for the first payment can arrive before this one. Keep the ids of the events you have handled, because the same event can be delivered twice.

Does Stripe email the customer?

Not for the start itself. Stripe's list of customer emails has none for a subscription being created. What can follow is the email or receipt for the first invoice, if you turn those on, and a reminder 7 days before a free trial ends, if you turn that on.

The email to send

The welcome, as soon as the event arrives. Say what they now have, a trial with its end date or a plan, and the one first step. For a trial, take the date from trial_end. If status is incomplete, hold the welcome until invoice.paid shows that the first payment worked.

Subject: Your [your app] trial has started

Hi {{first_name}},

Your trial of [your app] runs until [the date from trial_end], and everything is switched on. The best first step is [one step, with a link].

[Say what happens when the trial ends.] If you get stuck before then, reply to this email.

[Your name]

The SaaS onboarding email sequence covers the emails that follow it.

Fields worth reading

• status: trialing, active or incomplete, as above.
• trial_start and trial_end: unix seconds, or null when there is no trial.
• 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. Its nickname, unit_amount and recurring.interval say what it is called, what it costs and how often.
• items.data[].quantity: how many seats or units.
• items.data[].current_period_end: when the current period ends. On API versions before 2025-03-31.basil this was current_period_end on the subscription itself.
• default_payment_method: empty on a trial that started without a card.
• latest_invoice and collection_method: the first invoice, and whether Stripe charges automatically or emails an invoice.

if (event.type === "customer.subscription.created") {
  const subscription = event.data.object;
  const trial = subscription.status === "trialing";
  const endsAt = subscription.trial_end; // unix seconds, or null
  const customerId = subscription.customer; // an id; fetch the customer for the email
}

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

What Kicklace does

With Stripe connected, the event lands on the person as a trial started, trial_started, when the subscription's status is trialing, and as a subscription started, subscription_started, otherwise. Kicklace also keeps the subscription itself on the account: its plan, price, how often it bills, how many seats, the period and the trial's end.

A trial moves nobody on your Lifecycle map. The account reads Trial beside whatever stage its people are on. A paid first invoice arrives as a purchase, which is what moves them to Paying.

A side road can start from trial_started or subscription_started once one has arrived. 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 it writes the welcome and the nudges after it in your site's voice, ready to copy, with no sign-up.

Sources

• Types of events
• Stripe CLI: trigger
• Using webhooks with subscriptions
• The Subscription object
• Send customer emails
• Subscription item billing periods