Migration guide for v12

Version pinning

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

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

  // if using StripeClient
- $stripe = new \Stripe\StripeClient('sk_test_xyz');
+ $stripe = new \Stripe\StripeClient([
+   'api_key' => 'sk_test_xyz',
+   'stripe_version' => '2020-08-27',
+ ]);

  // if using the global client
\Stripe\Stripe::setApiKey('sk_test_xyz');
+ \Stripe\Stripe::setApiVersion('2020-08-27');

Examples

This request would use your Stripe account's default API Version in stripe-php v10, but it will use 2023-08-16 in v12:

// If using StripeClient
$stripe = new \Stripe\StripeClient([
  'api_key' => 'sk_test_xyz',
]);

$stripe->customers->create([
  'name' => 'Jenny Rosen',
  'email' => 'jenny.rosen@example.com'
]);

// If using the global client
\Stripe\Stripe::setApiKey('sk_test_xyz');

\Stripe\Customer::create([
  'name' => 'Jenny Rosen',
  'email' => 'jenny.rosen@example.com'
]);

This request would use 2020-08-27 in both previous versions and v12:

// If using StripeClient
$stripe = new \Stripe\StripeClient([
  'api_key' => 'sk_test_xyz',
  'stripe_version' => '2020-08-27',
]);

$stripe->customers->create([
  'name' => 'Jenny Rosen',
  'email' => 'jenny.rosen@example.com'
]);

// If using the global client
\Stripe\Stripe::setApiKey('sk_test_xyz');

\Stripe\Customer::create([
  'name' => 'Jenny Rosen',
  'email' => 'jenny.rosen@example.com'
]);

This request would use 2022-08-01 in both previous version and v12:

// If using StripeClient
$stripe = new \Stripe\StripeClient([
  'api_key' => 'sk_test_xyz',
]);

$stripe->customers->create([
  'name' => 'Jenny Rosen',
  'email' => 'jenny.rosen@example.com'
],
[
  'stripe_version' => '2022-08-01',
]);

// If using the global client
\Stripe\Stripe::setApiKey('sk_test_xyz');

\Stripe\Customer::create([
  'name' => 'Jenny Rosen',
  'email' => 'jenny.rosen@example.com'
],
[
  'stripe_version' => '2022-08-01',
]);

Rationale

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

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