Breaking changes
Adds subscription item-level billing periods and removes subscription-level periods Breaking changes
What’s new
Subscription items now track their respective billing periods directly instead of as a top-level shared billing period on the subscription resource.
Why is this a breaking change?
- current _ period _ start and current _ period _ end fields are no longer available on the subscription resource.
- previous _ attributes on the customer. subscription. updated webhook now include that the subscription item’s billing period has changed.
Impact
Update any code that references subscription-level current_period_end and current_period_start fields. Instead, access the subscription item’s billing periods directly using items.data.current_period_end and items.data.current_period_start fields.
Make sure that your integration correctly handles the previous_attributes field on the customer.subscription.updated webhook. For instance, for price or quantity changes, inspect the previous_attributes.items.data[].price field.
Changes
| Parameters | Change | Resources or endpoints |
|---|---|---|
| current_period_end current_period_start | Removed | Subscription |
| current_period_end current_period_start | Added | SubscriptionItem |
Upgrade
- View your current API version in Workbench.
- If you use an SDK, upgrade to the corresponding SDK version for this API version.
- If you don’t use an SDK, update your API requests to include Stripe-Version: 2025-03-31. basil
- Upgrade the API version used for webhook endpoints .
- Test your integration against the new version.
- If you use Connect, test your Connect integration .
- In Workbench, perform the upgrade . You can roll back the version for 72 hours.
Learn more about Stripe API upgrades.