Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Overview
Versioning
Changelog
Upgrade your API version
Upgrade your SDK version
    Versioning and support policy
    Set an API version
    Stripe.js versioning
Developer tools
SDKs
API
Testing
Workbench
Event Destinations
Workflows
Stripe CLI
Stripe Shell
Developers Dashboard
Agent toolkit
Stripe health alertsBuilding with LLMsStripe for Visual Studio CodeFile uploads
Security
Security
Extend Stripe
Stripe Apps
Stripe Connectors
Partners
Partner ecosystem
Partner certification
HomeDeveloper toolsUpgrade your SDK version

Set a Stripe API version

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

Copy page

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.

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-04-30.basil'

Or set the version per-request:

require 'stripe' intent = Stripe::PaymentIntent.retrieve( 'pi_1DlIVK2eZvKYlo2CW4yj5l2C', { stripe_version: '2025-04-30.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:

  • Stripe API changelog
  • View the API versions used by API requests

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.

See also

Stripe SDKs follow their own versioning policy. See the link below to learn more.

  • Stripe versioning and support policies
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc