upgrade-stripe

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Upgrading Stripe Versions

Stripe版本升级

This skill covers upgrading Stripe API versions, server-side SDKs, Stripe.js, and mobile SDKs.

本指南涵盖Stripe API版本、服务端SDK、Stripe.js及移动端SDK的升级内容。

Understanding Stripe API Versioning

了解Stripe API版本控制

Stripe uses date-based API versions (e.g.,

2025-12-15.clover

2025-08-27.basil

2024-12-18.acacia

). Your account's API version determines request/response behavior.

Stripe采用基于日期的API版本（例如：

2025-12-15.clover

、

2025-08-27.basil

、

2024-12-18.acacia

）。你的账户API版本决定了请求与响应的行为。

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.

向后兼容变更（无需修改代码）：

新增API资源
新增可选请求参数
现有响应中新增属性
不透明字符串长度变更（例如：对象ID）
新增Webhook事件类型

破坏性变更（需要修改代码）：

字段重命名或移除
行为修改
端点或参数移除

查看API变更日志了解版本间的所有变更。

Server-Side SDK Versioning

服务端SDK版本控制

See SDK Version Management for details.

详情请参阅SDK版本管理。

Dynamically-Typed Languages (Ruby, Python, PHP, Node.js)

动态类型语言（Ruby、Python、PHP、Node.js）

These SDKs offer flexible version control:

Global Configuration:

python

import stripe
stripe.api_version = '2025-12-15.clover'

ruby

Stripe.api_version = '2025-12-15.clover'

javascript

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2025-12-15.clover'
});

Per-Request Override:

python

stripe.Customer.create(
  email="customer@example.com",
  stripe_version='2025-12-15.clover'
)

这些SDK提供灵活的版本控制：

全局配置：

python

import stripe
stripe.api_version = '2025-12-15.clover'

ruby

Stripe.api_version = '2025-12-15.clover'

javascript

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2025-12-15.clover'
});

单请求覆盖：

python

stripe.Customer.create(
  email="customer@example.com",
  stripe_version='2025-12-15.clover'
)

Strongly-Typed Languages (Java, Go, .NET)

静态类型语言（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.

这些语言的SDK使用与发布日期匹配的固定API版本。请勿为静态类型语言设置不同的API版本，因为响应对象可能与SDK中的静态类型不匹配。应通过升级SDK来适配新的API版本。

Best Practice

最佳实践

Always specify the API version you're integrating against in your code instead of relying on your account's default API version:

javascript

// Good: Explicit version
const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2025-12-15.clover'
});

// Avoid: Relying on account default
const stripe = require('stripe')('sk_test_xxx');

始终在代码中指定你要集成的API版本，而非依赖账户的默认API版本：

javascript

// 推荐：显式指定版本
const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2025-12-15.clover'
});

// 避免：依赖账户默认版本
const stripe = require('stripe')('sk_test_xxx');

Stripe.js Versioning

Stripe.js版本控制

See Stripe.js Versioning for details.

Stripe.js uses an evergreen model with major releases (Acacia, Basil, Clover) on a biannual basis.

详情请参阅Stripe.js版本控制。

Stripe.js采用常青版本模型，每半年发布一次主要版本（Acacia、Basil、Clover）。

Loading Versioned Stripe.js

加载指定版本的Stripe.js

Via Script Tag:

html

<script src="https://js.stripe.com/clover/stripe.js"></script>

Via npm:

bash

npm install @stripe/stripe-js

Major npm versions correspond to specific Stripe.js versions.

通过脚本标签：

html

<script src="https://js.stripe.com/clover/stripe.js"></script>

通过npm：

bash

npm install @stripe/stripe-js

npm的主要版本对应特定的Stripe.js版本。

API Version Pairing

API版本配对

Each Stripe.js version automatically pairs with its corresponding API version. For instance:

Clover Stripe.js uses
```
2025-12-15.clover
```
API
Acacia Stripe.js uses
```
2024-12-18.acacia
```
API

You cannot override this association.

每个Stripe.js版本会自动与对应的API版本配对。例如：

Clover版本的Stripe.js使用
```
2025-12-15.clover
```
API
Acacia版本的Stripe.js使用
```
2024-12-18.acacia
```
API

你无法覆盖此关联关系。

Migrating from v3

从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

在代码中确认当前使用的API版本
查看变更日志了解相关变更
考虑在切换Stripe.js版本前逐步更新API版本
Stripe会持续支持v3版本

Mobile SDK Versioning

移动端SDK版本控制

See Mobile SDK Versioning for details.

详情请参阅移动端SDK版本控制。

iOS and Android SDKs

iOS和Android SDK

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.

两个平台均遵循语义化版本控制（MAJOR.MINOR.PATCH）：

MAJOR（主版本）：破坏性API变更
MINOR（次版本）：新增功能（向后兼容）
PATCH（补丁版本）：Bug修复（向后兼容）

新功能和修复仅在最新主版本中发布。请定期升级以获取改进。

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

采用不同的版本模型（0.x.y格式）：

次版本变更（x）：包含破坏性变更及新功能
补丁更新（y）：仅包含关键Bug修复

Backend Compatibility

后端兼容性

All mobile SDKs work with any Stripe API version you use on your backend unless documentation specifies otherwise.

除非文档另有说明，否则所有移动端SDK均可与你后端使用的任意Stripe API版本兼容。

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)

查看API变更日志了解当前版本与目标版本间的变更
查看升级指南获取迁移指导

更新服务端SDK包版本（例如：

npm update stripe

、

pip install --upgrade stripe

）

在Stripe客户端初始化代码中更新
```
apiVersion
```
参数
使用
```
Stripe-Version
```
标头测试集成的新API版本
更新Webhook处理器以适配新的事件结构
如有需要，更新Stripe.js脚本标签或npm包版本
如有需要，在包管理器中更新移动端SDK版本
将Stripe对象ID存储在支持最多255字符的数据库中（区分大小写排序）

Testing API Version Changes

测试API版本变更

Use the

Stripe-Version

header to test your code against a new version without changing your default:

bash

curl https://api.stripe.com/v1/customers \
  -u sk_test_xxx: \
  -H "Stripe-Version: 2025-12-15.clover"

Or in code:

javascript

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2025-12-15.clover'  // Test with new version
});

使用

Stripe-Version

标头测试代码在新版本下的表现，无需修改默认版本：

bash

curl https://api.stripe.com/v1/customers \
  -u sk_test_xxx: \
  -H "Stripe-Version: 2025-12-15.clover"

或在代码中：

javascript

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2025-12-15.clover'  // 测试新版本
});

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

你的Webhook监听器应能优雅处理未知事件类型
在升级前测试新版本结构的Webhook
破坏性变更会按受影响的产品领域标记（支付、账单、Connect等）
多个API版本可同时存在，支持分阶段升级