New Cancellation Reason for Test Data Retention

Stripe has introduced a new enum value canceled_by_retention_policy to the cancellation_details.reason attribute on Subscription objects. This value indicates that a subscription has been automatically canceled due to Stripe's test data retention policy, which applies only to subscriptions in test mode.

What Changed

Previously, subscriptions canceled by the retention policy would show a cancellation_details.reason of cancellation_requested, making it unclear whether the cancellation was automatic or user-initiated. With this update, subscriptions automatically canceled by test data retention now explicitly show canceled_by_retention_policy as the reason.

Key points:

• The new reason only appears on test mode subscriptions (where livemode is false)
• This is a breaking change in API version 2026-03-25.dahlia
• The change applies to the Subscriptions API

Required Action Items

If your integration handles subscription cancellations, you must update your code to:

1. Expect the new reason value - Replace any logic checking for cancellation_requested on test subscriptions with canceled_by_retention_policy
2. Add explicit handling - If your code has exhaustive switches or enums for cancellation_details.reason, add a case for canceled_by_retention_policy
3. Upgrade SDKs - Update to the latest SDK version for your language (Python, PHP, Node.js, Go, and others)
4. Test and deploy - Update your API version to 2026-03-25.dahlia, test thoroughly, and perform the upgrade through Workbench (with 72-hour rollback window available)