Stripe subscription item deletion supports pending payment behavior
Introduced 2026-02-25 · score 0.96
HOW TO USE IT
When deleting a subscription item would create an invoice that requires payment, pass `payment_behavior=pending_if_incomplete` to stage the deletion as a pending update. The parameter is optional; pending updates accept only supported parameters.
curl -X DELETE https://api.stripe.com/v1/subscription_items/<SUBSCRIPTION_ITEM_ID> \
-u "<YOUR_SECRET_KEY>" \
-H "Stripe-Version: 2026-02-25.clover" \
-d "payment_behavior=pending_if_incomplete"WHY THIS HELPS
When implementing subscription changes that may require payment, defer deleting a subscription item until payment is confirmed.
BEFORE THIS CHANGE
Previously, subscription items could only be deleted immediately.
REQUIREMENTS AND LIMITATIONS
- subscription item ID (required): Identifies the subscription item in the DELETE endpoint path.
- payment_behavior: Controls behavior when payment is required. `pending_if_incomplete` uses pending updates; allowed values are `allow_incomplete`, `default_incomplete`, `error_if_incomplete`, and `pending_if_incomplete`. The docs do not say these values are mutually exclusive; it is a single enum parameter.
- Prerequisite: Have an existing subscription item to delete. The reference's example setup creates a payment method, customer, product, price, subscription, and subscription item.
- Prerequisite: Authenticate the API request with a Stripe secret key.
- Prerequisite: Use API version `2026-02-25.clover` to access the release-note change; the changelog says requests should specify this version when upgrading the REST API.
- This behavior applies when the change would generate an invoice that requires payment.
FIRST-PARTY EVIDENCE
- https://docs.stripe.com/changelog/clover/2026-02-25/subscription-item-deletion-payment-behavior-control
- https://docs.stripe.com/api/subscription_items/delete?api-version=2026-02-25.clover
Check the installed version and the source before using it. Entry JSON