Adds metadata support to pending subscription updates
What’s new
Adds support for metadata in pending subscription updates. When you update a Subscription or SubscriptionItem with payment_behavior=pending_if_incomplete, you can now include a metadata parameter. The metadata is stored in pending_update.metadata and applied to the subscription when the pending update is resolved.
Impact
With metadata support in pending subscription updates, you can now attach key-value pairs to a pending update and have them applied when the update is resolved (for example, after a failed payment is retried successfully). When the pending update is applied, the metadata is merged into the existing subscription metadata using merge semantics. New keys are added and existing keys are updated, but unrelated keys are preserved.
Previously, passing metadata with payment_behavior=pending_if_incomplete returned an error. This change is backwards compatible. Existing integrations that don’t pass metadata are unaffected. To learn more, see Pending updates.
Changes
| Parameter | Change | Resources or endpoints |
|---|---|---|
| metadata | Added | Subscription. pending_update |
Upgrade
- View your current API version in Workbench.
- If you use an SDK, upgrade to the corresponding SDK version for this API version.
- If you don’t use an SDK, update your API requests to include Stripe-Version: 2026-05-27. dahlia
- Upgrade the API version used for webhook endpoints .
- Test your integration against the new version.
- If you use Connect, test your Connect integration .
- In Workbench, perform the upgrade . You can roll back the version for 72 hours.
Learn more about Stripe API upgrades.
Related changes
- Adds discount eligibility options for add-on invoice items on Subscriptions and Preview Invoice APIs
- Adds amount paid off Stripe property to Invoice object
- Adds billing schedules to enable prebilling on subscriptions
- Adds discount and discounts properties to pending subscription updates
- Adds credited items information to invoice item proration details
- Adds customer parameter to test clock creation