Migration guide for v6 (original) (raw)

Version pinning

In stripe-python v6, 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.

Details

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 v6, 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 v6, stripe-python will always send a Stripe-Version header, and it will no longer be possible to ask stripe-python to use your account's default version. If you do not specify an API Version when initializing stripe-python, or when making a particular request, stripe-python will use the pinned version (2023-08-16 for stripe-python@6.x.x) as the default.

How to upgrade

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.

Option 2. Explicitly specify an older API version when initializing stripe-python.

To avoid or postpone upgrading API Versions, you can explicitly set an API version when initializing stripe-python. 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.

import stripe stripe.api_key = "sk_test_..."

Examples

This request would use your Stripe account's default API Version in stripe-python v5, but it will use 2023-08-16 in v6:

import stripe stripe.api_key = "sk_test_..."

stripe.Customer.create( name="Jenny Rosen", email="jennyrosen@example.com", )

This request would use 2020-08-27 in both v5 and v6:

import stripe stripe.api_key = "sk_test_..." stripe.api_version = "2020-08-27"

stripe.Customer.create( name="Jenny Rosen", email="jennyrosen@example.com", )

This request would use 2022-08-01 in both v5 and v6:

import stripe stripe.api_key = "sk_test_..."

stripe.Customer.create( name="Jenny Rosen", email="jennyrosen@example.com", stripe_version='2022-08-01', )

Rationale

We believe this will lead to a better overall experience for stripe-python users.