v1 namespace in StripeClient

In September 2024, Stripe introduced APIs in a new v2 namespace (e.g. /v2/core/event_destinations). These APIs follow new paradigms for authentication, request serialization, idempotency, and pagination, that differentiate them from the ones in the v1 namespace (e.g. /v1/customers). See API v2 overview for more details.

While the APIs in the v2 namespace were surfaced in the SDKs via a corresponding v2 namespace in the StripeClient class, no changes were made at the time to existing APIs in the SDKs. We have since realized the importance of being able to clearly distinguish the two kinds of APIs due to the semantic differences between them.

In version 12.5.0 of the Stripe Python SDK, we addressed this by copying over all the non-v2 services that were available at the top level of StripeClient to a new v1 namespace under StripeClient.

In version 13.0.0 of the Stripe Python SDK, the top level non-namespaced services will be marked as deprecated, but will continue to be supported till a major version in late 2026.

What should you do?

If you have been using StripeClient in your integration and are upgrading to version 12.5.0+ of the Python SDK, identify all StripeClient calls that do not include v2, and add v1 to the start of the call chain.

client = StripeClient("sk_test...")

- client.customers.retrieve("cus_123");
+ client.v1.customers.retrieve("cus_123");

If you are on version 13.0.0 or higher, your editor will show deprecation warnings for calls that should be changed.

Automated migration

We’ve built SDK Migrator to help you migrate to the new v1 namespace. The script will run locally and uses ast-grep over all Python files in a directory to find usages of StripeClient and updates all the call sites with the newly added v1 namespace.

Warning

sdk-migrator makes its best effort to migrate your code (especially with dynamic languages). Make sure you have all your code checked in a version control system (e.g. Git) before using this tool. Always review and test your code before deploying.

Typed Python Codebases

If you use types and have a decently typed codebase, you can run the following command with the path to your codebase to view the set of files that will be migrated:

npx @stripe/sdk-migrator --language python --migration v1-namespace -d <path-to-your-codebase>

Run the command with –execute flag to actually modify the files:

npx @stripe/sdk-migrator --language python --migration v1-namespace -d <path-to-your-codebase> --execute

Untyped Python codebases

If you do not use types and/or have a minimally typed codebase, you can run the following command with --untyped flag to view the set of files that will be migrated:

npx @stripe/sdk-migrator --language python -d ~/stripe-integration --migration v1-namespace --untyped

Run the command with --execute flag to actually modify the files:

npx @stripe/sdk-migrator --language python -d ~/stripe-integration --migration v1-namespace --untyped --execute

We will be adding more migration scripts in the future to help you migrate between major versions and we are looking for feedback to improve the SDK Migrator. Use Github issues on SDK Migrator repo for providing suggestions.