v22.0.1: `import type Stripe from 'stripe'` does not expose `Stripe.Customer`

[seigo2016]

Describe the bug

stripe@22.0.1 appears to fix the CommonJS constructor regression from #2660.

However, there seems to be a separate TypeScript issue specifically with type-only default imports:

import type Stripe from 'stripe';

let customer: Stripe.Customer; // TS2694: Namespace 'StripeConstructor' has no exported member 'Customer'

In contrast, the standard documented usage continues to work.

import Stripe from 'stripe';

const stripe = new Stripe('your_stripe_secret_key', {
  apiVersion: '2026-03-25.dahlia',
});

async function createCustomer() {
  return await stripe.customers.create({
    email: '',
  });
}

So this does not appear to be a general regression in namespaced Stripe types.
It appears to be specifically about import type Stripe from 'stripe'.

To Reproduce

1. Create a TypeScript project with

• module: "commonjs", moduleResolution: "node", esModuleInterop: true

2. Install stripe@22.0.1
3. Use:

import type Stripe from 'stripe';
let customer: Stripe.Customer;

4. Run tsc

Expected behavior

Either

• import type Stripe from 'stripe' should support references like Stripe.Customer
• the migration guide / README should document that this pattern is no longer supported and recommend the replacement pattern.

Code snippets

OS

WSL2 (Debian) on Windows 11

Node version

Node v22.22.2

Library version

stripe@22.0.1

API version

2026-03-25.dahlia

Additional context

The v22 migration guide documents breaking changes to exported TypeScript types, but it does not mention import type Stripe from 'stripe' as a changed or unsupported pattern. It documents other typing changes such as:

• removal of the old types/ directory

• Stripe.StripeContext -> StripeContextType

• changed type usage for Stripe.errors.StripeError

• Related reports:

  • TypeScript error when initializing Stripe client after upgrading to v22 #2660 follow-up comment: import type Stripe from 'stripe' / Stripe.Customer
  • [Bug] v22: Params types missing from namespaced resource exports (Checkout.SessionCreateParams, etc.) #2662: missing namespaced exports such as Stripe.Checkout.SessionCreateParams

• I am not sure whether these are exactly the same root cause, but they appear closely related.

[konradliebig]

It seems like there is currently no way to access any types with Stripe.X in version 22.

Before we were for example able to use Stripe.CustomerUpdateParams.TaxExempt, but this now errors with Namespace 'StripeConstructor' has no exported member 'CustomerUpdateParams'..

As a workaround, these can all be imported from internal files like import { CustomerUpdateParams } from 'stripe/cjs/resources/Customers';, but this seems like it is not intended and introduces quite a few new imports.

[xavdid]

We're working towards a fix here and will have more news soon.

In the meantime, the best workaround is actually to swap your package type from a CommonJS package to the more modern ESM setup, if possible. In a lot of cases, it's as simple as updating a line in your tsconfig.json & package.json. The types work just like they used to through the ESM entrypoint.

While we do still support CJS in the Node SDK, we are strongly considering moving the package to pure ESM in the future to reduce our surface area and inconsistencies like these. If migrating now is an option for you, I recommend it!

In the meantime, we'll get this fixed (though it's likely you'll need a manual update to get types working again because of the type changes in v22)

[sgarner]

In the meantime, the best workaround is actually to swap your package type from a CommonJS package to the more modern ESM setup, if possible. In a lot of cases, it's as simple as updating a line in your tsconfig.json & package.json. The types work just like they used to through the ESM entrypoint.

Migrating to ESM isn't always that simple. For example, the very popular NestJS framework doesn't yet support ESM for technical reasons, so anyone (like me) building on NestJS cannot use ESM. (NestJS v12 is coming with ESM support in Q3 2026)

The CJS->ESM migration has been a very painful one for the Node community and it's far from over. I think Stripe should continue maintaining CJS support for a while yet.

[xavdid]

That's fair! We know it's not always that simple and I appreciate you giving us such a specific use case. We'll make sure to test it before we make any decisions.

We're also optimistic about the future of ESM because all of the interop-related work the Node.js team has been doing. For example, you can now require ESM packages from common JS code (in node 20+). So there's a good chance that even if we were dropping CJS in the package, CJS users would be able to make a small code change without changing their whole integration.

(we haven't tested this yet, but compatibility wins like that make us optimistic that we'll be able to keep simplifying our codebase without compromising usability)

[mumincelalpinar]

@xavdid @prathmesh-stripe any progress on this? Codebase getting messy without types and we can not understand the structure of any response without them? When do you plan to deploy it?

[prathmesh-stripe]

@mumincelalpinar I am working on a solution for this. We should have a fix for this shipped this week. Thanks again for your patience!

[mumincelalpinar]

@prathmesh-stripe thank you. I am looking forward.

[Bmbona]

+1 confirming this affects Express-based Node.js projects (not just NestJS).

Setup: Express 5 + TypeScript 5.9 + module: "commonjs" + moduleResolution: "node" + esModuleInterop: true + Node 22.

Impact: upgrade from v21.0.1 → v22.1.1 produces 62 tsc errors in a Stripe-heavy backend module (subscriptions, invoices, refunds, schedules, balance transactions, webhook handlers). Root cause is the same as @konradliebig reported: every Stripe.X type access (Subscription, Event, Invoice, Refund, Customer, PaymentIntent, SubscriptionCancelParams, etc.) fails with TS2694: Namespace 'StripeConstructor' has no exported member 'X'.

Verified workaround scope:

• moduleResolution: "bundler" ✅ works (resolves to .esm.d.ts where the namespace is properly merged into the default export)
• moduleResolution: "node" / "node16" ❌ fails (resolves to .cjs.node.d.ts where the StripeConstructor wrap loses the namespace)

For backend Node.js projects compiled with tsc directly (no bundler), switching moduleResolution is disruptive — it changes how all imports resolve across the project, not just stripe. The internal path workaround (stripe/cjs/resources/*) is fragile and not future-proof.

Holding off on v22 upgrade until this is fixed upstream — staying on 21.0.1, which works perfectly. Happy to test a v22.x patch when available.

Tested reproduction (minimal):

import Stripe from 'stripe';
let sub: Stripe.Subscription;  // ❌ TS2694 with moduleResolution:node + module:commonjs

[isnolan]

+1

[prathmesh-stripe]

@Bmbona I have a PR up that should be merged and released as part of our SDK releases. Feel free to test this branch out and we are all ears for your feedback.