# API バージョン管理の仕組みを理解する

Stripe が API をバージョン管理する方法と、各リクエストで使用するバージョンがどのように選択されるかについて説明します。

Stripe では、予測可能なスケジュールで新機能を導入できるよう API をバージョン管理しています。各リクエスト、Webhook、自動処理には特定の API バージョンが適用され、そのバージョンによって送信できるリクエストパラメーターと受信するオブジェクトの形式が決まります。

API の現行バージョンは **2026-09-30.endive** です。すべての変更ログについては、[API 変更ログ](https://docs.stripe.com/changelog.md)をご覧ください。

月次 API バージョンごとに SDK の新しいマイナーバージョンがリリースされ、年 2 回のメジャーリリースごとに SDK の新しいメジャーバージョンがリリースされます。SDK に互換性に関わる変更を含める必要がある場合は、SDK のメジャーバージョンの更新と月次 API バージョンの更新が同時に行われることがあります。

新しい API バージョンにアップグレードするには、[API のアップグレード](https://docs.stripe.com/upgrades.md) をご覧ください。

## API リリースモデルを理解する

2024-09-30.acacia リリース以降、Stripe は[新しい API リリースプロセス](https://stripe.com/blog/introducing-stripes-new-api-release-process)に従って、互換性に関わる変更のない新しい API バージョンを毎月リリースします。年に 2 回、互換性に関わる変更を含む API バージョンから始まる新しいメジャーリリース ([Basil](https://docs.stripe.com/changelog/basil.md) など) が提供されます。月次リリースは、コードを更新することなく安全にアップグレードできます。新しいメジャーリリースにアップグレードする際には、既存の実装の変更が必要な場合があります。

## API バージョンの適用対象を確認する

API バージョンは、1 回の呼び出しで返される REST レスポンスだけでなく、次の内容も決定します。

- `Stripe-Version` を設定していない場合に送信できるパラメーターと受信するオブジェクト。
- [Stripe.js](https://docs.stripe.com/js.md) が返すオブジェクトの構造。
- Stripe が [Webhook エンドポイント](https://docs.stripe.com/webhooks/versioning.md) に送信するオブジェクトの構造。
- 新しいサブスク期間の請求を作成するなど、Stripe がユーザーに代わって実行する自動 Billing 処理。

### リクエストで API バージョンを指定する方法を確認する

Stripe は、リクエストごとに、以下のいずれかのソースから API バージョンを選択します。

- リクエストの `Stripe-Version` ヘッダー (設定されている場合)。
- サーバーサイド SDK で固定されている API バージョン (SDK を使用している場合)。
- アカウントのデフォルトの API バージョン (バージョンを指定していない場合)。

### デフォルト API バージョンの動作を理解する

デフォルトの API バージョンは、初回の API リクエストを行う際に設定されます。API リクエストの `Stripe-Version` ヘッダーで API バージョンを指定しない場合、アカウントのデフォルトの API バージョンが使用されます。デフォルトのバージョンは[ワークベンチ](https://dashboard.stripe.com/workbench/overview)で確認およびアップグレードできます。

API 経由でイベントを取得する際、Stripe が返すイベントの構造は、イベント発生時におけるアカウントのデフォルトの API バージョンによって定義されます。

Webhook エンドポイントでも独自の API バージョンを固定できます。エンドポイントに明示的なバージョンが設定されている場合、Stripe では常にそのバージョンを使用して、そのエンドポイントにイベントを送信します。

### 組織の API キー

[組織の API キー](https://docs.stripe.com/keys/organization-api-keys.md)を使用するすべての API リクエストには、組織内の実装全体で一貫性と予測可能性を確保するため、`Stripe-Version` ヘッダーを含める必要があります。

### 使用中のバージョンを確認する

1. ワークベンチの[概要](https://dashboard.stripe.com/workbench/overview)タブを開きます。
2. **API バージョン**セクションを調べて、先週のリクエストを確認します。
3. アカウントのデフォルトの **API バージョン**には、(デフォルト) のラベルが表示されます。最新の API バージョンを使用したリクエストには、(最新) のラベルが表示されます。

## 互換性のある変更と互換性に関わる変更を理解する

月次リリースでは、コードを変更しなくても機能が追加されます。メジャーリリースには、フィールド名の変更、パラメーターの削除、オブジェクト形式の変更など、互換性に関わる変更が含まれる場合があります。未知のフィールドやイベントタイプを無視するように実装を設計します。

Stripe では、以下の変更を下位互換性のある変更として扱います。

- 新しい API リソースを追加する。
- 既存の API メソッドに新しいオプションのリクエストパラメーターを追加する。
- 既存の API レスポンスに新しいプロパティを追加する。
- 既存の API レスポンス内のプロパティの順序を変更する。
- オブジェクト ID、エラーメッセージ、その他の可読文字列など、内容を解釈せずに扱う文字列の長さや形式の変更する。
  - これには、固定のプレフィックス (`Charge ID の ch_` など) の追加または削除が含まれます。
  - Stripe で生成されるオブジェクト ID は最大 255 文字になることがあります。実装でこれらの ID を処理できるようにします。たとえば、MySQL を使用している場合は、ID を `VARCHAR(255) COLLATE utf8_bin` 列に格納します (`COLLATE` 設定により、検索時に大文字と小文字が区別されます)。
- 新しいイベントタイプを追加する
  - Webhook リスナーが未知のイベントタイプを問題なく処理できるようにします。

## バージョン識別子を理解する

API バージョンでは、`2024-09-30.acacia` のような日付ベースの識別子を使用します。年 2 回のメジャーリリースには、[Acacia](https://docs.stripe.com/changelog/acacia.md) や [Basil](https://docs.stripe.com/changelog/basil.md) などの名前も付けられます。メジャーリリース後の月次バージョンは同じ名前の系列を引き継ぎ、互換性に関わる変更は導入されません。

## See also

- [実装をアップグレードする](https://docs.stripe.com/upgrades.md)
- [SDK の API バージョンを設定する](https://docs.stripe.com/sdks/set-version.md)
- [Webhook のバージョン管理に対応する](https://docs.stripe.com/webhooks/versioning.md)