-
Notifications
You must be signed in to change notification settings - Fork 548
Migration guide for v9
In stripe-ruby v9, the library is now "pinned" to Stripe API Version 2023-08-16. This means, unless you are explicitly specifying an API version, you must modify your Stripe integration to be compatible with 2023-08-16 to upgrade.
Your API version controls the API behavior you see (for example, what properties you see in responses, what parameters you’re permitted to send in requests, and so on).
Prior to v9, when you did not specify an API version, the library would send requests with no Stripe-Version header. These requests would then use your Stripe account's default API version, configurable on the Stripe Dashboard.
Starting in v9, stripe-ruby will always send a Stripe-Version header, and it will no longer be possible to ask stripe-ruby to use your account's default version. If you do not specify an API Version when initializing stripe-ruby, or when making a particular request, stripe-ruby will use the pinned version (2023-08-16 for [email protected]) as the default.
Using the latest API version will give you the best experience when interacting with Stripe Docs, Stripe Dashboard, and Stripe Support.
To upgrade, please read the entries of the API Changelog carefully for each API Version from 2023-08-16 back to your Stripe account's default API version. Determine if you are using any of the APIs that had breaking changes, and adjust your code accordingly. Carefully test your changes with Stripe Test Mode before deploying them to production.
If you wish to avoid upgrading your entire Stripe integration at once, you can individually upgrade each place your integration makes a Stripe request by passing the stripe_version request option.
You should also upgrade your webhooks. Depending on how your webhook endpoints are configured, you will need to either create new webhook endpoints on the latest version, or upgrade your Account's Stripe Version. See the docs for detailed instructions.
To avoid or postpone upgrading API Versions, you can explicitly set an API version when initializing stripe-ruby. If you were already explicitly setting an API version, no change is necessary. If you weren't setting a version, then you should use your Stripe account's default API version to avoid the need to make changes.
require 'stripe'
Stripe.api_key = "sk_test_..."
+ Stripe.api_version = '2020-08-27'This request would use your Stripe account's default API Version in stripe-ruby v8, but it will use 2023-08-16 in v9:
require 'stripe'
Stripe.api_key = "sk_test_..."
Stripe::Customer.create({
name: 'Jenny Rosen',
email: '[email protected]',
})This request would use 2020-08-27 in both v8 and v9:
require 'stripe'
Stripe.api_key = "sk_test_..."
Stripe.api_version = '2020-08-27'
Stripe::Customer.create({
name: 'Jenny Rosen',
email: '[email protected]',
})This request would use 2022-08-01 in both v8 and v9:
require 'stripe'
Stripe.api_key = "sk_test_..."
Stripe::Customer.create({
name: 'Jenny Rosen',
email: '[email protected]',
}, {stripe_version: '2022-08-01'})We believe this will lead to a better overall experience for stripe-ruby users.
- This change creates a simpler default experience for upgrading your Stripe version. Some users think of upgrading stripe-ruby in their Gemfile as "upgrading Stripe", and were surprised to discover the existence of a separate API version managed not in code but on the Dashboard.
- Other Stripe libraries already pin versions. After this release, all server-side Stripe libraries will be pinned, allowing Stripe Support, the Stripe Docs, the Stripe Dashboard, and all library-aware Stripe surfaces to provide a simpler and more consistent experience, because the information relevant to your integration will be identified by a single version (the library version) instead of the combination of two separate versions.
- This change will create a better default experience for using types and docstrings, when introduced.