Set a Stripe API version

Follow these guidelines to make sure that API versions match throughout your Stripe integration.

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. Webhook event objects are based on your default API version, which might be different from the API version used by the SDK. To make sure these versions match, we recommend registering a webhook endpoint with the same API version used as the SDK. To find your version, see View the API versions used by API requests.

Versioning basics

Choose your SDK language to get started. If you’re using curl or Stripe CLI instead of an SDK, refer to our versioning page.

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'
Stripe.api_key =sk_test_BQokikJOvBiI2HlWgH4olfQ2
Stripe.api_version = '2025-05-28.basil'

Or set the version per-request:

require 'stripe'
intent = Stripe::PaymentIntent.retrieve(
  'pi_1DlIVK2eZvKYlo2CW4yj5l2C',
  {
    stripe_version: '2025-05-28.basil',
  }
)
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 Ruby SDK and set the new API version when making your calls.