upgrade-stripe

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

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

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

同梱のフォールバック API バージョン：2026-09-30.endive。この値は、このスキルが最後に生成された 2026-10-14 時点のスナップショットにすぎません。バージョン識別子は 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 versioning を参照してください。

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

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

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

変更の種類

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

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

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

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

バージョン間のすべての変更については、API changelog を確認してください。アップグレード手順の全体については、API upgrades を参照してください。

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

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

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

これらの SDK では、柔軟にバージョンを管理できます。

グローバル設定：

import stripe
stripe.api_version = '2026-09-30.endive'

Stripe.api_version = '2026-09-30.endive'

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-09-30.endive'
});

リクエスト単位のオーバーライド：

stripe.Customer.create(
  email="[email protected]",
  stripe_version='2026-09-30.endive'
)

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

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

ベストプラクティス

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

// Good: Explicit version
const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-09-30.endive'
});

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

Stripe.js のバージョン管理

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

Stripe.js は、メジャーリリース（Acacia、Basil、Clover、Dahlia、Endive）を年2回行う、エバーグリーンモデルを採用しています。

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

スクリプトタグ経由：

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

npm 経由：

npm install @stripe/stripe-js

npm のメジャーバージョンは、それぞれ特定の Stripe.js バージョンに対応しています。

API バージョンの対応関係

各 Stripe.js バージョンは、対応する API バージョンと自動的に組み合わされます。たとえば、次のとおりです。

• Endive Stripe.js は 2026-09-30.endive 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 エンドポイントを置き換える場合は、新しい署名シークレットを保存し、テストと切り替えの間はハンドラーが両方のシークレットを受け入れるように設定します。切り替え後、重複配信を避けるため、古い送信先を無効化または削除します。シンイベントの送信先は変更しないでください
7. 必要に応じて、Stripe.js のスクリプトタグまたは npm パッケージのバージョンを更新します
8. 必要に応じて、パッケージマネージャーでモバイル SDK のバージョンを更新します
9. Stripe オブジェクト ID は、最大255文字に対応するデータベース（大文字と小文字を区別する照合順序）に保存します

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

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

curl https://api.stripe.com/v1/customers \
  -u sk_test_xxx: \
  -H "Stripe-Version: 2026-09-30.endive"

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

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-09-30.endive'  // Test with new version
});

重要な注意事項

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