Set a Stripe API version
Follow these guidelines to target a different API version than your SDKs use.
Your default API version gets set the first time you make an API request. If your API requests don’t specify an API version with the Stripe-Version header, Stripe uses your account’s default API version, which you can view and upgrade in Workbench.
When you retrieve an event through the API, the structure of the event that Stripe returns is defined by the account’s default API version at the time the event occurred.
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.
Set 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 /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.
Upgrading your API version
To upgrade your account’s default API version, follow the steps in our API upgrades guide. Before upgrading, review the API changelog and view the API versions used by API requests.
See also
Stripe SDKs follow their own versioning policy. See the link below to learn more.