Stripe Subscription pending updates accept metadata
Introduced 2026-05-27 · score 0.97
HOW TO USE IT
When a subscription change should wait for payment, update the Subscription or SubscriptionItem with `payment_behavior=pending_if_incomplete` and `metadata`; Stripe applies the metadata when the pending update resolves, merging keys into subscription metadata.
curl https://api.stripe.com/v1/subscriptions/<SUBSCRIPTION_ID> -u "<YOUR_SECRET_KEY>" -H "Stripe-Version: 2026-05-27.dahlia" -d payment_behavior=pending_if_incomplete -d "metadata[<KEY>]=<VALUE>"curl https://api.stripe.com/v1/subscription_items/<SUBSCRIPTION_ITEM_ID> -u "<YOUR_SECRET_KEY>" -H "Stripe-Version: 2026-05-27.dahlia" -d payment_behavior=pending_if_incomplete -d "metadata[<KEY>]=<VALUE>"WHY THIS HELPS
When implementing a subscription update that should remain pending until payment succeeds, attach metadata to the pending update.
BEFORE THIS CHANGE
Previously, passing `metadata` with `payment_behavior=pending_if_incomplete` returned an error.
REQUIREMENTS AND LIMITATIONS
- payment_behavior: Optional enum; set to `pending_if_incomplete` to create a pending update when payment fails. Only supported pending-update attributes can be passed.
- metadata: Optional key-value object; attach keys to the pending update. Applied to subscription metadata when resolved; new and updated keys merge while unrelated keys are preserved.
- <SUBSCRIPTION_ID> (required): ID in the Subscription update path.
- <SUBSCRIPTION_ITEM_ID> (required): ID in the SubscriptionItem update path.
- <YOUR_SECRET_KEY> (required): Stripe secret API key used for request authentication.
- Prerequisite: The update endpoint requires an existing subscription; the SubscriptionItem endpoint requires an existing subscription item. API reference setup examples create a payment method, customer, product, price, and subscription (and a subscription item for the item endpoint).
- Prerequisite: `pending_if_incomplete` is for updates, and applies only when payment fails; supported attributes and payment methods are limited.
- Metadata is applied when the pending update is resolved.
- Existing integrations that do not pass `metadata` are unaffected.
FIRST-PARTY EVIDENCE
- https://docs.stripe.com/changelog/dahlia/2026-05-27/pending-subscription-update-metadata
- https://docs.stripe.com/api/subscriptions/update?api-version=2026-05-27.dahlia
- https://docs.stripe.com/api/subscription_items/update?api-version=2026-05-27.dahlia
- https://docs.stripe.com/api/subscriptions/object?api-version=2026-05-27.dahlia#subscription_object-pending_update-metadata
Check the installed version and the source before using it. Entry JSON