# Adds metadata support to pending subscription updates ## What’s new Adds support for [metadata](https://docs.stripe.com/api/subscriptions/object.md?api-version=2026-05-27.dahlia#subscription_object-pending_update-metadata) in pending subscription updates. When you update a [Subscription](https://docs.stripe.com/api/subscriptions/update.md?api-version=2026-05-27.dahlia) or [SubscriptionItem](https://docs.stripe.com/api/subscription_items/update.md?api-version=2026-05-27.dahlia) 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](https://docs.stripe.com/billing/subscriptions/pending-updates.md). ## Changes #### REST API | Parameter | Change | Resources or endpoints | | ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------- | | `metadata` | Added | [Subscription.pending_update](/api/subscriptions/object?api-version=2026-05-27.dahlia#subscription_object-pending_update) | #### Ruby | Parameter | Change | Resources or methods | | ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------- | | `metadata` | Added | [Subscription::PendingUpdate](/api/subscriptions/object?api-version=2026-05-27.dahlia#subscription_object-pending_update) | #### Python | Parameter | Change | Resources or methods | | ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------ | | `metadata` | Added | [Subscription.PendingUpdate](/api/subscriptions/object?api-version=2026-05-27.dahlia#subscription_object-pending_update) | #### PHP | Parameter | Change | Resources or methods | | ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------- | | `metadata` | Added | [Subscription.pending_update](/api/subscriptions/object?api-version=2026-05-27.dahlia#subscription_object-pending_update) | #### Java | Parameter | Change | Resources or methods | | ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------- | | `metadata` | Added | [Subscription.pending_update](/api/subscriptions/object?api-version=2026-05-27.dahlia#subscription_object-pending_update) | #### Node.js | Parameter | Change | Resources or methods | | ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------- | | `metadata` | Added | [Subscription.pending_update](/api/subscriptions/object?api-version=2026-05-27.dahlia#subscription_object-pending_update) | #### Go | Parameter | Change | Resources or methods | | ---------- | ------ | ----------------------------------------------------------------------------------------------------------------------- | | `Metadata` | Added | [SubscriptionPendingUpdate](/api/subscriptions/object?api-version=2026-05-27.dahlia#subscription_object-pending_update) | #### .NET | Parameter | Change | Resources or methods | | ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------ | | `Metadata` | Added | [Subscription.PendingUpdate](/api/subscriptions/object?api-version=2026-05-27.dahlia#subscription_object-pending_update) | ## Upgrade #### REST API 1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench. 1. 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](https://docs.stripe.com/api/versioning.md) to include `Stripe-Version: 2026-05-27.dahlia` 1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md). 1. [Test your integration](https://docs.stripe.com/testing.md) against the new version. 1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md). 1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours. Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md). #### Ruby 1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench. 1. Upgrade your Ruby SDK to the latest version. 1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md). 1. [Test your integration](https://docs.stripe.com/testing.md) against the new version. 1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md). 1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours. Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md). #### Python 1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench. 1. Upgrade your Python SDK to the latest version. 1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md). 1. [Test your integration](https://docs.stripe.com/testing.md) against the new version. 1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md). 1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours. Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md). #### PHP 1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench. 1. Upgrade your PHP SDK to the latest version. 1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md). 1. [Test your integration](https://docs.stripe.com/testing.md) against the new version. 1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md). 1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours. Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md). #### Java 1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench. 1. Upgrade your Java SDK to the latest version. 1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md). 1. [Test your integration](https://docs.stripe.com/testing.md) against the new version. 1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md). 1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours. Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md). #### Node.js 1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench. 1. Upgrade your Node SDK to the latest version. 1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md). 1. [Test your integration](https://docs.stripe.com/testing.md) against the new version. 1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md). 1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours. Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md). #### Go 1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench. 1. Upgrade your Go SDK to the latest version. 1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md). 1. [Test your integration](https://docs.stripe.com/testing.md) against the new version. 1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md). 1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours. Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md). #### .NET 1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench. 1. Upgrade your .NET SDK to the latest version. 1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md). 1. [Test your integration](https://docs.stripe.com/testing.md) against the new version. 1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md). 1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours. Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md). ## Related changes - [Adds discount eligibility options for add-on invoice items on Subscriptions and Preview Invoice APIs](https://docs.stripe.com/changelog/dahlia/2026-05-27/invoice-items-discount-eligibility.md) - [Adds amount paid off Stripe property to Invoice object](https://docs.stripe.com/changelog/dahlia/2026-05-27/invoice-object-amount-paid-off-stripe-property.md) - [Adds billing schedules to enable prebilling on subscriptions](https://docs.stripe.com/changelog/dahlia/2026-05-27/subscriptions-billing-schedules.md) - [Adds discount and discounts properties to pending subscription updates](https://docs.stripe.com/changelog/dahlia/2026-05-27/pending-subscription-updates-discount-and-discounts-properties.md) - [Adds credited items information to invoice item proration details](https://docs.stripe.com/changelog/dahlia/2026-05-27/invoice-item-proration-credited-items.md) - [Adds customer parameter to test clock creation](https://docs.stripe.com/changelog/dahlia/2026-05-27/test-clock-creation-customer-parameter.md)