Guide for upgrading Stripe API versions and SDKs
</ script
Via npm:
npm install @stripe/stripe-js
Major npm versions correspond to specific Stripe.js versions.
API Version Pairing
Each Stripe.js version automatically pairs with its corresponding API version. For instance:
Dahlia Stripe.js uses
2026-03-25.dahlia
API
Acacia Stripe.js uses
2024-12-18.acacia
API
You can’t override this association.
Migrating from v3
Identify your current API version in code
Review the changelog for relevant changes
Consider gradually updating your API version before switching Stripe.js versions
Stripe continues supporting v3 indefinitely
Mobile SDK Versioning
See
Mobile SDK Versioning
for details.
iOS and Android SDKs
Both platforms follow
semantic versioning
(MAJOR.MINOR.PATCH):
MAJOR
: Breaking API changes
MINOR
: New functionality (backward-compatible)
PATCH
: Bug fixes (backward-compatible)
New features and fixes release only on the latest major version. Upgrade regularly to access improvements.
React Native SDK
Uses a different model (0.x.y schema):
Minor version changes
(x): Breaking changes AND new features
Patch updates
(y): Critical bug fixes only
Backend Compatibility
All mobile SDKs work with any Stripe API version you use on your backend unless documentation specifies otherwise.
Upgrade Checklist
Review the
API Changelog
for changes between your current and target versions
Check
Upgrades Guide
for migration guidance
Update server-side SDK package version (e.g.,
npm update stripe
,
pip install --upgrade stripe
)
Update the
apiVersion
parameter in your Stripe client initialization
Test your integration against the new API version using the
Stripe-Version
header
Update webhook handlers to handle new event structures
Update Stripe.js script tag or npm package version if needed
Update mobile SDK versions in your package manager if needed
Store Stripe object IDs in databases that accommodate up to 255 characters (case-sensitive collation)
Testing API Version Changes
Use the
Stripe-Version
header to test your code against a new version without changing your default:
curl https://api.stripe.com/v1/customers
-u sk_test_xxx:
-H
"Stripe-Version: 2026-03-25.dahlia"
Or in code:
const
stripe =
require
(
'stripe'
)(
'sk_test_xxx'
, {
apiVersion
:
'2026-03-25.dahlia'
// Test with new version
});
Important Notes
Your webhook listener should handle unfamiliar event types gracefully
Test webhooks with the new version structure before upgrading
Breaking changes are tagged by affected product areas (Payments, Billing, Connect, etc.)
Multiple API versions coexist simultaneously, enabling staged adoption