upgrade-stripe
Guide for upgrading Stripe API versions and SDKs
- License 许可
- AGPL-3.0
- 所属仓库
- wxdwu/new-api
- 最近更新
- 2026-10-05
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- upgrade-stripe
- description
- Guide for upgrading Stripe API versions and SDKs
02 资源文件 1
- 参考文档agents/openai.yaml239 B
03 SKILL.md 正文
The latest Stripe API version is 2026-02-25.clover - 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-02-25.clover, 2025-08-27.basil, 2024-12-18.acacia). Your account's API version determines request/response behavior.
Types of Changes
Backward-Compatible Changes (do not 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-02-25.clover'
Stripe.api_version = '2026-02-25.clover'
const stripe = require('stripe')('sk_test_xxx', {
apiVersion: '2026-02-25.clover'
});
Per-Request Override:
stripe.Customer.create(
email="customer@example.com",
stripe_version='2026-02-25.clover'
)
Strongly-Typed Languages (Java, Go, .NET)
These 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.
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-02-25.clover'
});
// 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) on a biannual basis.
Loading Versioned Stripe.js
Via Script Tag:
<script src="https://js.stripe.com/clover/stripe.js"></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:
- Clover Stripe.js uses
2026-02-25.cloverAPI - Acacia Stripe.js uses
2024-12-18.acaciaAPI
You cannot 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-02-25.clover"
Or in code:
const stripe = require('stripe')('sk_test_xxx', {
apiVersion: '2026-02-25.clover' // 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
04 同仓库更多 Skills
Zotero
Use Zotero Desktop from Codex to enable/probe the local API, search a local Zotero library, list items/collections/tags, export BibTeX, insert citation keys into LaTeX or Markdown drafts, read indexed full text when requested, and import BibTeX/RIS records into Zotero through the connector server. Use when the user mentions Zotero, citations, references.bib, BibTeX export, local Zotero API, localhost:23119, or adding citations from a Zotero library.
zoom-apps-sdk
Use when using Apps SDK.
setup-zoom-websockets
Use when building Zoom WebSockets.
setup-zoom-webhooks
Use when building Zoom webhooks.
zoom-virtual-agent-web
Zoom Virtual Agent SDK for web embeds. Use for campaign or entry ID chat launch, event-driven controls, user context updates, and CSP-safe deployment.
zoom-virtual-agent-ios
Zoom Virtual Agent iOS integration via WKWebView. Use for Swift/Objective-C script injection, message handlers, support_handoff relay, and URL routing policies.