Breaking changes

Adds retention policy cancellation reason to Subscriptions Breaking changes

What’s new

Adds the canceled_by_retention_policy enum value to the cancellation_details.reason attribute on Subscription objects.

This value indicates that a subscription has been cancelled automatically due to Stripe’s test data retention policy. This reduces confusion when reviewing test subscriptions that appear to have been cancelled unexpectedly.

The retention policy only applies to subscriptions created in test mode or a sandbox. Therefore, the canceled_by_retention_policy reason can only appear on subscriptions where livemode is false.

Why is this a breaking change?

For subscriptions cancelled by Stripe’s test data retention policy, the cancellation_details.reason property is now canceled_by_retention_policy instead of cancellation_requested.

Impact

If your integration expects subscriptions cancelled by the retention policy to have a cancellation_details.reason of cancellation_requested, then you need to update your code to expect a value of canceled_by_retention_policy instead. Also, if your integration explicitly handles all possible values of cancellation_details.reason, you need to update your code to handle the new canceled_by_retention_policy value.

Changes

Upgrade

1. View your current API version in Workbench.
2. 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: 2026-03-25. dahlia

3. Upgrade the API version used for webhook endpoints .
4. Test your integration against the new version.
5. If you use Connect, test your Connect integration .

Learn more about Stripe API upgrades.