岡本 秀高

Stripe APIバージョン「Basil」で変わる10のこと – 従量課金から請求書機能まで

Knowledge
Stripe

Stripe は2025年3月31日、新しい API バージョン「 Basil 」をリリースしました。このバージョンには多数の破壊的変更（Breaking Change） が含まれており、 Stripe API を利用しているアプリケーションには大きな影響がある可能性があります。特に従量課金、請求書プレビュー、サブスクリプション管理などの請求関連の機能に重要な変更があるとアナウンスされています。そのため、これらの機能を使用しているシステムは特に注意が必要です。

このガイドでは、 Basil バージョンの主要な変更点と、それぞれに対する適切な対応方法を解説します。 API の更新を計画する上でも、どんな破壊的変更があり、どのAPIへの対応が必要かをチェックしてみましょう。

https://docs.stripe.com/changelog/basil

Basil での主な破壊的変更と対応策

Stripe では、 Acacia / Basil などAPIのメジャーアップデートにコードネームが付与されます。ここでは2025年3月31日にリリースされたBasilでの破壊的変更とその対応策について詳しく解説します。

1. リスト表示時の合計数拡張サポートの削除

このバージョンから、リスト系APIでの total_count プロパティが完全に削除されました。そのため、 include[]=total_count または exclude[]=total_count パラメーターを利用することができなくなります。

もしBasil以降のバージョンで total_count を利用すると、 HTTP 400 の property_forbidden エラーが発生します。

影響を受ける機能

  • ページネーション機能で合計数を表示する UI 要素を持つアプリケーション
  • 特定の条件に一致するオブジェクトの総数を表示する機能
  • 「全100件中10件表示」のようなページネーション表示

対応方法

ページネーションのシステムを更新し、 has_more レスポンスフィールドのみに依存するよう変更する必要があります。ページネーションの作り方については、Stripeのページネーションドキュメントを参照しましょう。

2. Checkoutセッションの処理方法変更

サブスクリプションは、ユーザーが支払いを完了した後に作成されるようになりました。この変更により、Checkout Session API のレイテンシが改善され、ユーザー体験が向上します。しかし一方で、　Payment Intent や Subscription の作成タイミングが変更されています。この変更は Checkout を使用してサブスクリプションを作成するすべての実装、支払いインテントの Webhook から請求書情報を取得するフロー、Checkout セッション完了時の処理フローに影響します。

影響を受ける機能

  • Checkout を使用してサブスクリプションを作成するすべての実装
  • 支払いインテントの Webhook から請求書情報を取得するフロー
  • Checkout セッション完了時の処理フロー

対応方法

Payment IntentのWebhook イベントから請求書を参照しているシステムは、代わりにcheckout_session.completed Webhook を使用するように更新してください。また、顧客がサブスクリプションに関する情報を必要とする場合は、Checkoutセッションが完了した後に提供するようにしてください。

3 レガシーの従量課金機能の廃止

従来から提供されていた従量課金のサポートが完全に終了し Meter APIを利用した新しい従量課金システムのみが利用できるようになります。関連して、 UsageRecord と UsageRecordSummary のAPIリソースが削除されました。また、 meter を指定せずに metered の usage_type を持つ価格を作成できなくなりました。この変更は従来の従量課金システムを使用しているすべてのアプリケーション、 UsageRecord API エンドポイントを使用している実装、 Subscription エンドポイントの billing_thresholds パラメーターを使用している実装、 Price エンドポイントの aggregate_usage パラメーターを使用している実装に影響します。

影響を受ける機能

  • レガシー従量課金を使用しているすべてのアプリケーション
  • UsageRecord API エンドポイントを使用している実装
  • Subscription API エンドポイントの billing_thresholds パラメーターを使用している実装
  • Price エンドポイントの aggregate_usage パラメーターを使用している実装

対応方法

移行ガイドに従って新しいMeter APIを利用したシステムに移行する必要があります。新しい Meter API を利用した従量課金では、Meter リソースを作成し、MeterをPrice に関連付け、Meter Event API を使用して使用量を報告するという手順が必要です。既存のレガシー従量制価格は引き続き機能しますが、新規作成や修正はできません。新しい Meter ベースの課金システムの詳細は Stripe のドキュメントを参照してください。

4 Upcoming Invoice API メソッドの廃止

GET /v1/invoices/upcoming API エンドポイントと GET /v1/invoices/upcoming/lines API エンドポイントが削除されました。これらは Create Preview Invoice API に置き換えられています。この変更は今後の請求書のプレビューを表示するアプリケーション、サブスクリプション変更前の料金シミュレーション機能、顧客の次回請求書を表示する機能に影響します。

影響を受ける機能

  • 今後の請求書のプレビューを表示するアプリケーション
  • サブスクリプション変更前の料金シミュレーション機能
  • 顧客の次回請求書を表示する機能

対応方法

