I'm confused about why Stripe's documentation suggests the customer.subscription.updated
event is not fired when I believe it should:
subscription
object has the properties current_period_start
and current_period_end
which would be updated whenever the customer successfully pays a subscription's invoices ( https://stripe.com/docs/api#subscriptions )The documentation for the customer.subscription.updated
event states that it...
Occurs whenever a subscription changes. Examples would include switching from one plan to another, or switching status from trial to active.
...which would imply that the event would be raised if the current_period_start
and current_period_end
values change, but it doesn't affirm if it does or it does not in this case.
However this third-party webpage states that it is not raised when a successful renewal is performed ( https://www.masteringmodernpayments.com/stripe-webhook-event-cheatsheet#8 ).
But raising the event just makes sense...
customer.subscription.updated
) then it would greatly simplify program code without needing to also monitor invoice.payment_succeeded
, invoice.created
and charge.succeeded
.customer.subscription.updated
event at all.It just seems odd that such an appropriate event is not raised when it should be. The documentation also really doesn't say when the current_period_end
and current_period_start
values are updated either, which limits their utility.
So in my application, after receiving an invoice.payment_succeeded
event, how can my program code determine when the customer's subscription period will end next?
Subscription Cycle means each billing cycle which is one (1) month in length unless we communicate a different time period to you in writing at the time of sign up; Sample 1.
To test it, create a subscription in test mode. Then, log in to the portal as the test user and update the subscription. Check the Dashboard or API to see whether the subscription reflects the customer's change. Read the integration guide to learn how to set up the customer portal.
Failed payments If automatic payment fails, the subscription updates to past_due and Stripe attempts to recover payment based on your retry rules. If payment recovery fails, you can set the subscription status to canceled , unpaid , or leave it past_due .
Subscription payments, or recurring payments, are repeated transactions that are scheduled on a regular basis. Any time a consumer has a continued service or product purchase, they may opt for a subscription or recurring payment plan.
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.
customer.subscription.updated
is triggered when current_period_start
and current_period_end
change. These represent the billing period.
When invoice.payment_succeeded
happens, it's there that you must update the information on your side (e.g.: subscription period): https://stripe.com/docs/subscriptions/guide#step-3-sync-with-your-site
Also more info here: https://support.stripe.com/questions/what-events-can-i-see-when-a-subscription-is-renewed
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With