I have confirmed that customer.subscription.updated is called when the payment period ends .
To do this, I intercepted all the websites that occur at the end of the period (FYI: I used the AWS Lambda function, which receives events from the AWS API Gateway, and then puts the events in the SQS queue :))
I agree that the Stripe documentation for the customer.subscription.updated event can be clearer and can cover this use case by saying ....
Occurs when a subscription changes. Examples include when the billing period ends and a new billing period begins, when switching from one plan to another, or switching from a trial to an active one.
(FYI: I would completely ignore the cheatsheet site. They only make a passing link to customer.subscription.updated . In step 8 they describe the (poor) use case of “Create a client with a plan without a trial process”, Do not create a customer.subscription.updated event , because this event occurs only when the subscription is updated, and not when it is created. Where are they referenced by customer.subscription.updated in the context of step 12 "Invoice attempt failed")
In defense of the Stripes documentation regarding the subscription life cycle, he says: “The following figure shows the life cycle of the most important events that occur,” and I would say that customer.subscription.updated not an important event in the context of creating invoices making payments.
Some information on how Stripe handles the end of a period:
In my test, Stripe raised the customer.subscription.updated event about 2 minutes after the timestamp in the current_period_end property in the subscription. An event has two data objects associated with it. The first is a subscription with new values on it. The second object is previousAttributes with the two previous values current_period_start and current_period_end .
Two events were generated simultaneously: customer.subscription.updated and invoice.created (it was an invoice for the period just passed).
About an hour after creating the account, three events were created: invoice.payment_succeeded , charge.succeeded and invoice.updated .
How do you feel about the transfer of the billing period compared to the payment status of the invoice, really depends on you and very much depends on the type of your application. This is the beauty of the Stripe API (and it's beautiful).
In my case, I relate to the transfer of the billing period separately to the payment status of the invoice. My application takes care of when the billing period overflows and makes updates for use based on this, but any payment failures generate alerts and are processed offline.
In the end, you can use customer.subscription.updated to find out when the billing period has changed.