API upgrades

Learn how to manage API versions and handle breaking changes in major releases.

To upgrade your integration, complete the following steps. Search the Changelog for information specific to your integration.

Define the target version for your upgrade

Make sure that you specify the API version that you’re integrating against in your code instead of relying on your account’s default API version. To test a newer version for API calls, set the Stripe-Version header (in live or testing environments). Learn how to set an API version in our server-side SDKs.

View which API versions your integration uses in the Overview tab of Workbench.

Review the Changelog to find the target version for your upgrade.

Specify the API version in your SDK

Your account has a default API version that defines how you call the API, what functionality you have access to, and the structure of API responses. When you use a server-side SDK, your API calls to Stripe use the API version that was current when the SDK was released. You can’t target a different API version when using a strongly typed language, such as Java, Go, or.NET.

The stripe-ruby library allows you to set the API version globally or on a per-request basis.

If you don’t set an API version, recent versions of stripe-ruby use the API version that was latest at the time your version of stripe-ruby was released. Versions of stripe-ruby before v9 use your account’s default API version.

To set the API version globally with the SDK, assign the version to the Stripe.api_version property:

require 'stripe'
# Don't put any keys in code. See /keys-best-practices.
client = Stripe::StripeClient.new('sk_test_Ou1w6LVt3zmVipDVJsvMeQsc', stripe_version: '2026-08-26.dahlia')

Or set the version per-request:

require 'stripe'
# Don't put any keys in code. See /keys-best-practices.
client = Stripe::StripeClient.new('sk_test_Ou1w6LVt3zmVipDVJsvMeQsc')
intent = client.v1.payment_intents.retrieve(
 'pi_1DlIVK2eZvKYlo2CW4yj5l2C',
 {
 stripe_version: '2026-08-26.dahlia',
 },
)
intent.capture

Note

When you override the version globally or per-request, the API response objects are also returned in that version.

Update your code to handle API changes

Review your most important requests and update your code to handle changes to the response. For each request, review the relevant breaking changes in the changelog to understand the changes required to adopt your target version.

View your API requests in the Overview tab of Workbench.

Update your event destinations

Private preview

Thin events for API v1 resources are available in private preview. You can use them to streamline integration upgrades without changing your webhook configuration. Previously, thin events only supported API v2 resources. Learn more and request access.

Review each event destination that receives snapshot events, including webhook endpoints and cloud destinations for Amazon EventBridge and Azure Event Grid. For snapshot events, the destination’s snapshot_api_version property controls the API version used to render the event payload. This setting is independent of the API version used by your server-side SDK. Thin event payloads are unversioned.

You can set snapshot_api_version only when you create an event destination. To use a different API version, create and test a destination configured with that version before deleting the existing destination. If both destinations are active during the migration, your event handler must be idempotent because Stripe delivers subscribed events to both destinations.

Update your webhook endpoints

To upgrade your webhook endpoints, you need to verify incoming webhook signatures and allow traffic from Stripe public IP addresses. You also need to create new endpoints, redirect traffic to them, then disable the old endpoints.

Create new disabled webhook endpoints

Create a new webhook endpoint with the following parameters:

• url : the same URL as your original webhook endpoint, but add a query parameter to distinguish between events sent to the two different endpoints. For example https://example. com/webhooks?version=2024-04-10 .
• enabled _ events : the same events as your original webhook endpoint.
• api _ version : the API version you want to upgrade to. If you’re upgrading to the latest API version, you can use the Dashboard or the API to create the endpoint. For other versions, use the API to set a specific version.

After you create the new webhook endpoint, disable it. You’ll re-enable it in the next step.

Update your webhook code to ignore events sent to the new endpoint

Update your event processing code:

• If the query parameter is for the older API version, process it as usual.
• If the query parameter is for the newer API version, ignore the event and return a 200 response to prevent delivery retries.

Next, enable the new webhook endpoint that you created in the previous step. At this point every event is sent twice: once with the old API version and once with the new one.

Update your webhook code to process events for the new endpoints

Update your event processing code:

• If the query parameter is for the older version, ignore the event. We recommend returning a 400 status to let Stripe automatically retry the event. This ensures that if you need to revert, events are re-sent to the older webhook endpoint.
• If the query parameter is for the new version, process it.

Monitor your webhook endpoints

Monitor traffic to the new webhook endpoints to confirm that they process events correctly.

If events aren’t being correctly handled by your new code, try the following:

1. Revert to the earlier version of your code.
2. Temporarily disable the new webhook endpoint.
3. Process the failed events (if you returned a 400 status as described in the previous step, Stripe automatically resends all the events).
4. Investigate and fix the issue.
5. Enable the new webhook endpoint and resume monitoring.

Disable the old webhook endpoint

After the upgrade is successful, disable the old webhook endpoint to stop your server from returning 400 status. If you don’t disable it, this may cause issues with integrations that rely on a 200 response.

After you disable the old webhook endpoint, Stripe won’t re-deliver events that returned a 400.

Test and monitor your integration

Test your integration in a sandbox to confirm that it handles the new version as expected.

In addition to the general testing guidance, follow the guidelines for the products and resources that your integration uses:

• Billing : Use test clocks to simulate subscriptions .
• Invoicing : Test webhook notifications, payment failures and other scenarios.
• Connect : Create test accounts and use them for verification testing .
• Terminal : Test simulated reader updates .
• Payment Intents : Create PaymentIntents and use test card numbers to simulate payments.