--- title: "サブスクリプションのライフサイクルと請求" description: "このページでは、サブスクリプションがライフサイクルをどのように進行するか、請求期間と更新がどのように計算されるか、そして支払いの失敗がどのように処理されるかを説明します。" source: "https://docs.tokenz.one/ja/v3/subscriptions/lifecycle" api_version: "v3" locale: "ja" version_status: "current" docs_stage: "prod" --- # サブスクリプションのライフサイクルと請求 このページでは、サブスクリプションがライフサイクルをどのように進行するか、請求期間と更新がどのように計算されるか、そして支払いの失敗がどのように処理されるかを説明します。 ## ステータス | ステータス | 意味 | | --- | --- | | `created` | サブスクリプションは作成されましたが、まだ消費者による認証が行われていません。 | | `trialing` | 消費者はトライアル期間中です。まだ課金は発生していません。 | | `active` | サブスクリプションは通常どおり課金されています。各請求期間の終了時に新しい注文が作成され、自動的に課金されます。 | | `unpaid` | 現在の請求期間の注文の支払いができませんでした。サブスクリプションは督促中で、`active` に復帰するか `expired` として終了します。 | | `canceled` | 加盟店または消費者によって解約されました。終端状態であり、以降の課金は発生しません。 | | `expired` | 支払いを回収できなかったため(初回課金または督促の失敗)、意図せず終了しました。終端状態であり、以降の課金は発生しません。 | `canceled` と `expired` はどちらも終端状態ですが、意味は異なります。`canceled` は加盟店または消費者による意図的な解約であるのに対し、`expired` は支払いの失敗を反映したものです。独自の解約分析ではこれらを区別してください。 ## 請求期間 有効なサブスクリプションには `currentBillingPeriodEnd` タイムスタンプがあり、トライアル中のサブスクリプションには `trialEnd` タイムスタンプもあります。 - **間隔**:`unit`(`WEEK`、`MONTH`、または `YEAR`)と `count`(更新間隔の単位数)を持つオブジェクトです。月次・年次の期間は、サブスクリプションの請求基準日(最初の課金成功日)と同じ日に繰り上がります。基準日が対象の月に存在しない場合はその月の末日(例:31日を基準とする場合、より短い月では30日や28日・29日)に繰り上がります。 - **更新**:現在の請求期間の終了時に Tokenz によって管理されます。 ```mermaid sequenceDiagram; autonumber; participant T as Tokenz; participant PSP as カードネットワーク / PSP; participant W as 加盟店の Webhook ハンドラー; T->>T: 請求期間の更新注文を作成; T->>PSP: 保存済みカードに課金; alt 支払い成功 PSP-->>T: 認証成功; T->>T: 請求期間を進め、サブスクリプションは active のまま; T->>W: webhook: subscription.renewed; else 支払い失敗 PSP-->>T: 拒否; T->>T: サブスクリプションを unpaid にし、督促を開始; T->>W: webhook: subscription.unpaid; end ``` ## トライアル期間 サブスクリプション作成時に `trialPeriodDays`(1〜365)を設定すると、チェックアウト時点では初期注文は作成されません。代わりに次のように進みます。 1. 消費者がカード情報を入力してトライアルを開始します。Tokenz は決済ネットワークに支払いの同意を登録します — 詳細は [決済方法と同意](https://docs.tokenz.one/ja/v3/subscriptions/payment-methods) をご覧ください。 2. サブスクリプションは `trialing` に移行し、`subscription.trial_started` の Webhook が送信されます。 3. トライアルが `trialEnd` に達すると、注文が作成され、保存済みのカードで課金されます。成功すると、サブスクリプションは `active` になり、`subscription.activated` の Webhook が送信されます。 トライアル期間が設定されていない場合、初期注文はチェックアウト時に作成・課金され、認証が成功すると同時にサブスクリプションは直ちに `active` になります。 ## 督促(支払い失敗からの回復) 各サブスクリプションは、予定されている課金が失敗した場合の対応を制御する督促戦略とともに作成されます。 - **`RETRY`**(デフォルト):未払いの注文は、注文の有効期限(`dunningExpireAfterHours`、デフォルト24時間)が経過するまでの間に、最大 `dunningMaxAttempts` 回(デフォルト3回)再試行されます。消費者にはメールで復旧用のチェックアウトリンクも送信され、必要に応じてカードを更新できます。再試行が成功すると、サブスクリプションは `active` に戻ります。すべての再試行が失敗するか注文が期限切れになると、サブスクリプションは `expired` になります。 - **`CANCEL_IMMEDIATELY`**:最初の課金失敗で即座にサブスクリプションが失効します — 再試行の猶予期間はありません。 | フィールド | 説明 | | --- | --- | | `dunningMode` | `RETRY` または `CANCEL_IMMEDIATELY`。デフォルトは `RETRY`。 | | `dunningMaxAttempts` | `dunningMode` が `RETRY` の場合の最大再試行回数。1〜10、デフォルト3。 | | `dunningExpireAfterHours` | `dunningMode` が `RETRY` の場合に未払いの注文が期限切れになるまでの時間。1〜168、デフォルト24。 | > **注:** `unpaid` から `active` への復旧は、元の請求期間をずらすものではありません。次回の更新は、復旧日ではなく元の基準日から引き続きスケジュールされます。 ## 消費者のアクセス権 消費者が支払った内容をどのように提供するかは、サブスクリプションの種類によって異なります。 **期間型**のサブスクリプション(例:プレミアムプラン)では、アクセス権はSubscriptionオブジェクトに含まれます。[サブスクリプションのWebhook](https://docs.tokenz.one/ja/v3/subscriptions/webhooks)と[Subscription API](https://docs.tokenz.one/ja/v3/subscriptions/modification#%E3%82%B5%E3%83%96%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%97%E3%82%B7%E3%83%A7%E3%83%B3%E3%81%AE%E5%8F%96%E5%BE%97)から`provideAccess`と`provideAccessUntil`を読み取ってください。`provideAccess`は、消費者にアクセス権を付与すべきかどうかを示します。`provideAccessUntil`はアクセス権が終了する日時で、アクセス権に期限がない場合や付与されていない場合は含まれません。これらのフィールドに従ってください。`unpaid`への移行や、サブスクリプションが`active`または`trialing`のまま`currentBillingPeriodEnd`を過ぎたことは、それ自体ではアクセス権を取り消す理由になりません。 **アイテム型**のサブスクリプション(例:毎月の通貨購入)では、Tokenzがそのサブスクリプションのために作成する注文に基づいて商品を付与してください。それらの注文については、単発購入と同じ[注文Webhook](https://docs.tokenz.one/ja/v3/order#%E6%B3%A8%E6%96%87webhook)(`order.succeeded`など)を処理します。これらの注文にはそれぞれ`subscriptionId`が含まれます。 ## 解約 サブスクリプションは、`trialing`・`active`・`unpaid` のいずれかの状態であれば、加盟店(Tokenzダッシュボードまたは[APIから直接](https://docs.tokenz.one/ja/v3/subscriptions/modification#%E3%82%B5%E3%83%96%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%97%E3%82%B7%E3%83%A7%E3%83%B3%E3%81%AE%E8%A7%A3%E7%B4%84))または消費者([ホストされた確認画面](https://docs.tokenz.one/ja/v3/subscriptions/modification#%E6%B6%88%E8%B2%BB%E8%80%85%E3%81%AB%E3%82%88%E3%82%8B%E8%A7%A3%E7%B4%84%E3%81%AE%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88))が解約できます。解約すると: - `canceledAt` が設定され、以降の更新注文の生成が無効になります - サブスクリプションの進行中の注文(例:支払い待ちの注文)がキャンセルされます - `subscription.canceled` の Webhook が送信されます 解約は最終的なものであり、現時点では解約済みのサブスクリプションを再開する方法はありません。消費者は新しいサブスクリプションを開始する必要があります。 ## 更新リマインダー 一部の地域では、特定の課金(例:トライアルから本課金への移行前や、年次更新の前)について事前通知が規制で義務付けられている場合があります。その場合、Tokenz が自動的に通知を送信します。