# サブスクリプションの仕組み

継続支払いとサブスクリプションのライフサイクルを管理します。

顧客はサブスクにより継続課金を行い、プロダクトやサービスにアクセスできます。サブスクを作成すると、Stripe により自動的に請求書が生成され、決済の回収が試行され、ライフサイクル全体にわたりサブスクのステータスが管理されます。サブスクは、作成からキャンセルまで、予測可能な一連の状態を経て移行します。

1 回限りの決済とは異なり、サブスクでは今後の請求サイクルのために顧客と決済手段の情報を保存する必要があります。Stripe は決済の再試行ロジック、督促、ステータスの移行を処理します。

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

以下のサブスクの各ライフサイクルフェーズは、[Subscription オブジェクト](https://docs.stripe.com/api/subscriptions/object.md)のステータス変更にマッピングされます。これらのステータスを理解することで、アクセスのプロビジョニング、顧客への通知、エラーの処理を行うタイミングを把握できます。ステータス間の移行の監視および処理には、[Webhook イベント](https://docs.stripe.com/billing/subscriptions/webhooks.md#state-changes)を使用できます。

### 定期支払いを作成する

[ダッシュボード](https://dashboard.stripe.com/subscriptions?status=active)または [Subscriptions API](https://docs.stripe.com/api/subscriptions/create.md) で新しいサブスクを作成します。生成される [Subscription オブジェクト](https://docs.stripe.com/api/subscriptions/object.md)には、登録された顧客、[プロダクト](https://docs.stripe.com/api/products.md)、[価格](https://docs.stripe.com/api/prices/object.md)、およびサブスクの現在のライフサイクル状態を反映する `status` が含まれます。

即時決済が必要なサブスクを作成すると、Stripe は [Invoice](https://docs.stripe.com/billing/invoices/subscription.md) および [PaymentIntent](https://docs.stripe.com/payments/payment-intents.md) も作成します。サブスクの初期ステータスは `incomplete` であり、顧客が最初の請求書を支払った後に `active` になります。

サブスクの決済の回収と失敗処理のデフォルトは、決済手段によって異なります。API では、サブスクの [payment_behavior](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-payment_behavior) を設定して、デフォルトを上書きできます。

サブスクの初回の請求を遅らせるために[トライアル期間](https://docs.stripe.com/billing/subscriptions/trials.md)を作成した場合、初期ステータスは `trialing` となり、トライアルが終了して決済が成功すると、サブスクは自動的に `active` に移行します。

### 請求書を処理する

`collection_method` が `charge_automatically` に設定されているサブスクの場合、サブスクの作成時に Stripe はステータスが `open` の[請求書](https://docs.stripe.com/billing/invoices/subscription.md)を作成します。顧客の支払い期限は 23 時間です。この期間中、サブスクのステータスは `incomplete` となり、請求書のステータスは `open` のままです。この 23 時間の期間は、*オンセッション* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method) で支払いを行う顧客に対応するものです。23 時間経過後に顧客がアプリケーションに戻ってきた場合は、その顧客に新しいサブスクを作成してください。

`collection_method` が `send_invoice` に設定されているサブスクの場合、Stripe は設定可能な期日を含む請求書へのリンクを顧客にメールで送信します。サブスクは、顧客が支払いを行うまで `incomplete` のままになります。

詳細については、[サブスクの請求書](https://docs.stripe.com/billing/invoices/subscription.md)をご覧ください。

### 決済を確認

顧客が請求書を支払うと、サブスクは `active` に、請求書は `paid` に更新されます。[invoice.paid](https://docs.stripe.com/billing/subscriptions/webhooks.md#events) イベントをリッスンするか、サブスクのステータスが `active` であることを確認してください。

顧客が 23 時間以内に支払いを行わない場合、サブスクは `incomplete_expired` に更新され、請求書は `void` になります。アクセスを再開するには、新しいサブスクを作成してください。

詳細については、[サブスクリプションステータス](https://docs.stripe.com/billing/subscriptions/overview.md#subscription-statuses)と[決済ステータス](https://docs.stripe.com/billing/subscriptions/overview.md#payment-status)をご覧ください。

### 商品へのアクセスを提供する

サブスクが `active` になると、Stripe は登録されたプロダクトに関連付けられている各機能の有効な[エンタイトルメント](https://docs.stripe.com/billing/entitlements.md)を作成します。顧客がサービスにアクセスした際に、その有効なエンタイトルメントを使用して、サブスクに含まれる機能へのアクセスを許可します。

あるいは、Webhook イベントで[有効なサブスクリプションを追跡](https://docs.stripe.com/billing/subscriptions/webhooks.md#active-subscriptions)し、そのアクティビティに基づいて顧客向けに商品をプロビジョニングします。

### サブスクリプションを更新する

[既存のサブスクリプション](https://docs.stripe.com/billing/subscriptions/change.md)は、キャンセルして再作成することなく、必要に応じて変更できます。最も重要な変更には、サブスクリプション価格の[アップグレードやダウングレード](https://docs.stripe.com/billing/subscriptions/change-price.md)、有効なサブスクリプションの[決済回収](https://docs.stripe.com/billing/subscriptions/pause-payment.md)の一時停止などがあります。

[Stripe Checkout](https://docs.stripe.com/payments/checkout.md) の組み込みでは、セッションのサブスクリプションが `incomplete` 場合、サブスクリプションまたはその請求書を更新できません。[checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) イベントをリッスンして、セッションの完了後に更新を行うことができます。セッションのサブスクリプションをキャンセルしたり、サブスクリプションの請求書を無効にしたり、請求書を回収不能としてマークしたりする場合は、代わりに[セッションを期限切れにする](https://docs.stripe.com/api/checkout/sessions/expire.md)こともできます。

### 未払いのサブスクリプションを処理する

顧客がサブスクの請求書を支払わない場合、Stripe は以降の回収試行を一時停止します。サブスクは請求期間ごとに請求書を生成し続けますが、これらは `draft` ステータスのままになります。サブスクのステータス (`past_due` または `unpaid`) は、ダッシュボードの[決済の失敗に対する設定](https://dashboard.stripe.com/settings/billing/automatic)によって異なります。

Stripe はサブスクのステータスを決定する際に無効化された請求書を無視し、代わりに無効化されていない最新の請求書を使用します。

詳細については、[失敗したサブスクの決済](https://docs.stripe.com/billing/collection-method.md#failed-subscription-payments)をご覧ください。

### サブスクリプションをキャンセルする

サブスクリプションは、[請求期間の終了時](https://docs.stripe.com/billing/subscriptions/cancel.md#cancel-at-the-end-of-the-current-billing-period)や[設定した請求期間回数](https://docs.stripe.com/billing/subscriptions/cancel.md#subscription-schedules)の経過後など、いつでも[キャンセル](https://docs.stripe.com/billing/subscriptions/cancel.md)できます。

デフォルトでは、サブスクリプションを解約すると、新しい請求書の作成が無効になり、サブスクリプションに関するすべての未払い請求書の[自動回収が停止](https://docs.stripe.com/billing/subscriptions/cancel.md#handle-invoice-items-when-canceling-subscriptions)されます。また、サブスクリプションが削除され、[metadata](https://docs.stripe.com/metadata.md) と `cancellation_details` を除いて更新できなくなります。顧客が再度サブスクリプションを申し込む場合は、新しい決済情報を収集し、新しいサブスクリプションを作成する必要があります。

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

サブスクリプションには次のステータスがあります。サブスクリプションに対して実行できるアクションは、ステータスによって異なります。

| ステータス | 説明 |
| --- | --- |
| `trialing` | サブスクリプションは現在トライアル期間中であり、顧客にプロダクトを支障なく提供できます。初回の支払いが行われると、サブスクリプションは自動的に `active` に移行します。 |
| `active` | サブスクリプションの状態は良好です。`past_due` のサブスクリプションでは、関連する最新の請求書を支払うか、回収不可としてマークすると、サブスクリプションが `active` に移行します。`active` は、サブスクリプションに関連するすべての未払いの請求書が支払われたことを示すものではない点に注意してください。その他の未払いの請求書は、支払い待ちのまま残すことも、回収不可としてマークすることも、必要に応じて無効にすることもできます。 |
| `incomplete` | サブスクリプションを有効にするには、顧客が 23 時間以内に支払いを成功させる必要があります。または、支払いで顧客認証などの[対応が必要](https://docs.stripe.com/billing/subscriptions/overview.md#requires-action)です。保留中の支払いがあり、PaymentIntent のステータスが `processing` の場合も、サブスクリプションが `incomplete` になることがあります。 |
| `incomplete_expired` | サブスクリプションの初回の支払いが失敗し、サブスクリプションの作成から 23 時間以内に支払いが成功しませんでした。これらのサブスクリプションは顧客に請求されません。このステータスは、サブスクリプションの有効化に失敗した顧客を追跡するために存在します。 |
| `past_due` | 最新の *確定済み* の請求書の決済は、失敗したか、試行されていません。サブスクリプションは、引き続き請求書を作成します。ダッシュボードの [subscription settings](https://dashboard.stripe.com/settings/billing/automatic) によって、サブスクリプションの次のステータスが決まります。[smart retries](https://docs.stripe.com/billing/revenue-recovery/smart-retries.md) を試行しても請求書が未払いの場合は、サブスクリプションを `canceled`、`unpaid`、または `past_due` のままにするように設定できます。サブスクリプションを再度有効にするには、顧客に最新の請求書を決済してもらいます。サブスクリプションのステータスは、決済が最新の請求書より前に行われたか、最新の請求書の期日を過ぎたかに関係なく、`active` になります。 |
| `canceled` | サブスクリプションがキャンセルされました。キャンセル時に未払いのすべての請求書の自動回収が無効化されます (`auto_advance=false`)。これは、更新できない最終的なステータスです。 |
| `unpaid` | 最新の請求書は支払われていませんが、サブスクリプションはそのまま保持されます。最新の請求書は未処理のままになり、請求書は引き続き生成されますが、支払いの試行は行われません。サブスクリプションが `unpaid` の場合は、`past_due` の時点で支払いの試行と再試行がすでに行われているため、プロダクトへのアクセスを取り消します。サブスクリプションのステータスを `active` にするには、期日前に最新の請求書を支払う必要があります。 |
| `paused` | サブスクリプションはデフォルトの決済手段なしでトライアル期間が終了し、[trial_settings.end_behavior.missing_payment_method](https://docs.stripe.com/billing/subscriptions/trials/free-trials.md#create-free-trials-without-payment) が `pause` に設定されています。サブスクリプションの請求書は作成されなくなりました。顧客にデフォルトの決済手段を関連付けた後で、[サブスクリプションを再開](https://docs.stripe.com/billing/subscriptions/trials/free-trials.md#resume-a-paused-subscription)できます。 |

## 決済ステータス

[PaymentIntent](https://docs.stripe.com/payments/payment-intents.md) は、すべての決済のライフサイクルを追跡します。サブスクリプションの決済期日になると、Stripe は[請求書](https://docs.stripe.com/billing/invoices/subscription.md)と PaymentIntent を生成します。PaymentIntent ID は請求書に関連付けられ、請求書オブジェクトとサブスクリプションオブジェクトからアクセスできます。

PaymentIntent のステータスは、請求書とサブスクリプションのステータスに影響を与えます。決済のさまざまな結果が、さまざまなステータスにどのようにマッピングされるかを以下に示します。

| 支払い結果 | PaymentIntent ステータス | 請求書のステータス | サブスクリプションのステータス |
| --- | --- | --- | --- |
| 成功 | `succeeded` | `paid` | `active` |
| カードエラーによる失敗 | `requires_payment_method` | `open` | `incomplete` |
| 認証による失敗 | `requires_action` | `open` | `incomplete` |

ACH Direct Debit などの非同期決済手段は、サブスクリプションステータスの移行を即時決済手段とは異なる方法で処理します。非同期決済手段を使用する場合、サブスクリプションは作成後に直接 `有効` に移行し、`未完了` をバイパスできます。後で決済が失敗した場合、Stripe は請求書を無効にしますが、サブスクリプションは `有効な` ままになります。アクセス制御と再試行ロジックを設計する際には、この動作を使用します。

以降のセクションでは、これらのステータスと、各ステータスに対するアクションを説明します。

### 支払いの成功

顧客の決済が成功した場合:

- PaymentIntent の `status` は `succeeded` に移行します。
- サブスクリプションの `status` は `active` です。
- 請求書の `status` は `paid` です。
- 設定済みの Webhook エンドポイントに Stripe が `invoice.paid` イベントを送信します。

処理期間が長い[決済手段](https://docs.stripe.com/payments/payment-methods/integration-options.md)では、サブスクリプションは直ちに有効になります。このような場合、決済が成功するまで、PaymentIntent のステータスは `processing` サブスクリプションに対して `active` である可能性があります。

サブスクリプションが有効になったので、商品への[アクセスを提供](https://docs.stripe.com/billing/subscriptions/overview.md#provision-access)します。

### 支払い方法が必要

支払い拒否などの[カードエラー](https://docs.stripe.com/api/errors.md#errors-card_error)が原因で[決済](https://docs.stripe.com/declines.md#issuer-declines)が失敗した場合:

- PaymentIntent の `status` は `requires_payment_method` です。
- サブスクリプションの `status` は `incomplete` です。
- 請求書の `status` は `open` です。

これらのシナリオを処理するには、以下のステップに従います。

- 顧客に通知します。
- 新しい決済情報を徴収し、[PaymentIntent を確定](https://docs.stripe.com/api/payment_intents/confirm.md)します。
- サブスクリプションの [default payment method (デフォルトの支払い方法)](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-default_payment_method) を更新します。
- Stripe は [Smart Retries](https://docs.stripe.com/invoicing/automatic-collection.md#smart-retries) を使用するか、カスタム [リトライルール](https://dashboard.stripe.com/account/billing/automatic) に基づいて決済を再試行します。
- [invoice.payment_failed](https://docs.stripe.com/billing/revenue-recovery/smart-retries.md#invoice-payment-failed-webhook) イベントを使用して、サブスクリプション決済失敗イベントを監視し、更新を再試行します。請求書の決済試行後、その [next_payment_attempt](https://docs.stripe.com/api.md#invoice_object-next_payment_attempt) 値はダッシュボードの現在のサブスクリプション設定を使用して設定されます。

[サブスクリプションの支払い失敗を処理](https://docs.stripe.com/billing/subscriptions/webhooks.md#payment-failures)する方法は以下のとおりです。

### アクションが必要

一部の決済手段では、[3D セキュア認証](https://docs.stripe.com/payments/3d-secure.md) (3DS) による顧客認証が必要です。認証が必要かどうかは、[Radar ルール](https://docs.stripe.com/payments/3d-secure/authentication-flow.md#three-ds-radar)とカード発行会社によって異なります。

顧客が決済を認証する必要があるために決済が失敗した場合:

- PaymentIntent の `status` は `requires_action` です。
- サブスクリプションの `status` は `incomplete` です。
- 請求書の `status` は `open` です。

これらのシナリオを処理するには、以下のステップに従います。

- [Webhook エンドポイント](https://docs.stripe.com/billing/subscriptions/webhooks.md)を使用して `invoice.payment_action_required` イベントの通知を監視します。これには認証が必要です。
- 認証が必要であることを顧客に通知します。
- PaymentIntent のクライアントシークレットを取得し、それを[stripe.ConfirmCardPayment](https://docs.stripe.com/js/payment_intents/confirm_card_payment) の呼び出しに渡します。これで顧客に認証モーダルが表示されるようになり、決済が行われると、モーダルが閉じてコンテキストがアプリケーションに戻されます。
- イベントの送信先で `invoice.paid` イベントをモニタリングし、支払いが成功したことを確認します。ユーザーは、`confirmCardPayment()` が完了する前にアプリケーションを離れることができます。支払いが成功したかどうかを確認することで、商品を正しく提供できます。

## See also

- [サブスクリプションの導入を設計](https://docs.stripe.com/billing/subscriptions/design-an-integration.md)
- [サブスクの実装を構築する](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md)
- [サブスクリプションクイックスタート](https://docs.stripe.com/billing/quickstart.md)