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

このページでは、サブスクリプションがライフサイクルをどのように進行するか、請求期間と更新がどのように計算されるか、そして支払いの失敗がどのように処理されるかを説明します。

ステータス

canceled と expired はどちらも終端状態ですが、意味は異なります。canceled は消費者に代わって加盟店が行う意図的な解約であるのに対し、expired は支払いの失敗を反映したものです。独自の解約分析ではこれらを区別してください。

請求期間

有効なサブスクリプションには currentBillingPeriodEnd タイムスタンプがあり、トライアル中のサブスクリプションには trialEnd タイムスタンプもあります。

• 間隔：unit（WEEK、MONTH、または YEAR）と count（更新間隔の単位数）を持つオブジェクトです。月次・年次の期間は、サブスクリプションの請求基準日（最初の課金成功日）と同じ日に繰り上がります。基準日が対象の月に存在しない場合はその月の末日（例：31日を基準とする場合、より短い月では30日や28日・29日）に繰り上がります。
• 更新：現在の請求期間の終了時に Tokenz によって管理されます。

トライアル期間

サブスクリプション作成時に trialPeriodDays（1〜365）を設定すると、チェックアウト時点では初期注文は作成されません。代わりに次のように進みます。

1. 消費者がカード情報を入力してトライアルを開始します。Tokenz は決済ネットワークに支払いの同意を登録します — 詳細は 決済方法と同意 をご覧ください。
2. サブスクリプションは trialing に移行し、subscription.trial_started の Webhook が送信されます。
3. トライアルが trialEnd に達すると、注文が作成され、保存済みのカードで課金されます。成功すると、サブスクリプションは active になり、subscription.activated の Webhook が送信されます。

トライアル期間が設定されていない場合、初期注文はチェックアウト時に作成・課金され、認証が成功すると同時にサブスクリプションは直ちに active になります。

督促（支払い失敗からの回復）

各サブスクリプションは、予定されている課金が失敗した場合の対応を制御する督促戦略とともに作成されます。

• RETRY（デフォルト）：未払いの注文は、注文の有効期限（dunningExpireAfterHours、デフォルト24時間）が経過するまでの間に、最大 dunningMaxAttempts 回（デフォルト3回）再試行されます。消費者にはメールで復旧用のチェックアウトリンクも送信され、必要に応じてカードを更新できます。再試行が成功すると、サブスクリプションは active に戻ります。すべての再試行が失敗して注文が期限切れになると、サブスクリプションは expired になります。
• CANCEL_IMMEDIATELY：最初の課金失敗で即座にサブスクリプションが失効します — 再試行の猶予期間はありません。

注： unpaid から active への復旧は、元の請求期間をずらすものではありません。次回の更新は、復旧日ではなく元の基準日から引き続きスケジュールされます。

解約

サブスクリプションは、trialing・active・unpaid のいずれかの状態であれば、加盟店が消費者に代わって解約できます。解約すると：

• canceledAt が設定され、以降の更新注文の生成が無効になります
• サブスクリプションの進行中の注文（例：支払い待ちの注文）がキャンセルされます
• subscription.canceled の Webhook が送信されます

解約は最終的なものであり、現時点では解約済みのサブスクリプションを再開する方法はありません。消費者は新しいサブスクリプションを開始する必要があります。

更新リマインダー

一部の地域では、特定の課金（例：トライアルから本課金への移行前や、年次更新の前）について事前通知が規制で義務付けられている場合があります。その場合、Tokenz が自動的に通知を送信します。