Stripe ステータス・ライフサイクルのメモ

Posted at 2025-03-27

はじめに

前回の Stripe 記事（サンプル「Checkout を使用した構築済みのサブスクリプション」）から随分時間が過ぎてしまいましたが、Stripeのメモです。
Stripe の処理はほぼライフサイクル（ステータス）の管理なので備忘録として投稿します。

請求書のライフサイクル

ステータス	説明	可能なアクション
draft	請求書は使用する準備ができていません。すべての請求書は、開始時には draft ステータスです。	１．請求書の任意の部分を編集する。２．請求書を使用する準備ができたら、そのステータスを open に変更して確定する。３．請求書がサブスクリプションに関連付けられていない場合に、削除する。
open	請求書が確定され、支払いを待っています。	１．支払いのために請求書を顧客に送信する。２．請求書の一部の要素のみを変更する。大幅に変更するには、新しい請求書を作成し、古いものを無効にします。３．請求書のステータスを paid、void、または uncollectible に変更する。
paid	この請求書は支払い済みです。	これ以降のアクションはありません。
void	この請求書はキャンセル済みです。	これ以降のアクションはありません。
uncollectible	請求書への支払いを顧客が行う可能性が低いと思われます。通常、会計処理で回収不能金として処理します。	請求書のステータスを void または paid に変更する。

サブスクリプションのライフサイクル

サブスクリプションを作成します。サブスクリプションの status は incomplete です
(推奨されるフローに従った場合。payment_behavior を指定せずにサブスクリプションを作成した場合、デフォルトの status は active になります)
サブスクリプションの請求書が作成されます。請求書の status は open です
顧客が最初の請求書への支払いを行います
支払いが成功すると、以下のようになります
- サブスクリプションの status が active に移行します
- 請求書の status が paid に設定される
- 設定済みの Webhook エンドポイントに Stripe が invoice.paid イベントを送信します
商品へのアクセスを提供します。以下のようにして、請求書の支払いが行われたかどうかを確認できます
- Webhook エンドポイントまたは別のタイプのイベント送信先を設定し、invoice.paid イベントをリッスンします
- サブスクリプションオブジェクトを手動で確認し、subscription.status=active を探します。自動請求または顧客による手動での支払いによって請求書への支払いが行われると、status は active になります

サブスクリプションステータス

ステータス	説明
trialing	サブスクリプションは現在トライアル期間中であり、顧客にプロダクトを支障なく提供できます。初回の支払いが行われると、サブスクリプションは自動的に active に移行します。
active	サブスクリプションは有効です。期限切れサブスクリプションの場合、最新の関連する請求書を支払うか、または未回収とすることで、サブスクリプションはアクティブに移行します。アクティブは、サブスクリプションに関連するすべての未払いの請求書が支払われたことを示すものではないことに注意してください。他の未払いの請求書は、支払い可能な状態にしておくか、未回収としてマークするか、または無効にすることができます。
incomplete	サブスクリプションを有効にするには、顧客が 23 時間以内に支払いを成功させる必要があります。または、支払いで顧客認証などの対応が必要です。保留中の支払いがあり、PaymentIntent のステータスが processing の場合も、サブスクリプションが incomplete になることがあります。
incomplete_expired	サブスクリプションの初回の支払いが失敗し、サブスクリプションの作成から 23 時間以内に支払いが成功しませんでした。これらのサブスクリプションは顧客に請求されません。このステータスは、サブスクリプションの有効化に失敗した顧客を追跡するために存在します。
past_due	最新の_確定済み_の請求書の支払いが失敗したか、試行されていません。サブスクリプションでは、引き続き請求書が作成されます。サブスクリプションのその後の状態は、サブスクリプションの設定によって決まります。Smart Retries をすべて試行しても請求書が未払いの場合は、サブスクリプションを canceled または unpaid に移行するか、past_due のままにすることができます。サブスクリプションのステータスを active にするには、期日前に最新の請求書を支払う必要があります。
canceled	サブスクリプションがキャンセルされました。キャンセル時に未払いのすべての請求書の自動回収が無効化されます (auto_advance=false)。これは、更新できない最終的なステータスです。
unpaid	最新の請求書は支払われていませんが、サブスクリプションはそのまま保持されます。最新の請求書は未処理のままになり、請求書は引き続き生成されますが、支払いの試行は行われません。サブスクリプションが unpaid の場合は、past_due の時点で支払いの試行と再試行がすでに行われているため、プロダクトへのアクセスを取り消します。サブスクリプションのステータスを active にするには、期日前に最新の請求書を支払う必要があります。
paused	デフォルトの決済手段が設定されずにサブスクリプションのトライアル期間が終了し、trial_settings.end_behavior.missing_payment_method が pause に設定されています。サブスクリプションの請求書は今後作成されなくなります。デフォルトの決済手段を顧客に関連付けた後、サブスクリプションを再開できます。

サブスクリプションイベント

