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.

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.

require 'stripe'
# Don't put any keys in code. See /keys-best-practices.
client = Stripe::StripeClient.new('sk_test_...', stripe_version: '2026-09-30.endive')

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

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.

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.

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 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.