Stripe Subscription updates support cancel_at_period_end in pending updates
Introduced 2026-09-30 · score 0.93
HOW TO USE IT
When an update should cancel a subscription at the current period end after payment succeeds, update it with `payment_behavior=pending_if_incomplete` and `cancel_at_period_end=true`. Stripe stores the setting in `pending_update` if payment fails or requires customer action; a conflicting later cancellation value expires the pending update.
curl https://api.stripe.com/v1/subscriptions/<subscription_id> \
-u "<YOUR_SECRET_KEY>:" \
-d payment_behavior=pending_if_incomplete \
-d proration_behavior=always_invoice \
-d "items[0][id]=<subscription_item_id>" \
-d "items[0][price]=<price_id>" \
-d cancel_at_period_end=trueWHY THIS HELPS
When scheduling an incomplete Subscription update that should also cancel at the billing period end, set cancel_at_period_end as part of the pending update.
BEFORE THIS CHANGE
Before this change, passing `cancel_at_period_end` with `payment_behavior=pending_if_incomplete` returned an error.
REQUIREMENTS AND LIMITATIONS
- subscription_id (required): Subscription ID in the update URL.
- payment_behavior (required): Set to `pending_if_incomplete` to use pending updates.
- cancel_at_period_end (required): Set to `true` to cancel at the current period end; supported for pending updates.
- proration_behavior: `always_invoice` creates an invoice and attempts payment when the update is made.
- items[0][id]: Subscription item ID to update; included in the documented example.
- items[0][price]: Price ID to apply to the subscription item; included in the documented example.
- Prerequisite: Pending updates require `collection_method=charge_automatically` and a supported payment method.
- Prerequisite: The update must generate an invoice to trigger a pending update; `proration_behavior=always_invoice` does so in the documented example.
- Prerequisite: Authenticate the API request with a Stripe secret key.
- cancel_at_period_end is a nullable boolean property of pending_update on a Subscription.
- The cancellation takes effect at the end of the current billing period after the pending update applies.
- A conflicting cancel_at_period_end value in a subsequent update expires the existing pending update.
FIRST-PARTY EVIDENCE
- https://docs.stripe.com/changelog/endive/2026-09-30/scheduled-subscription-cancellation
- https://docs.stripe.com/billing/subscriptions/pending-updates
- https://docs.stripe.com/api/subscriptions/update?api-version=2025-04-30.basil
Check the installed version and the source before using it. Entry JSON