最新の Stripe API バージョンは 2026-04-22.dahlia です。ユーザーが異なるターゲットバージョンを指定しない限り、アップグレード時にこのバージョンを使用してください。

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

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

Stripe API バージョニングの理解

Stripe では日付ベースの API バージョン（例：2026-04-22.dahlia、2025-08-27.basil、2024-12-18.acacia）を使用します。アカウントの API バージョンは、リクエスト/レスポンスの動作を決定します。

変更の種類

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

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

破壊的な変更（コード更新が必要）：

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

バージョン間のすべての変更については、API Changelog を確認してください。

サーバーサイド SDK バージョニング

詳細については SDK Version Management を参照してください。

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

これらの SDK は柔軟なバージョン管理を提供します：

グローバル設定：

import stripe
stripe.api_version = '2026-04-22.dahlia'

Stripe.api_version = '2026-04-22.dahlia'

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

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

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

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

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

ベストプラクティス

アカウントのデフォルト API バージョンに依存するのではなく、常にコードで統合しているAPI バージョンを明示的に指定してください：

// 推奨: 明示的なバージョン
const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-04-22.dahlia'
});

// 非推奨: アカウントのデフォルトに依存
const stripe = require('stripe')('sk_test_xxx');

Stripe.js バージョニング

詳細については Stripe.js Versioning を参照してください。

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-04-22.dahlia API を使用
• Acacia Stripe.js は 2024-12-18.acacia API を使用

この関連付けをオーバーライドすることはできません。

v3 からのマイグレーション

1. コード内の現在の API バージョンを特定する
2. 関連する変更について変更履歴を確認する
3. Stripe.js バージョンを切り替える前に、API バージョンを段階的に更新することを検討する
4. Stripe は v3 を無期限にサポート継続

モバイル SDK バージョニング

詳細については Mobile SDK Versioning を参照してください。

iOS および Android SDK

両プラットフォームはセマンティックバージョニング（MAJOR.MINOR.PATCH）に従います：

• MAJOR：破壊的な API 変更
• MINOR：新機能（後方互換性あり）
• PATCH：バグ修正（後方互換性あり）

新機能と修正は最新のメジャーバージョンのみでリリースされます。改善にアクセスするために定期的にアップグレードしてください。

React Native SDK

異なるモデル（0.x.y スキーマ）を使用します：

• マイナーバージョン変更（x）：破壊的な変更と新機能
• パッチ更新（y）：重大なバグ修正のみ

バックエンド互換性

すべてのモバイル SDK は、ドキュメントで特に指定されていない限り、バックエンドで使用する任意の Stripe API バージョンで動作します。

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

1. API Changelog で現在のバージョンとターゲットバージョン間の変更を確認する
2. マイグレーション guidance について Upgrades Guide を確認する
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-04-22.dahlia"

またはコード内：

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-04-22.dahlia'  // 新しいバージョンでテスト
});

重要な注意事項

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