Stripe SDK migration
Upgrade stripe-node across majors with the API version, webhook typings and expanded objects handled.
1 repository · 3 migrations a month · no card
What compat detects
- stripe
- @stripe/stripe-js
- @stripe/react-stripe-js
Stripe pins an API version per SDK major, so a version bump changes response shapes for every call, not only the ones in the changelog. compat finds the pins, the webhook handlers and the nested field reads that move, edits them in a sandbox, and proves the change with your checks.
What breaks across majors
- 01
apiVersion pins and Stripe.LatestApiVersion change with every major.
- 02
stripe.webhooks.constructEvent event typings and event names shift; Stripe.Event narrowing can stop compiling.
- 03
Expandable objects: fields that were ids become objects or the reverse, for example payment_intent, latest_invoice, customer.
- 04
Checkout Sessions, Subscriptions and Invoices renamed fields across majors, such as subscription.current_period_* moving to items.
- 05
Node runtime minimums rise with SDK majors.
Typecheck catches most typing changes because Stripe's types are generated per API version. Tests that mock Stripe objects need updated shapes, and compat lists those files in the pull request.
Stripe v14 to v18 on compat-playground
Recorded runA recorded run: two files changed (package.json and src/billing.ts), the apiVersion pin moved to 2025-08-27.basil, invoice.subscription rewired to invoice.parent.subscription_details.subscription, install, typecheck and test passed, lint and build not run because the repository has no scripts for them. 190 seconds wall clock, $0.57 model cost, zero repair rounds, pull request #2 opened for review.
01
Detect
compat finds the Stripe packages your code imports and the upstream releases that affect them.
02
Migrate and verify
It edits only the affected code in a disposable sandbox, regenerates the lockfile, and runs your existing tests, type checks, lint and build where available.
03
Pull request
It opens a PR with the diff, verification results, warnings and manual steps. A person merges.
Questions
- Does compat merge the Stripe migration automatically?
- No. compat has no merge capability. It pushes a branch and opens a pull request with the diff, the recorded checks and any manual steps. A person on your team reviews and merges.
- Which checks run?
- Your repository's own: install, typecheck, lint, test and build where the scripts exist. Each is listed in the pull request as passed, failed or not run. A check that did not run is never shown as passed.
- Does compat need my production credentials?
- No. Migrations run in a disposable sandbox with your code and package manager, not your environment. Checks that need live credentials are reported as not run.
- How does compat know a release affects my repository?
- It watches the Stripe packages your code imports, reads new release notes, and judges relevance against the files that actually use the SDK. Irrelevant releases are dismissed with the reason; relevant ones become a proposal or, if you allow it, a run.
- Can compat pin a specific Stripe API version?
- Yes. It reads the installed SDK's types before pinning apiVersion and never guesses a date string. Confirming your Stripe account's API version compatibility is listed as a manual step in the pull request.