GET /v1/invoices/upcomingの代わりにPOST /v1/invoices/create_previewを使用するようコードを更新してください。新しいAPIでは同等の機能が提供されますが、パラメーターの構造が変更されています。また、複数のサブスクリプションを持つ顧客の場合、各サブスクリプションに対して個別にAPIコールを行う必要があります。具体的には、subscription、subscription_details.items、schedule、schedule_details.phases、または invoice_items などのパラメーターを customer パラメーターと共に指定する必要があります。

変更前後のコード例

変更前

GET /v1/invoices/upcoming?customer=cus_123&subscription=sub_456

変更後

POST /v1/invoices/create_preview
{
  "customer": "cus_123",
  "subscription": "sub_456"
}

5 クーポン機能の変更

終了日が指定されていない永続期間の割引クーポンが削除され、併用可能な割引でクーポンとプロモーションコードのパラメーターも削除されました。この変更は永続的なクーポン（終了日なし）を使用するビジネスモデルや、複数のクーポンを組み合わせて使用するシステムに影響します。

影響を受ける機能

  • 永続的なクーポン（終了日なし）を使用するビジネスモデル
  • 複数のクーポンを組み合わせて使用するシステム

対応方法

既存の無期限クーポンについては適切な終了日を設定し、クーポン作成ロジックを更新して、すべての新規クーポンに終了日を設定するよう変更してください。必要に応じて、長期間（数年）の終了日を設定することで実質的な「無期限」クーポンを実現することも可能です。

6 請求書関連の変更

請求書のデータ構造が大きく変わります。トップレベルに存在した Price フィールドが、 Invoice Item と Invoice Line Item の pricing モデルに置き換えられ、トップレベルの tax 関連プロパティが、 Invoice 、 Invoice Line Item 、 Credit Note Line Item の新しい tax モデルに置き換えられました。

  • price フィールドと plan フィールドは、Invoice Item と Invoice Line Item では使用できなくなりました。
  • total_tax_amounts は Invoice オブジェクトで使用できなくなりました。
  • tax_rates と tax_amounts は、Invoice Line Item オブジェクトと Credit Note Line Item オブジェクトで使用できなくなりました。
  • unit_amount と unit_amount_decimal は、Invoice Item と Invoice Line Item の新しい pricing コンセプトに移行します。

また、請求書の手動税額に jurisdiction level と taxability reason が追加されました。この変更は請求書データを処理するシステム、請求書データを外部システムにエクスポートする機能、カスタム請求書レポートを生成するアプリケーション、税金計算を行うシステムに影響します。

影響を受ける機能

  • 請求書のデータを参照・処理するシステム
  • カスタムの請求書レポートを行う仕組み
  • 税金計算を行うシステム

対応方法

まず、上で紹介しているプロパティを参照しているアプリケーションがないかを確認してください。もし参照している場合は、Stripeのドキュメントを参考にして、同様のデータを参照できるプロパティが存在するかチェックしましょう。

7 サブスクリプション関連の変更

公式ドキュメント:サブスクリプション項目の請求期間を追加し、サブスクリプションの期間を削除
公式ドキュメント:請求リソースに、その作成方法が指定されるようになりました

サブスクリプションのパラメータが一部変更されました。 current_period_start フィールドと current_period_end フィールドは Subscription リソースで使用できなくなっています。これにより、異なる請求サイクルを持つ項目が同じサブスクリプションに含まれる場合でも、より正確な情報が提供さるようになります。また、請求リソースには、自動生成されたものか、手動で作成されたものかを示す情報が含まれるようになりました。

対応方法

サブスクリプション期間データを使用するコードを更新し、 Subscription Item にてこの情報を取得するよう変更してください。UIを更新し、サブスクリプション項目ごとに期間を表示するよう変更を検討してください。請求書の生成方法に依存するロジックがある場合は、メタデータを活用するよう更新してください。

8 決済関連の変更

公式ドキュメント:Vault and Forward API を更新し、タイムアウトに402ステータスコードを返す
公式ドキュメント:Interacカードの手動キャプチャーのメソッドを削除
公式ドキュメント:Naver Payのフィールドが変更できなくなる仕様
公式ドキュメント:決済の一部をキャプチャーまたはキャンセルしても、返金は作成されない
公式ドキュメント:オンライン請求書ページでKlarnaのサポートを追加

部分的なキャプチャーやキャンセルが行われても自動的に返金が作成されなくなり、明示的な返金処理が必要になりました。その他、 Forward API を利用した際のタイムアウトエラーのステータスや日本国外で利用できる決済手段について変更が加わっています。

この変更は Vault and Forward API を使用するシステム、 Interac カードの手動キャプチャーを使用する実装、 Naver Pay の決済方法を処理するコード、部分的なキャプチャーやキャンセルのワークフローを持つアプリケーションに影響します。

対応方法

部分的なキャプチャーやキャンセル後に返金が必要な場合は、明示的に返金を作成するコードを追加してください。 Interac カードの手動キャプチャーを使用している場合は、自動キャプチャーフローに移行してください。 Naver Pay 決済処理を更新し、作成時に正確な情報を設定するようにしてください。

