upgrade-stripe

Stripe バージョンのアップグレード

対象 API バージョンを選択する

ユーザーが対象 API バージョンを指定している場合は、そのバージョンを使用してください。指定がない場合は、利用可能なドキュメントツールまたはウェブツールを使って docs.stripe.com で現在のバージョンを確認してください。たとえば、Stripe CLI で stripe docs /api/versioning を実行します。API バージョン管理のページでは、「The current version is」で始まる文にバージョンが記載されています。

同梱されているフォールバック API バージョン：2026-08-26.dahlia。この値は、このスキルが最後に生成された 2026-10-01 時点のスナップショットにすぎません。バージョン識別子は YYYY-MM-DD 形式のリリース日で始まり、新しい安定版は毎月リリースされるため、1 か月以上前の日付のフォールバックバージョンは古くなっている可能性があります。docs.stripe.com にアクセスできない場合にのみ使用してください。より新しいバージョン番号を推測してはいけません。

変更を加える前に、対象バージョンを、連携で固定されている各 API バージョン（クライアント設定、リクエストごとのオーバーライド、Webhook エンドポイント）と比較してください。ユーザーから明示的な依頼がない限り、固定バージョンを古いバージョンに変更したり、安定版の固定バージョンをプレビュー版に変更したりしないでください。固定バージョンがすでに対象と一致している場合は、変更なしと報告してください。選択した対象と、その情報源を明記してください。ライブでの確認に失敗した場合、または確認できない場合は、最新バージョンを確認できていないと伝え、連携が最新バージョンであると主張しないでください。

Webhook エンドポイントとイベント送信先を確認するときは、スナップショットイベントと薄型イベントを区別してください。薄型イベントのペイロードにはバージョンがないため、API バージョンを変更する際にアップグレードする必要はありません。イベント全体または関連リソースを取得する API 呼び出しには、引き続きバージョンが適用されます。

API バージョンの明示的なオーバーライドに対応している SDK では、選択した対象をクライアント設定とリクエストごとのオーバーライドに使用してください。curl のテスト用 Stripe-Version ヘッダーにも使用してください。例をコピーまたは実行する前に、例に記載されている同梱の API バージョンを選択した対象に置き換えてください。Java、Go、.NET では、SDK 固定バージョンをオーバーライドするのではなく、選択した API バージョンを対象とする SDK リリースを選択してください。プレビュー版を対象にする場合は、すべての言語で対応する beta SDK リリースが必要です。SDK のバージョン管理を参照してください。

Stripe API のバージョン管理について

Stripe は日付ベースの API バージョン（例：2026-08-26.dahlia、2025-08-27.basil、2024-12-18.acacia）を使用します。アカウントの API バージョンによって、リクエストとレスポンスの動作が決まります。

2024-09-30.acacia リリース以降、Stripe は破壊的変更を含まない新しい API バージョンを毎月リリースしています。年に 2 回、新しいメジャーリリース（Basil など）が破壊的変更を含む API バージョンとともに開始されます。コードを更新せずに、任意の月次リリースへ安全にアップグレードできます。

変更の種類

後方互換性のある変更（コードの更新は不要です）：

• 新しい API リソース
• 新しい任意指定のリクエストパラメーター
• 既存のレスポンスにおける新しいプロパティ
• 不透明な文字列の長さの変更（例：オブジェクト ID）
• 新しい Webhook イベントタイプ

破壊的変更（コードの更新が必要です）：

• フィールド名の変更または削除
• 動作の変更
• エンドポイントまたはパラメーターの削除

バージョン間のすべての変更については、API 変更履歴を確認してください。アップグレードの詳細なガイドは、API のアップグレードを参照してください。

サーバーサイド SDK のバージョン管理

コードで API バージョンを設定する方法については、SDK の Stripe API バージョンを設定するを参照してください。

動的型付け言語（Ruby、Python、PHP、Node.js）

これらの SDK では、柔軟なバージョン管理が可能です。

グローバル設定：

import stripe
stripe.api_version = '2026-08-26.dahlia'

