Migration guide for v22

Version 22 of the Node SDK continues to use the 2026-03-25.dahlia API version introduced in version 21, so no Stripe-specific business logic needs to change if you're already on version 21. If you're upgrading from an older API version, see the Dahlia API Changelog for general migration assistance.

This document describes the upgrade process for the SDK-specific breaking changes we introduced in version 22. There are two categories of breaking changes:

• Changes to exported TypeScript types
• Changes to service method arguments

As part of this change, we adjusted how our CommonJS worked. While CJS is still supported, we highly recommend updating your integration to use ES modules, the modern packaging standard. Stripe packages support both importing systems today but we will move away from supporting CJS imports in the future.

// CJS Import (before)
const stripe = require("stripe");
const stripeClient = new Stripe('sk_test...');

// ESM Import (after)
import Stripe from "stripe";

Breaking Typing Changes

Before v22.0.0, we maintained TypeScript types in a separate folder. In v22.0.0, we started generating most of our types using the TypeScript compiler instead of internal tooling.

The types/ directory was removed

If you use /// <reference types="stripe/types" /> directives pointing at the old types/path, remove them - they are no longer needed. TypeScript will resolve types automatically from the exports map.

Stripe.StripeContext is no longer exported as a type

If you reference the StripeContext type from the Stripe namespace, you should now use StripeContextType:

// Before
const context: Stripe.StripeContext = new Stripe.StripeContext();
// After
const context: Stripe.StripeContextType = new Stripe.StripeContext();

Stripe.errors.StripeError type usage changed

The type of Stripe.errors.StripeError is now the class constructor itself, not an instance type. If you were using it as a type for error instances:

// Before
let err: Stripe.errors.StripeError;

// After
let err: typeof Stripe.errors.StripeError;
// Or more simply, use InstanceType:
let err: InstanceType<typeof Stripe.errors.StripeError>;
// Or ErrorType
let err: Stripe.ErrorType;

Breaking Runtime Changes

For years, the Node SDK has supported more arguments to its service methods than the types imply. These were all supported despite none of them passing a type check:

stripe.customers.retrieve('cus_123', 'sk_test_123')
stripe.customers.create({name: 'david', host: 'example.com'}, 'sk_test_123')
stripe.customers.create({apiKey: 'sk_test_123'})
stripe.customers.list(customers => {
  // do something with customers
})

To fix a few surprising bugs and inconsistencies in the SDK, we've changed the runtime code to match the type signature. Your code may need to be updated to continue working. The good news is that the type checker will hopefully make this straightforward by correctly flagging code that no longer works.

Remove Callback support for service methods

Now that promises and async / await are widely available, we're discontinuing callback support for service methods (those that correspond to an API resource). To upgrade, use promises instead:

// ❌ before:
stripe.customers.list(customers => {
  // do something with customers
})

// ✅ after:
const customers = await stripe.customers.list()
// do something with customers

// or:
stripe.customers.list().then(customers =>
  // do something with customers
)

Note

Functions that took well-typed callbacks (like autoPagingEach) are unaffected by this change

No longer allow setting host per-request

We used to allow altering the host of an API call on a per-request basis. It's still possible to change the host per-client, but the option is now ignored at the request level.

// ❌ before:
const stripe = Stripe('sk_test_123')
stripe.customers.retrieve('cus_123', undefined {host: 'localhost'})

// ✅ after:
const stripe = Stripe('sk_test_123', {host: 'localhost'})
stripe.customers.retrieve('cus_123')

RequestOptions must be the last arg (if present)

Service methods that take optional params and options used to allow options in either order. Now you must pass undefined explicitly if you're not passing params:

// ❌ before:
stripe.customers.retrieve('cus_123', {stripeAccount: 'acct_123'})

// ✅ after:
stripe.customers.retrieve('cus_123', undefined, {stripeAccount: 'acct_123'})

The new type signatures are explicit about this:

retrieve(
  id: string,
  params?: CustomerRetrieveParams,
  options?: RequestOptions
): Promise<Response<Customer | DeletedCustomer>>;
- retrieve(
-   id: string,
-   options?: RequestOptions
- ): Promise<Response<Customer | DeletedCustomer>>;

Remove support for string API key arguments

API keys must be passed as part of a RequestOptions argument:

// ❌ before:
stripe.customers.retrieve('cus_123', 'sk_test_123')

// ✅ after:
stripe.customers.retrieve('cus_123', {apiKey: 'sk_test_123'})

Stripe is now a proper ES6 class (not a factory function)

The internal createStripe() factory function is replaced by an exported class Stripe. This is largely transparent, but has runtime implications:

• the new operator is required to instantiate Stripe
• instanceof Stripe now works correctly

// ❌ before:
const stripeClient = Stripe("sk_test_...");

// ✅ after:
const stripeClient = new Stripe("sk_test_...");

CJS Imports have changed

The CJS entry point no longer exports .default or .Stripe as separate properties. The export is just the constructor wrapper itself:

// ❌ before:
const { Stripe } = require('stripe');
// or
const Stripe = require('stripe').default;

// ✅ after:
const Stripe = require('stripe');
const StripeClient = new Stripe('sk_test...');

Removed some methods from StripeResource

The following public methods have been removed from StripeResource:

• createFullPath
• createResourcePathWithSymbols
• extend
• method
• _joinUrlParts

They were always meant mostly for internal use and SDK construction and do not have 1:1 replacements.

If you were making ad-hoc API requests to custom resources in tests, use StripeResource._make_request directly (but probably just open an issue so we can better understand your use case).