Name: upgrade-stripe
Author: stripe

最新的 Stripe API 版本為 2026-06-24.dahlia - 除非使用者指定其他目標版本，否則請使用此版本進行升級。

Stripe 版本升級

本指南涵蓋 Stripe API 版本、伺服器端 SDK、Stripe.js 以及行動 SDK 的升級。

了解 Stripe API 版本管理

Stripe 使用基於日期的 API 版本（例如 2026-06-24.dahlia、2025-08-27.basil、2024-12-18.acacia）。您帳戶的 API 版本決定了請求/回應的行為。

變更類型

向後相容的變更（不需要更新程式碼）：

新的 API 資源
新的選用請求參數
現有回應中的新屬性
不透明字串長度的變更（例如物件 ID）
新的 Webhook 事件類型

重大變更（需要更新程式碼）：

欄位重新命名或移除
行為修改
移除的端點或參數

請查閱 API 變更日誌了解版本間的所有變更。

伺服器端 SDK 版本管理

詳情請參閱 SDK 版本管理。

動態型別語言（Ruby、Python、PHP、Node.js）

這些 SDK 提供靈活的版本控制：

全域設定：

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'
});

每次請求覆寫：

stripe.Customer.create(
  email="customer@example.com",
  stripe_version='2026-06-24.dahlia'
)

強型別語言（Java、Go、.NET）

這些語言使用與 SDK 發行日期相符的固定 API 版本。請勿為強型別語言設定不同的 API 版本，因為回應物件可能與 SDK 中的強型別不符。請改為更新 SDK 以鎖定新的 API 版本。

最佳做法

請務必在程式碼中明確指定您要整合的 API 版本，而不是依賴帳戶的預設 API 版本：

// 好：明確指定版本
const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-06-24.dahlia'
});

// 避免：依賴帳戶預設
const stripe = require('stripe')('sk_test_xxx');

Stripe.js 版本管理

詳情請參閱 Stripe.js 版本管理。

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

載入指定版本的 Stripe.js

透過 Script 標籤：

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

透過 npm：

npm install @stripe/stripe-js

主要的 npm 版本對應到特定的 Stripe.js 版本。

API 版本配對

每個 Stripe.js 版本會自動與其對應的 API 版本配對。例如：

Dahlia Stripe.js 使用 2026-06-24.dahlia API
Acacia Stripe.js 使用 2024-12-18.acacia API

您無法覆寫此關聯。

從 v3 遷移

找出程式碼中目前的 API 版本
查閱變更日誌了解相關變更
考慮在切換 Stripe.js 版本前逐步更新 API 版本
Stripe 會無限期繼續支援 v3

行動 SDK 版本管理

詳情請參閱行動 SDK 版本管理。

iOS 與 Android SDK

兩個平台都遵循語意化版本（MAJOR.MINOR.PATCH）：

MAJOR：重大 API 變更
MINOR：新功能（向後相容）
PATCH：錯誤修正（向後相容）

新功能與修正僅在最新的主要版本中發布。請定期升級以取得改進。

React Native SDK

使用不同的模型（0.x.y 結構）：

次要版本變更（x）：重大變更與新功能
修補更新（y）：僅限重大錯誤修正

後端相容性

除非文件另有說明，否則所有行動 SDK 都與您在後端使用的任何 Stripe API 版本相容。

升級檢查清單

查閱 API 變更日誌了解目前版本與目標版本之間的變更
查看升級指南取得遷移指引
更新伺服器端 SDK 套件版本（例如 npm update stripe、pip install --upgrade stripe）
更新 Stripe 客戶端初始化中的 apiVersion 參數
使用 Stripe-Version 標頭測試您的整合是否適用於新的 API 版本
更新 Webhook 處理器以處理新的事件結構
如有需要，更新 Stripe.js 的 script 標籤或 npm 套件版本
如有需要，在套件管理器中更新行動 SDK 版本
在資料庫中儲存 Stripe 物件 ID 時，請使用可容納最多 255 個字元的欄位（區分大小寫的定序）

測試 API 版本變更

使用 Stripe-Version 標頭測試您的程式碼是否適用於新版本，而無需變更預設值：

curl https://api.stripe.com/v1/customers \
  -u sk_test_xxx: \
  -H "Stripe-Version: 2026-06-24.dahlia"

或在程式碼中：

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-06-24.dahlia'  // 使用新版本測試
});

重要注意事項

您的 Webhook 監聽器應能優雅地處理不熟悉的事件類型
在升級前，請使用新版本結構測試 Webhook
重大變更會標記受影響的產品領域（付款、帳單、Connect 等）
多個 API 版本可同時共存，實現分階段採用

upgrade-stripe

相關技能