Overview

The Stripe Subscription API now includes a new cancellation reason enum value: canceled_by_retention_policy. This addition clarifies why certain test subscriptions are automatically canceled, reducing confusion during development and testing.

What Changed

The cancellation_details.reason property on Subscription objects now returns canceled_by_retention_policy when a subscription has been automatically canceled due to Stripe's test data retention policy. This value can only appear on test mode subscriptions where livemode is false.

Breaking Change Details:

• Subscriptions previously showing cancellation_details.reason as cancellation_requested will now display canceled_by_retention_policy if canceled by the retention policy
• This is a breaking change affecting integrations that explicitly handle all possible cancellation_details.reason values

Required Actions

If your integration handles subscription cancellations, you must:

• Update code expecting cancellation_requested for retention policy cancellations to handle the new canceled_by_retention_policy value
• Ensure all possible values of cancellation_details.reason are properly handled
• Test against the new Dahlia API version before upgrading to production

Upgrade Path

1. Check your current API version in Workbench
2. Upgrade your SDK to the corresponding version for Dahlia, or update API requests to include Stripe-Version: 2026-03-25.dahlia
3. Update webhook endpoints to use the new API version
4. Test your integration thoroughly in both test and production modes
5. Perform the upgrade in Workbench (you can roll back for 72 hours if needed)