Subscriptions items can cycle at different intervals using the current_period_start and current_period_end parameters. For example, one item can cycle monthly and another annually. Depending on how you're currently listening to customer.subscription.updated webhook events, you may need to update your integration to determine if an event was for a subscription cycling.

Determine when a subscription cycles

When a subscription cycles to a new billing period, Stripe generates a customer.subscription.updated event. However, not all subscription update events indicate a cycle. To reliably determine if a subscription has cycled, examine specific changes in the event's data.

A subscription has cycled if all the following conditions are true in the customer.subscription.updated event:

• The event's previous_attributes contains a change to the latest_invoice field.
• When the items array is present in previous_attributes, for each item:
  • The item's current_period_end in previous_attributes matches its new current_period_start.
  • The new current_period_start is later than the current_period_start in previous_attributes.

Common pitfalls to avoid

• Don't assume all items cycle together.
• Don't only check the first item in the subscription.
• Don't skip checking the latest_invoice field.
• Don't rely only on checking if items exists in previous_attributes.