customer.created: what it means and whether to email

What it means

A new Customer object exists in Stripe. It is Stripe's record of who somebody is, with a name, an email address and a place to keep their cards. It says nothing about whether they paid, started a trial or even finished signing up.

That is why it is a poor moment to send anything. The event knows a customer was made and not what the person did.

When Stripe sends it

Once for each customer, whenever one is created: by your code, in the Dashboard, or by Checkout. Checkout makes a customer for every Session in subscription mode, and in payment mode when you set customer_creation to always or turn on invoices after payment. With always, Stripe says it creates the customer when the Session is confirmed, so a customer can exist for a payment that then fails.

Checkout makes a new customer for a Session unless you passed an existing one when you created it, so somebody who buys twice can become two customers if you do not.

Does Stripe email the customer?

No. The customer emails Stripe describes are about payments and subscriptions, such as receipts, failed payments, refunds, trial endings, renewal reminders, expiring cards and cancellations. A customer being created is not one of them.

The email to send

None, on this event. Somebody who only has a Stripe customer may never have signed up or paid for anything, so an email to them can land as unwanted. The welcome belongs to your own sign-up, and the thank-you to their first payment, which checkout.session.completed and invoice.paid announce.

The email worth sending near it is the welcome, the moment they sign up in your product.

Subject: Welcome to [your app]

Hi {{first_name}},

Thanks for signing up for [your app]. The best place to start is [the first thing worth doing, with a link].

If anything gets in the way, reply to this email and it comes to me.

[Your name]

The SaaS welcome email template goes through what else a first email can say.

Fields worth reading

• id: the customer id, cus_ and a string. It is the key that joins Stripe to your own users.
• email and name: either can be empty, so do not assume a customer has an address.
• metadata: where you put your own user id, if you made the customer from your code.
• preferred_locales: the languages they prefer, in order, for choosing the language of an email.
• created: when it was made.

if (event.type === "customer.created") {
  const customer = event.data.object;
  const key = customer.id;
  const to = customer.email; // can be null
  const yours = customer.metadata.user_id; // only if you set it
}

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

What Kicklace does

With Stripe connected, Kicklace uses the event to know who a customer is. It finds the person by the email on it, or by the Stripe customer id if it knows that, or makes them. It writes the customer id on them, so that later events carrying only the id land on the same person, and it keeps their email in step with Stripe's. A name is filled in only where Kicklace has none. Where a company carries that customer id and is still called Organization, the company takes the customer's name.

Nothing goes on the person's timeline, so no email starts from this event. The first payment does that, as a purchase.

Write yours from your URL. Paste your site's address into the welcome email generator and it writes the welcome and the emails after it in your site's voice, ready to copy, with no sign-up.

Sources

• Types of events
• Stripe CLI: trigger
• The Customer object
• The Checkout Session object
• Send customer emails