9 Payment Element のデフォルトレイアウト更新

Payment Element のデフォルトのレイアウトは、 tabs ではなく accordion として表示されるようになりました。また、defaultCollapsed 値を未定義のままにする動作も更新され、複数の支払い方法が表示されたときに折りたたまれるようになりました。 Payment Element を利用した 決済フォームの UI が変更される可能性があるため、レイアウトを指定していない場合や、カスタムスタイリングを行っている場合は対応が必要です。

対応方法

Payment Element にて、レイアウトプロパティを明示的に設定しましょう。現在の挙動を維持したい場合は、 tabs を設定することをお勧めします。

10 Connect で、 Person オブジェクトの政治的に重要な公人のプロパティ変更

Person オブジェクトの政治的に重要な公人のプロパティpolitical_exposure）が文字列から列挙型に変更されました。より構造化されたデータ形式になり、正確な情報が提供されるようになりました。

段階的移行のためのロードマップ

テスト環境での検証

まずは Workbench を利用して、現在の API バージョンを確認してください。 その後、対応する SDK バージョンを最新版にアップグレードしてください。 SDK を使用していない場合は、APIリクエストに Stripe-Version: 2025-03-31.basil を含めるようにします。 また、Webhookを利用している場合は、WebhookのAPIバージョンも更新しましょう。

バージョンの更新が完了しましたら、テスト環境で統合テストを実施してください。特に破壊的変更の影響を受ける部分を重点的にテストしてください。 テスト方法の詳細

本番環境へのアップグレード実施

公式ドキュメント:アップグレード実行方法
公式ドキュメント:バージョンロールバック方法

Workbench でアップグレードを実行してください。 72 時間以内であれば、問題が発生した場合に、バージョンをロールバック可能ですので、リリース時のロールバック計画も用意しておきましょう。

監視と対応

アップグレード後、システムを注意深く監視し、予期しない問題が発生していないか確認してください。ワークベンチを利用して、エラー数が増加していないかをチェックすることをお勧めします。

まとめ

Stripe の 「Basil」 バージョンへのアップグレードには、多数の破壊的変更が含まれているため、十分な準備と計画が必要です。特に請求関連の機能（従量課金、請求書プレビュー、サブスクリプション管理）に大きな変更があるため、これらの機能を使用しているアプリケーションは特に注意が必要です。

このガイドで解説した各変更点を理解し、適切な対応策を実施することで、スムーズな移行が可能になります。テスト環境での十分な検証を行い、問題がないことを確認した上で本番環境に適用してください。

Stripe では、バージョンアップグレード後72時間以内であれば、問題が発生した場合にロールバックが可能です。この期間を利用して、アップグレード後のシステムの動作を十分に監視し、問題が発生した場合には迅速に対応することをお勧めします。

よくある質問

Q: API バージョンの移行はどのくらいの期間を見込むべきですか？

A: 変更の影響範囲によりますが、一般的には計画と実装に2〜4週間、テストに1〜2週間を見込むことをお勧めします。特に請求関連の機能を多用している場合は、より長い期間が必要になる可能性があります。

Q: 古い API バージョンはいつまでサポートされますか？

A: Stripe は通常、新しいバージョンがリリースされてから一定期間は古いバージョンをサポートしますが、早めの移行を強くお勧めします。具体的なサポート終了日は Stripe から通知されますが、新機能や改善点を活用するためにも、できるだけ早く移行するのが賢明です。

Q: 移行中にサービス停止は発生しますか？

A: 適切な計画と実装を行えば、サービス停止なしで移行することが可能です。特にテスト環境での十分な検証と、段階的な移行アプローチが重要です。ただし、重要な決済処理を行う時間帯を避けてアップグレードを実施することをお勧めします。

Stripeを活用したオンライン決済システム導入をサポートします

株式会社デジタルキューブは Stripe 公式パートナーとして、自社サービス開発で培った経験を活かし、Stripe を用いた決済システムの導入を支援します。多言語対応の決済フォーム実装、モバイル支払い対応、柔軟な従量課金システム構築など、ユースケースに合わせた活用方法の提案から、専用ダッシュボードの開発まで幅広くサポートします。

SaaS ダッシュボード開発や EC サイトへの Stripe 決済導入など、様々な導入実績があります。API の呼び出しだけで決済機能を実装できる Stripe の利点を最大限に活かしたシステム構築をお手伝いします。

Stripe導入支援サービスの詳細はこちら

著者プロフィール ： 岡本 秀高

DigitalCube の BizDev。EC ASP の開発や Stripe の Developer Advocate としての経験を元に、SaaS や EC サイトの収益を増やすための方法・生成 AI を使った効率化や新しい事業モデルの模索などに挑戦する。

Recommend Articles

おすすめの記事

このカテゴリの記事一覧を見る