Set a Stripe API version

Follow these guidelines to target a different API version than your SDKs use.

Your account has a default API version, which defines how you call the API, what functionality you have access to, and what you’re guaranteed to get back as part of the response. However, when using our server-side SDKs, your API calls to Stripe use the API version that was current when the SDK was released. You can’t target a different version when using a strongly typed language such as Java, Go, or .NET.

Setting the API version

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 https://docs.stripe.com/keys-best-practices.
client = Stripe::StripeClient.new('sk_test_BQokikJOvBiI2HlWgH4olfQ2'
, stripe_version: '2026-03-25.dahlia')

Or set the version per-request:

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

Note

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

Upgrading your API version

Before upgrading your API version, carefully review the following resources:

You can upgrade your account’s default API version in Workbench. Update your code to use the latest version of the SDK and set the new API version when making your calls.

Set a Stripe API version

Follow these guidelines to target a different API version than your SDKs use.

Setting the API version

Note

Upgrading your API version

See also