API Enhancement for Subscription Item Deletion

Stripe has added a new payment_behavior parameter to the subscription item deletion endpoint, giving developers greater control over how payment is handled when removing items from subscriptions.

What Changed

New Parameter: The payment_behavior parameter now accepts subscription item deletions in API version 2026-02-25.clover. When set to pending_if_incomplete, the API stages the deletion as a pending update if the change would generate an invoice requiring payment, rather than immediately removing the item.

Key Benefits

• Consistency: Aligns subscription item deletion with existing payment_behavior options for creating and modifying subscription items
• Payment Safety: Prevents items from being removed before payment is confirmed, avoiding invoice inconsistencies
• Workflow Control: Maintains predictable subscription management across all operations

Upgrade Path

To use this feature, developers must:

1. View their current API version in Stripe Workbench
2. Upgrade relevant SDKs (Ruby, Python, PHP, Java, Node.js, Go, .NET)
3. Update webhook endpoint API versions
4. Test integrations thoroughly in sandbox before production upgrade
5. Finalize the upgrade in Workbench (with 72-hour rollback window available)

SDKs across all major languages have been updated to support the new parameter.