イベント	説明
customer.created	Customer (顧客)の作成に成功すると送信されます。
customer.subscription.created	サブスクリプションが作成されると送信されます。支払いを完了するために顧客の認証が必要な場合、または payment_behavior を default_incomplete に設定した場合、サブスクリプションの status が incomplete になります。詳しくは、サブスクリプションの支払い処理をご覧ください。
customer.subscription.deleted	顧客のサブスクリプションが終了すると送信されます。
customer.subscription.paused	サブスクリプションの status が paused に変わると送信されます。たとえば、支払い方法が指定されないまま無料トライアルが終了した場合に一時停止するようサブスクリプションが設定されている場合に送信されます。サブスクリプションが再開されるまで請求書は作成されません。支払いの回収が一時停止されている場合、その期間中も請求書は引き続き作成されるため、このイベントは送信されません。
customer.subscription.resumed	以前に paused ステータスであったサブスクリプションが再開されると送信されます。支払いの回収の一時停止が解除された場合は、これに該当しません。
customer.subscription.trial_will_end	トライアル期間終了の 3 日前に送信されます。トライアル期間が 3 日未満の場合、このイベントがトリガーされます。
customer.subscription.updated	サブスクリプションが開始または変更された場合に送信されます。たとえば、サブスクリプションの更新、クーポンの追加、割引の適用、請求書アイテムの追加、プランの変更はすべて、このイベントのトリガーとなります。
entitlements.active_entitlement_summary.updated	顧客の有効なエンタイトルメントが更新されると送信されます。このイベントを受け取ると、商品の機能へのアクセスをプロビジョニングまたはデプロビジョニングすることができます。エンタイトルメントの導入の詳細をご覧ください。
invoice.created	新規または更新済みのサブスクリプションに対して請求書が作成されると送信されます。Stripe で invoice.created に対する成功レスポンスを受信できない場合、自動請求で指定されたすべての請求書の確定が最大 72 時間遅延します。詳しくは、請求書の確定をご覧ください。 - Finalize an Invoice (請求書の確定) API にリクエストを送信することで通知に応答します。
invoice.finalized	請求書の確定に成功し、支払いの準備が整うと送信されます。 - 顧客に請求書を送信できます。詳しくは、請求書の確定をご覧ください。 - 設定に応じて、Stripe は自動的にデフォルトの支払い方法に請求するか、回収を試みます。詳しくは、確定後のメールをご覧ください。
invoice.finalization_failed	請求書を確定することができませんでした。ガイドを参照して、請求書の確定失敗を処理する方法をご確認ください。請求書の概要ガイドに記載されている請求書の確定を確認してください。 - Invoice の last_finalization_error を調べて、エラーの原因を判別します。 - Stripe Tax を使用している場合、Invoice オブジェクトの automatic_tax フィールドを確認します。 - automatic_tax[status]=requires_location_inputs の場合、請求書を確定させることはできず、支払いを回収できません。顧客に通知し、必要な顧客の場所を収集します。 - automatic_tax[status]=failed の場合、後でリクエストを再試行します。
invoice.paid	請求書の支払いに成功すると送信されます。このイベントを受け取り、サブスクリプションの status が active になると、商品へのアクセスを提供できます。
invoice.payment_action_required	請求書に顧客の認証を必要とする場合に送信されます。請求書でアクションが必要な場合にサブスクリプションを処理する方法をご紹介します。
invoice.payment_failed	請求書に対する支払いが失敗しました。PaymentIntent のステータスは requires_action に変わります。サブスクリプションのステータスは、サブスクリプションの最初の請求書に対して「のみ」incomplete のままになります。支払いが失敗した場合、以下のような処理を行います。 - 顧客に通知します。サブスクリプションの設定を構成し、Smart Retries とその他の売上回収機能を有効にする方法をご紹介します。 - PaymentIntent を使用している場合、新しい支払情報を収集し、PaymentIntent を確定します。 - サブスクリプションの default payment method (デフォルトの支払い方法) を更新します。
invoice.upcoming	サブスクリプションの更新の数日前に送信されます。何日前に送信されるかについては、ダッシュボードの次回の更新イベントに設定された数値を参照します。既存のサブスクリプションについては、日数の変更は次の請求期間から有効になります。必要に応じて、追加の請求書アイテムを加えることもできます。
invoice.updated	支払いが成功または失敗したときに送信されます。支払いが成功の場合には、paid 属性が true に、status が paid に設定されます。支払いが失敗の場合には、paid が false に、status は open のままになります。また、支払いの失敗は、invoice.payment_failed イベントもトリガーします。
payment_intent.created	PaymentIntent が作成されると送信されます。
payment_intent.succeeded	PaymentIntent が正常に支払いを完了すると送信されます。
subscription_schedule.aborted	サブスクリプションスケジュールが、支払いの滞納により関連するサブスクリプションが終了となったことが原因でキャンセルされた場合に送信されます。
subscription_schedule.canceled	サブスクリプションスケジュールがキャンセルされ、それに関連するアクティブなサブスクリプションもキャンセルされた場合に送信されます。
subscription_schedule.completed	サブスクリプションスケジュールのすべてのフェーズが完了した場合に送信されます。
subscription_schedule.created	新しいサブスクリプションスケジュールが作成された場合に送信されます。
subscription_schedule.expiring	サブスクリプションスケジュールが無効になる 7 日前に送信されます。
subscription_schedule.released	サブスクリプションスケジュールがサブスクリプションからリリースされたとき、または停止され関連付けが解除されたときに送信されます。サブスクリプションはその後も残ります。
subscription_schedule.updated	サブスクリプションスケジュールが更新された場合に送信されます。

サブスクリプション課金イベント

初回課金イベント

customer.created
customer.subscription.created
invoice.created
invoice.finalized
charge.succeeded
invoice.payment_succeeded

自動課金（2回目以降）イベント

invoice.upcoming
invoice.created
invoice.finalized
charge.succeeded
invoice.payment_succeeded

おわりに

改めてまとめてみるといろいろとステータスがありますね。実際に Stripe では Webhook で連携するステータスを Stripe で選択できます。そのため、上記のステータスを全て処理する訳ではないのですが、どの順番で来るなのはコードを記載する時に必要でした。
Stripe はちゃんと毎月バージョンアップをしてくれているので、最新のじょうほうは下記の「参考リンク」をご覧ください。

参考（感謝）

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up