v1 namespace in StripeClient

In September 2024, Stripe introduced APIs in a new v2 namespace (e.g. /v2/core/eventdestinations). 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.