customer.updated: what it means and whether to email

What it means

Something about a Stripe customer changed: their email, their name, their address, the default card, or a note you keep on them. The event carries the customer as it is now, and previous_attributes has the old value of whatever changed.

It is a bookkeeping event. Stripe's own advice is to listen for it if you keep a copy of your customers' details, so that the copy does not drift from Stripe's.

When Stripe sends it

Every time any property of a customer changes, so expect many more of these than customer.created. The Customer Portal can change customer-level details such as billing information or the default payment method, and each change sends one.

A change to one of the customer's subscriptions does not send it. Events on subresources, such as customer.subscription.updated, do not trigger a matching event on the customer.

The usual delivery rules apply. The same event can arrive twice, and Stripe promises no order, so a later change can reach you before an earlier one.

Does Stripe email the customer?

No. Nothing in Stripe's list of customer emails is sent because a customer's details changed.

The email to send

Usually none. One is worth sending when previous_attributes contains email: a short note to the old address saying the billing email changed. It lets the real owner say it was not them, and it is a security notice, not marketing.

Subject: The billing email on your [your app] account changed

Hi {{first_name}},

The billing email on your [your app] account was changed today. [Say where billing messages go now.]

If you made the change, there is nothing to do. If you did not, reply to this email straight away and I will look into it.

[Your name]

Kicklace does not send this one, because it does not start emails from this event. It is for your own code.

Fields worth reading

• previous_attributes: only the properties that changed, with their old values. An email in it means the address changed.
• email and name: the customer's address and full name or business name now. Either can be empty.
• invoice_settings.default_payment_method: the card used for the customer's invoices.
• delinquent: true after an automatic payment failure and false again once an invoice is paid. For whether the latest subscription invoice is paid, Stripe says to use the subscription's status instead.
• metadata and preferred_locales: your own ids, and the languages they prefer.

if (event.type === "customer.updated") {
  const customer = event.data.object;
  const before = event.data.previous_attributes;
  const oldEmail = before?.email; // set only when the address changed
  const newEmail = customer.email;
}

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

What Kicklace does

With Stripe connected, Kicklace uses the event the way it uses customer.created. It finds the person by the email on it or by the Stripe customer id it already knows, keeps their email in step with Stripe's, and fills in a name 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 side road or email starts from it.

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

Sources

• Types of events
• Stripe CLI: trigger
• Using webhooks with subscriptions
• The Customer object
• The Event object
• Send customer emails