Migration guide for v6

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

Option 1. (Recommended) Upgrade your integration to be compatible with API Version 2023-08-16.

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_..."
+ stripe.api_version = '2020-08-27'

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.

• This change creates a simpler default experience for upgrading your Stripe version. Some users think of upgrading stripe-python in their requirements.txt 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.