Adds a duration parameter for schedule phases
What’s new
We introduced a new way to specify the length of a subscription schedule phase using the duration parameter to support mixed interval subscriptions. You can now define time-based durations for subscription schedule phases by length and interval type: day, week, month, year.
The iterations parameter is now marked as deprecated as duration replaces its functionality.
Impact
You can now set the duration of a subscription schedule phase directly using the duration parameter in these following API endpoints:
- Subscription Schedules Create
- Subscription Schedules Update
- Create an invoice preview
Use duration instead of iterations to create or update mixed interval subscription schedules.
Changes
| Parameter | Change | Resources or endpoints |
|---|---|---|
| duration | Added | Invoice#create_preview. schedule_details. phases[] SubscriptionSchedule#create. phases[] SubscriptionSchedule#update. phases[] |
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-07-30. 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.