upgrade-stripe

Name: upgrade-stripe
Author: stripe

bystripe· 6 skills

Installs

53k

Stars

1.7k

Forks

315

How to install upgrade-stripe?

stripe/ai/upgrade-stripe

$npx -y skills add stripe/ai --skill upgrade-stripe

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/stripe/ai" --skill "stripe/ai/upgrade-stripe"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/stripe/ai" that are relevant to the current task. Run `npx skills add "https://github.com/stripe/ai"` and select the relevant skills, then follow their instructions.

Files · 1

View on GitHub

SKILL.md

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

6 picks

Type

Run `npx skills use "https://github.com/stripe/ai" --skill "stripe/ai/upgrade-stripe"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/stripe/ai" that are relevant to the current task. Run `npx skills add "https://github.com/stripe/ai"` and select the relevant skills, then follow their instructions.

upgrade-stripe

How to install upgrade-stripe?

Related

upgrade-stripe

How to install upgrade-stripe?

Related