Public preview
Adds more flexibility for how you manage subscription end-of-period cancellations Public preview
What’s new
We introduced new cancel_at enum values for subscriptions configured with flexible behavior (which have billing_mode set to flexible). This change simplifies canceling a subscription at the end of a billing period with mixed intervals.
The new cancel_at enum values are:
- min _ period _ end
- max _ period _ end
Use these values to cancel the earliest and latest items.data.current_period_end amongst all subscription items.
These new enum values set the cancelation date based on the current subscription’s items.data.current_period_end. Unlike cancel_at_period_end, these values are resolved to timestamps immediately and aren’t affected by further changes to items.data.current_period_end.
The cancel_at_period_end parameter is now deprecated. The behavior of this parameter is unchanged, but in the context of mixed interval subscriptions, it defaults to canceling at the earliest period end.
Impact
The following API endpoints support these new values:
- Create a subscription
- Update a subscription
- Create an invoice preview
If your integration currently uses the deprecated cancel_at_period_end parameter to cancel subscriptions, use the new cancel_at parameter with the min_period_end enum value instead. The cancel_at_period_end field on a Subscription isn’t compatible with the new cancel_at helpers.
Changes
| Fields | Change | From → to |
|---|---|---|
| Invoice#create_preview. subscription_details. cancel_at Subscription#create. cancel_at Subscription#update. cancel_at | Changed | DateTime → DateTime | enum('max_period_end'|'min_period_end') DateTime → DateTime | enum('max_period_end'|'min_period_end') DateTime → DateTime | enum('max_period_end'|'min_period_end') |
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-05-28. preview
- 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.