upgrade-stripe
Skill578 starsChanged 6 days agoApache-2.0View on GitHub
Guide for upgrading Stripe API versions and SDKs
- Installs packages
7 other projects use a version of this, 7 of them edited.
Adopted by
Most recently taken up by
- stripe/aiedited, first seen Oct 13, 2026
- openai/pluginsedited, first seen Oct 13, 2026
- sirakinb/claude-code-skillsedited, first seen Oct 11, 2026
- fossasia/eventyayedited, first seen Oct 8, 2026
- NiazMorshed2007/jcredited, first seen Sep 20, 2026
- robinebers/skillsedited, first seen Jun 25, 2026
Other versions7 projects use a version of this.
Word for word · 0
None found.
Edited · 7
- openai/plugins★ 7.8k93% same
- stripe/ai★ 2.1k45% same
- fossasia/eventyay★ 1.7k48% same
- robinebers/skills★ 4888% same
- NiazMorshed2007/jcr★ 1966% same
- Roentek/Claude_Code_Boilerplate_Framework★ 493% same
- sirakinb/claude-code-skills★ 187% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository34 other files it gives its agents.
- AGENTS.mdAGENTS.md
- dashboard/AGENTS.mdAGENTS.md
- docs/AGENTS.mdAGENTS.md
- lego/AGENTS.mdAGENTS.md
- mobile/AGENTS.mdAGENTS.md
- .pm/AGENTS.mdAGENTS.md
- deploy-app-from-localSkill
- deploy-appSkill
- dont-code-but-answerSkill
- loopxSkill
- mermaidSkill
- mock-clusterSkill
- pm-brainstormSkill
- pmSkill
- pmxSkill
- qa-find-bugs-cliSkill
- qa-find-bugsSkill
- releaseSkill
- rt-fix-logic-bugsSkill
- rt-fix-prod-crashesSkill
- rt-flatten-abstractionsSkill
- rt-normalize-abstractionsSkill
- rt-prune-useless-testsSkill
- rt-remove-dead-codeSkill
- rt-simplify-logicSkill
- rt-unify-duplicatesSkill
- security-auditSkill
- shipSkill
- simplifySkill
- stripe-best-practicesSkill
- stripe-directorySkill
- stripe-docsSkill
- stripe-projectsSkill
- unblockSkill
The file
We split this skill into the rules it gives an agent
12 rules. 6 are common, 0 are distinctive, and 6 are very specific to this project.
6
Common
Most of the 7 edited versions we read keep these.
0
Distinctive
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Common: line 76
Always specify the API version you’re integrating against in your code instead of relying on your account’s default API version:
- Very specific: line 123
Consider gradually updating your API version before switching Stripe.js versions
- Common: line 149
All mobile SDKs work with any Stripe API version you use on your backend unless documentation specifies otherwise.
- Common: line 154
Check Upgrades Guide for migration guidance
- Very specific: line 155
Update server-side SDK package version (e.g., npm update stripe, pip install --upgrade stripe)
- Very specific: line 156
Update the apiVersion parameter in your Stripe client initialization
- Very specific: line 157
Test your integration against the new API version using the Stripe-Version header
- Common: line 158
Update webhook handlers to handle new event structures
- Very specific: line 159
Update Stripe.js script tag or npm package version if needed
- Common: line 160
Update mobile SDK versions in your package manager if needed
- Very specific: line 165
Use the Stripe-Version header to test your code against a new version without changing your default:
- Common: line 184
Test webhooks with the new version structure before upgrading
“Common” is measured: kept by at least 6 in 10 of the 7 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
The latest Stripe API version is 2026-06-24.dahlia - use this version when upgrading unless the user specifies a different target version.
Upgrading Stripe Versions
This guide covers upgrading Stripe API versions, server-side SDKs, Stripe.js, and mobile SDKs.
Understanding Stripe API Versioning
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.
Types of Changes
Backward-Compatible Changes (don’t require code updates):
- New API resources
- New optional request parameters
- New properties in existing responses
- Changes to opaque string lengths (e.g., object IDs)
- New webhook event types
Breaking Changes (require code updates):
- Field renames or removals
- Behavioral modifications
- Removed endpoints or parameters
Review the API Changelog for all changes between versions.
Server-Side SDK Versioning
See SDK Version Management for details.
Dynamically-Typed Languages (Ruby, Python, PHP, Node.js)
These SDKs offer flexible version control:
Global Configuration:
import stripe
stripe.api_version = '2026-06-24.dahlia'Stripe.api_version = '2026-06-24.dahlia'const stripe = require("stripe")("sk_test_xxx", {
apiVersion: "2026-06-24.dahlia",
});Per-Request Override:
stripe.Customer.create(
email="customer@example.com",
stripe_version='2026-06-24.dahlia'
)Strongly-Typed Languages (Java, Go, .NET)
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.
Best Practice
Always specify the API version you’re integrating against in your code instead of relying on your account’s default API version:
// Good: Explicit version
const stripe = require("stripe")("sk_test_xxx", {
apiVersion: "2026-06-24.dahlia",
});
// Avoid: Relying on account default
const stripe = require("stripe")("sk_test_xxx");Stripe.js Versioning
See Stripe.js Versioning for details.
Stripe.js uses an evergreen model with major releases (Acacia, Basil, Clover, Dahlia) on a biannual basis.
Loading Versioned Stripe.js
Via Script Tag:
<script src="https://js.stripe.com/dahlia/stripe.js"></script>Via npm:
npm install @stripe/stripe-jsMajor 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-06-24.dahliaAPI - Acacia Stripe.js uses
2024-12-18.acaciaAPI
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
apiVersionparameter in your Stripe client initialization - Test your integration against the new API version using the
Stripe-Versionheader - 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-06-24.dahlia"Or in code:
const stripe = require("stripe")("sk_test_xxx", {
apiVersion: "2026-06-24.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
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

