Closed4

Stripe Subscription のライフサイクルを理解する

Daigo WakabayashiDaigo Wakabayashi

Subscription の状態遷移

Subscription の status 一覧

ステータス 説明
trialing The subscription is currently in a trial period and it’s safe to provision your product for your customer. The subscription transitions automatically to active when the first payment is made.
active The subscription is in good standing and the most recent payment is successful. It’s safe to provision your product for your customer.
incomplete A successful payment needs to be made within 23 hours to activate the subscription. Or the payment requires action, like customer authentication. Read more about payments that require action. Subscriptions can also be incomplete if there’s a pending payment. In that case, the invoice status would be open_payment_pending and the PaymentIntent status would be processing.
incomplete_expired The initial payment on the subscription failed and no successful payment was made within 23 hours of creating the subscription. These subscriptions don’t bill customers. This status exists so you can track customers that failed to activate their subscriptions.
past_due Payment on the latest finalized invoice either failed or wasn’t attempted. The subscription continues to create invoices. Your subscription settings determine the subscription’s next state. If the invoice is still unpaid after all Smart Retries have been attempted, you can configure the subscription to move to canceled, unpaid, or leave it as past_due. To move the subscription to active, pay the most recent invoice before its due date.
canceled The subscription has been canceled. During cancellation, automatic collection for all unpaid invoices is disabled (auto_advance=false). This is a terminal state that can’t be updated.
unpaid The latest invoice hasn’t been paid but the subscription remains in place. The latest invoice remains open and invoices continue to be generated but payments aren’t attempted. You should revoke access to your product when the subscription is unpaid since payments were already attempted and retried when it was past_due. To move the subscription to active, pay the most recent invoice before its due date.

https://stripe.com/docs/billing/subscriptions/overview#subscription-statuses

推奨されている Subscription 管理フロー

  1. Subscription が作成される。Subscription のステータスは incomplete。（payment_behavior を特に指定せずに作成した場合は active ）
  2. Subscription の invoice （請求書）が作成される。invoice の status が open になる。
  3. 顧客が最初の支払いを行う。
  4. 決済が成功した場合
    • Subscription.status が active になる
    • Invoice.status が paid になる
    • webhook の invoice.paid イベントが送信される
  5. サービスへのアクセスを提供する。決済の成功可否を確認する方法は以下。
    • Webhookのエンドポイントを設定し、invoice.paidイベントをリッスンする
    • 手動で Subscription.status=active かどうかチェックする（ポーリング等）
Daigo WakabayashiDaigo Wakabayashi

payment_behavior について

以下の 4 つ。

  • default_incomplete（デフォルトではコレ）
  • allow_incomplete
  • error_if_incomplete
  • pending_if_incomplete

それぞれ調べていく。

default_incomplete

  • 最初の請求（invoice）が失敗しても、Subscription は作成される
  • 23時間以内に 決済のリトライに成功しなかった場合、Subscription は期限切れ（ status=incomplete_expired）のステータスになる

default_incomplete を使用すると、最初の請求書に支払いが必要な場合に status=incomplete のサブスクリプションを作成し、それ以外の場合は active として開始します。
23時間以内に支払い意思が確認されない場合、サブスクリプションはstatus=incomplete_expiredに移行し、これはターミナル状態です。

allow_incomplete

  • 最初の請求（invoice）が失敗しても、Subscription は作成される
  • default_incompleteのように期限切れにはならず、請求が失敗したサブスクは incomplete 状態で保持される
  • 決済エラーも含めて全てマネジメントする場合にコレを選ぶ

allow_incompleteを使用すると、最初の請求書の支払いができない場合、status=incompleteのサブスクリプションを作成することができます。このステータスでサブスクリプションを作成すると、サブスクリプションの請求書を支払うために追加のユーザーアクションが必要なシナリオを管理できます。

error_if_incomplete

  • 最初の請求（invoice）に失敗すると、402 エラーが返される
  • 2019-03-14以前のAPIバージョンではデフォルトの動作（ChangeLog）

サブスクリプションの最初の請求書を支払うことができない時に、StripeにHTTP 402ステータスコードを返させたい場合は、error_if_incompleteを使用します。
これは、2019-03-14以前のAPIバージョンではデフォルトの動作でした。詳しくは変更履歴をご覧ください。

pending_if_incomplete

  • サブスクの更新（subscription.update）時に指定することができる
  • 例えば、作成時に選んでいた金額からアップグレードしたりする際は、このパラメータを指定できる
  • 参考

pending_if_incomplete は、保留中の更新を使用してサブスクリプションを更新するために使用します。pending_if_incomplete を使用する場合、保留中の更新でサポートされるパラメータのみを渡すことができます。

https://stripe.com/docs/api/subscriptions/create#create_subscription-payment_behavior

このスクラップは2022/05/06にクローズされました