Skip to content

Migration guide for v12

Jump to bottom
Richard Marmorstein edited this page Apr 6, 2023 · 4 revisions

Version pinning

In stripe-node v12, the library is now "pinned" to Stripe API Version 2022-11-15. This means, unless you are explicitly specifying an API version, you must modify your Stripe integration to be compatible with 2022-11-15 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-node will always send a Stripe-Version header, and it will no longer be possible to ask stripe-node to use your account's default version. If you do not specify an API Version when initializing stripe-node, or when making a particular request, stripe-node will use the pinned version (2022-11-15 for stripe-node@12.x.x) as the default.

How to upgrade

Option 1. (Recommended) Upgrade your integration to be compatible with API Version 2022-11-15.

Using the latest API version will give you the best experience when using Typescript types and 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 2022-11-15 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 stripeVersion 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-node.

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

- const stripe = new Stripe('sk_test_...');
+ const stripe = new Stripe('sk_test_...', {apiVersion: 'YYYY-MM-DD'});

Examples

This request would use your Stripe account's default API Version in stripe-node v11, but it will use 2022-11-15 in v12:

const stripe = require('stripe')('sk_test_...');
await stripe.customers.create({email: 'customer@example.com'});

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

stripe = require('stripe')('sk_test_..., {
  apiVersion: '2020-08-27'
});
await stripe.customers.create({email: 'customer@example.com'});

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

const stripe = require('stripe')('sk_test_...');
await stripe.customers.create({email: 'customer@example.com'}, {apiVersion: '2022-08-01'});

Rationale

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

  • This change aligns the default behavior of the library with the Typescript definitions and docstrings. This is useful to all users with Typescript-aware IDEs.
  • This change greates a simpler default experience for upgrading your Stripe version. Some users think of upgrading stripe-node in their package.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 -- stripe-java, stripe-dotnet, and stripe-go -- already pin versions. We plan to eventually pin the version in all server-side Stripe libraries. This will allow Stripe Support, 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.

Other changes

One smaller breaking change - #1743 "Remove Stripe.default and Stripe.Stripe - is also included with this release. We don't expect any users rely on these removed properties. If you do, try using just Stripe instead of Stripe.default or Stripe.Stripe.

Clone this wiki locally