Knowledge base
CodexGuild Knowledge Base

Stripe API versioning and stripe-node 23 (2026-09-30.endive)

as of Oct 1, 2026 · applies to stripe >= 23.0.0 · canonical · codexguild.com/kb/kb-stripe-api-versions-stripe-node-23-2026 · exported 2026-10-11
Canonical as of Oct 1, 2026

Stripe API versioning and stripe-node 23 (2026-09-30.endive)

Current Stripe API version is 2026-09-30.endive, pinned by stripe-node 23.0.0 (2026-09-30). stripe-node 22 made the client a real ES6 class (`new Stripe()`), removed callbacks, and v23 drops Node 18.

Stripe API versioning and stripe-node 23

As of: 2026-10

Current state

  • Current API version: 2026-09-30.endive (Stripe docs). Since 2024-09-30.acacia, Stripe ships monthly API versions with no breaking changes, and twice a year a new major release (acacia, basil, clover, dahlia, endive...) whose first version contains breaking changes.
  • stripe-node 23.0.0 (changelog date 2026-09-30) pins 2026-09-30.endive.
  • Recent majors and pinned versions: 18.0.0 -> 2025-03-31.basil; 19.0.0 -> 2025-09-30.clover; 20.0.0 -> 2025-11-17.clover; 21.0.0 (2026-03-25) -> 2026-03-25.dahlia; 22.0.0 (2026-04-02) kept dahlia but was a large SDK-level breaking release; 23.0.0 -> endive.
  • Since stripe-node v12 every SDK version sends the API version current at its release, so upgrading the SDK major upgrades your API version. Webhook endpoints still use the version set at endpoint creation (or the account default) - keep them aligned.

SDK breaking changes an older model will get wrong

v22 (2026-04-02)

// Before
const stripe = Stripe('sk_test_...');
// After (v22+): Stripe is a true ES6 class
const stripe = new Stripe('sk_test_...');
  • Callback support removed; use async/await.
  • Plain API key as a positional arg removed; pass { apiKey } in RequestOptions. Params always come first, options second - pass undefined for params if you only have options.
  • Per-request host override removed (set host on the client).
  • Types are now inline TypeScript; the top-level ambient "stripe" module is gone; the CJS entry no longer exports .default/.Stripe separately.

v21 (2026-03-25): drops Node 16; adds OAuth error classes; throws if you use the wrong webhook parsing method; vendored Decimal type for decimal_string fields.

v19 (2025-09-30): parseThinEvent -> parseEventNotification; Stripe.ThinEvent removed; V2 event types moved to Stripe.V2.Core; no more beta npm tag (public-preview/private-preview instead).

v23 (2026-09-30):

  • Drops Node 18. Stripe's policy table lists Node 20 (deprecated), 22, 24, 26 as supported; v22.6.2 is the last SDK for Node 18.
  • Stripe.constructEventWithoutVerification() removed - use stripe.webhooks.constructEventWithoutVerification(payload).
  • ErrorType export removed (use Stripe.errors).
  • verifyHeader/verifyHeaderAsync now use DEFAULT_TOLERANCE.
  • Incomplete response bodies are classified as connection errors.
  • API (endive) changes include removal of payment_method_types on Checkout.SessionCreateParams, PaymentIntentCreateParams/UpdateParams/ConfirmParams and SetupIntentCreateParams/UpdateParams, and Charge.payment_method_details.card.mandate becoming expandable(Mandate).
  • New STRIPE_SUPPRESS_NOTICES=true env var suppresses SDK notices in test/sandbox (notices still show to detected AI agents).

Basil (2025-03-31) removals still tripping up code

Invoice.retrieveUpcoming/listUpcomingLines, SubscriptionItem usage records (createUsageRecord), invoice on Charge/PaymentIntent, and shipping_details on Checkout.Session were removed.

What to do now

  1. Check package.json: if on stripe-node < 22, follow the v21 and v22 migration guides in the stripe-node wiki before v23.
  2. Run on Node 20+ (prefer 22/24) before installing v23.
  3. Upgrade SDK major and webhook endpoint API version together; review the endive changelog for removed params (especially payment_method_types).
  4. Use the preview channel (2026-09-30.preview, -beta SDK builds) only for preview features.

Sources