upgrade-stripe

Stripe API の最新バージョンは 2026-02-25.clover です。ユーザーが別の対象バージョンを指定しない限り、アップグレード時にはこのバージョンを使用してください。

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

このガイドでは、Stripe API バージョン、サーバーサイド SDK、Stripe.js、モバイル SDK のアップグレードについて説明します。

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

Stripe では日付ベースの API バージョンを使用します（例：2026-02-25.clover、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-02-25.clover'

Stripe.api_version = '2026-02-25.clover'

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-02-25.clover'
});

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

stripe.Customer.create(
  email="[email protected]",
  stripe_version='2026-02-25.clover'
)

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

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

ベストプラクティス

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

// 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 のバージョン管理

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

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

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

スクリプトタグ経由：

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

npm 経由：

npm install @stripe/stripe-js

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

API バージョンの対応関係

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

• Clover Stripe.js は 2026-02-25.clover 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. 移行方法についてはアップグレードガイドを確認します
3. サーバーサイド SDK パッケージのバージョンを更新します（例：npm update stripe、pip install --upgrade stripe）
4. Stripe クライアントの初期化時にapiVersionパラメーターを更新します
5. Stripe-Versionヘッダーを使用して、新しい API バージョンに対するインテグレーションのテストを行います
6. 新しいイベント構造に対応できるよう、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-02-25.clover"

または、コード内で指定します。

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-02-25.clover'  // Test with new version
});

重要な注意事項

• Webhook リスナーは、未知のイベントタイプを適切に処理できる必要があります
• アップグレード前に、新しいバージョンの構造で Webhook をテストしてください
• 破壊的変更には、影響を受ける製品領域（Payments、Billing、Connect など）のタグが付けられています
• 複数の API バージョンが同時に共存するため、段階的に導入できます