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 29.5.0 of the Stripe Java 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 30.0.0 of the Stripe Java 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 29.5.0+ of the Java SDK, identify all StripeClient calls that do not include v2(), and add v1() to the start of the call chain.

StripeClient client = new StripeClient("sk_test...")

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

If you are on version 30.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 Java 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. 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.

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 java --migration v1-namespace -d <path-to-your-codebase>

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

npx @stripe/sdk-migrator --language java --migration v1-namespace -d <path-to-your-codebase> --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.