Is the customer.subscription.updated event raised when a subscription is renewed?

I’ve verified that customer.subscription.updated is called when the billing period ends.

To do this I intercepted all webhooks that occur at the end of the period (FYI: I used an AWS Lambda function that receives the events from an AWS API Gateway, then puts the events on an SQS queue :))

I agree that the Stripe documentation for the customer.subscription.updated event could be clearer and could cover this use case by saying….

Occurs whenever a subscription changes. Examples would include
when the billing period ends and a new billing period begins, when
switching from one plan to another, or switching status from trial to
active.

(FYI: I would ignore the cheatsheet website altogether. They make only fleeting reference to customer.subscription.updated – In step 8 they are describing (poorly) the use case of “Create a customer with a plan without a trial” which wouldn’t create a customer.subscription.updated event because this event only occurs when the subscription is updated, not when it is created. Where they do reference customer.subscription.updated is in context of Step 12 “Invoice charge attempt fails”)

In defense of Stripes documentation regarding the lifecycle of a subscription, it does say “the following image shows the lifecycle of the most important events that occur” and I’d say customer.subscription.updated is not an important event in context of creating invoices and making payments.

Some details about how Stripe handles the end of a period:

• In my test, Stripe raised the customer.subscription.updated event approximately 2 minutes after the timestamp in the current_period_end property on the subscription. The event has two data objects associated with it. The first is the subscription with the new values on it. The second is a previousAttributes object with the two previous current_period_start and current_period_end values.

• Two events were generated simultaneously: customer.subscription.updated and invoice.created (this was the invoice for the period that had just elapsed).

• Around an hour after the invoice was created, three events were generated simultaneously: invoice.payment_succeeded, charge.succeeded and invoice.updated.

How you treat the rollover of a billing period vs. the payment status of an invoice is really up to you, and very much depends on your application type. That’s the beauty of the Stripe API (and it is a thing of beauty).

In my case, I treat the rollover of a billing period separately to the payment status of an invoice. My application cares about when the billing period rolls over and makes updates to usage based on this, but any payment failures generate alerts & are handled offline.

In summary, you can use customer.subscription.updated to know when the billing period has changed.