Stripe.api_version = '2026-08-26.dahlia'

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-08-26.dahlia'
});

リクエストごとのオーバーライド：

stripe.Customer.create(
  email="[email protected]",
  stripe_version='2026-08-26.dahlia'
)

静的型付け言語（Java、Go、.NET）

これらの SDK では、SDK のリリース日に対応する固定 API バージョンが使用されます。レスポンスオブジェクトが SDK の静的型と一致しない可能性があるため、静的型付け言語では異なる API バージョンを設定しないでください。代わりに、新しい API バージョンを対象とするよう SDK を更新してください。

ベストプラクティス

アカウントのデフォルト API バージョンに依存せず、コード内で連携対象の API バージョンを常に指定してください。

// Good: Explicit version
const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-08-26.dahlia'
});

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

Stripe.js のバージョン管理

詳細については、Stripe.js のバージョン管理をご覧ください。

Stripe.js はエバーグリーンモデルを採用しており、メジャーリリース（Acacia、Basil、Clover、Dahlia）が年に 2 回提供されます。

バージョン指定された Stripe.js の読み込み

スクリプトタグ経由：

<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-08-26.dahlia API を使用します
• Acacia Stripe.js は 2024-12-18.acacia API を使用します

この対応関係は上書きできません。

v3 からの移行

1. コードで現在使用している API バージョンを確認します
2. 変更履歴で関連する変更を確認します
3. Stripe.js のバージョンを切り替える前に、API バージョンを段階的に更新することを検討します
4. 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 バージョンで動作します。

アップグレードのチェックリスト

1. 現在のバージョンと対象バージョンの間の変更について、API の変更履歴を確認します
2. 移行方法について、API アップグレードガイドを確認します
3. サーバーサイド SDK のパッケージバージョンを更新します（例：npm update stripe、pip install --upgrade stripe）
4. Stripe クライアントの初期化時に apiVersion パラメーターを更新します
5. Stripe-Version ヘッダーを使用して、新しい API バージョンで連携をテストします
6. スナップショットイベントを受信する各送信先について、設定されている API バージョンを確認します。Webhook エンドポイントについては、Webhook のバージョン管理に従ってください。Webhook エンドポイント、Amazon EventBridge、Azure Event Grid の送信先など、すべての v2 スナップショットイベント送信先について、snapshot_api_versionを確認し、対象バージョンと異なる場合は、作成後に変更できないため、代替の送信先を作成してテストします。Webhook エンドポイントを置き換える場合は、新しい署名シークレットを保存し、テストと切り替えの間、ハンドラーで両方のシークレットを受け入れるように設定します。切り替え後は、重複配信を避けるため、古い送信先を無効化または削除します。thin イベントの送信先は変更しないでください
7. 必要に応じて、Stripe.js のスクリプトタグまたは npm パッケージのバージョンを更新します
8. 必要に応じて、パッケージマネージャーでモバイル SDK のバージョンを更新します
9. 最大 255 文字に対応するデータベースに Stripe オブジェクト ID を保存します（照合順序では大文字と小文字を区別）

API バージョン変更のテスト

デフォルトを変更せずに新しいバージョンに対してコードをテストするには、Stripe-Version ヘッダーを使用します。

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

または、コード内で次のように指定します。

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-08-26.dahlia'  // Test with new version
});

重要な注意事項

• 対応しているイベントタイプについては、移行ガイドに従って、スナップショットイベントからシンイベントに移行してください。移行後、Webhook ペイロードは API バージョンのアップグレードに依存しなくなります。イベント全体または関連リソースを取得する API 呼び出しには、引き続きバージョンが適用されます。
• Webhook リスナーは、未知のイベントタイプを適切に処理する必要があります。
• アップグレード前に、新しいバージョン構造で Webhook をテストしてください。
• 破壊的変更には、影響を受ける製品領域（Payments、Billing、Connect など）のタグが付けられています。
• 複数の API バージョンが同時に共存するため、段階的に導入できます。
• アップグレード後 72 時間は、Workbench で以前の API バージョンにロールバックできます。