Stripe AI

1---
2description: Guide for upgrading Stripe API versions and SDKs
3alwaysApply: false
4---
5 
6The latest Stripe API version is 2026-01-28.clover - use this version when upgrading unless the user specifies a different target version.
7 
8# Upgrading Stripe Versions
9 
10This guide covers upgrading Stripe API versions, server-side SDKs, Stripe.js, and mobile SDKs.
11 
12## Understanding Stripe API Versioning
13 
14Stripe uses date-based API versions (e.g., `2026-01-28.clover`, `2025-08-27.basil`, `2024-12-18.acacia`). Your account's API version determines request/response behavior.
15 
16### Types of Changes
17 
18**Backward-Compatible Changes** (do not require code updates):
19- New API resources
20- New optional request parameters
21- New properties in existing responses
22- Changes to opaque string lengths (e.g., object IDs)
23- New webhook event types
24 
25**Breaking Changes** (require code updates):
26- Field renames or removals
27- Behavioral modifications
28- Removed endpoints or parameters
29 
30Review the [API Changelog](https://docs.stripe.com/changelog.md) for all changes between versions.
31 
32## Server-Side SDK Versioning
33 
34See [SDK Version Management](https://docs.stripe.com/sdks/set-version.md) for details.
35 
36### Dynamically-Typed Languages (Ruby, Python, PHP, Node.js)
37 
38These SDKs offer flexible version control:
39 
40**Global Configuration:**
41```python
42import stripe
43stripe.api_version = '2026-01-28.clover'
44```
45 
46```ruby
47Stripe.api_version = '2026-01-28.clover'
48```
49 
50```javascript
51const stripe = require('stripe')('sk_test_xxx', {
52  apiVersion: '2026-01-28.clover'
53});
54```
55 
56**Per-Request Override:**
57```python
58stripe.Customer.create(
59  email="customer@example.com",
60  stripe_version='2026-01-28.clover'
61)
62```
63 
64### Strongly-Typed Languages (Java, Go, .NET)
65 
66These use a fixed API version matching the SDK release date. Do not set a different API version for strongly-typed languages because response objects might not match the strong types in the SDK. Instead, update the SDK to target a new API version.
67 
68### Best Practice
69 
70Always specify the API version you're integrating against in your code instead of relying on your account's default API version:
71 
72```javascript
73// Good: Explicit version
74const stripe = require('stripe')('sk_test_xxx', {
75  apiVersion: '2026-01-28.clover'
76});
77 
78// Avoid: Relying on account default
79const stripe = require('stripe')('sk_test_xxx');
80```
81 
82## Stripe.js Versioning
83 
84See [Stripe.js Versioning](https://docs.stripe.com/sdks/stripejs-versioning.md) for details.
85 
86Stripe.js uses an evergreen model with major releases (Acacia, Basil, Clover) on a biannual basis.
87 
88### Loading Versioned Stripe.js
89 
90**Via Script Tag:**
91```html
92<script src="https://js.stripe.com/clover/stripe.js"></script>
93```
94 
95**Via npm:**
96```bash
97npm install @stripe/stripe-js
98```
99 
100Major npm versions correspond to specific Stripe.js versions.
101 
102### API Version Pairing
103 
104Each Stripe.js version automatically pairs with its corresponding API version. For instance:
105- Clover Stripe.js uses `2026-01-28.clover` API
106- Acacia Stripe.js uses `2024-12-18.acacia` API
107 
108You cannot override this association.
109 
110### Migrating from v3
111 
1121. Identify your current API version in code
1132. Review the changelog for relevant changes
1143. Consider gradually updating your API version before switching Stripe.js versions
1154. Stripe continues supporting v3 indefinitely
116 
117## Mobile SDK Versioning
118 
119See [Mobile SDK Versioning](https://docs.stripe.com/sdks/mobile-sdk-versioning.md) for details.
120 
121### iOS and Android SDKs
122 
123Both platforms follow **semantic versioning** (MAJOR.MINOR.PATCH):
124- **MAJOR**: Breaking API changes
125- **MINOR**: New functionality (backward-compatible)
126- **PATCH**: Bug fixes (backward-compatible)
127 
128New features and fixes release only on the latest major version. Upgrade regularly to access improvements.
129 
130### React Native SDK
131 
132Uses a different model (0.x.y schema):
133- **Minor version changes** (x): Breaking changes AND new features
134- **Patch updates** (y): Critical bug fixes only
135 
136### Backend Compatibility
137 
138All mobile SDKs work with any Stripe API version you use on your backend unless documentation specifies otherwise.
139 
140## Upgrade Checklist
141 
1421. Review the [API Changelog](https://docs.stripe.com/changelog.md) for changes between your current and target versions
1432. Check [Upgrades Guide](https://docs.stripe.com/upgrades.md) for migration guidance
1443. Update server-side SDK package version (e.g., `npm update stripe`, `pip install --upgrade stripe`)
1454. Update the `apiVersion` parameter in your Stripe client initialization
1465. Test your integration against the new API version using the `Stripe-Version` header
1476. Update webhook handlers to handle new event structures
1487. Update Stripe.js script tag or npm package version if needed
1498. Update mobile SDK versions in your package manager if needed
1509. Store Stripe object IDs in databases that accommodate up to 255 characters (case-sensitive collation)
151 
152## Testing API Version Changes
153 
154Use the `Stripe-Version` header to test your code against a new version without changing your default:
155 
156```bash
157curl https://api.stripe.com/v1/customers \
158  -u sk_test_xxx: \
159  -H "Stripe-Version: 2026-01-28.clover"
160```
161 
162Or in code:
163 
164```javascript
165const stripe = require('stripe')('sk_test_xxx', {
166  apiVersion: '2026-01-28.clover'  // Test with new version
167});
168```
169 
170## Important Notes
171 
172- Your webhook listener should handle unfamiliar event types gracefully
173- Test webhooks with the new version structure before upgrading
174- Breaking changes are tagged by affected product areas (Payments, Billing, Connect, etc.)
175- Multiple API versions coexist simultaneously, enabling staged adoption
176 
177