サブスクリプションを一時停止する非公開プレビュー

サブスクリプションを一時停止すると、サービスの提供と請求書の生成の両方を一時的に停止できます。サブスクリプションの一時停止機能は、休暇、一時的な使用停止、顧客維持のための猶予期間など、顧客のさまざまなシナリオをサポートし、離脱防止に役立ちます。

To use the Pause subscription endpoint, the subscription must use flexible billing mode.

現在、サブスクリプションでサポートされている他の類似の一時停止動作には、以下のものがあります。

• 決済回収の一時停止: 決済回収を一時停止しても、請求書は生成されます。
• 決済手段なしの無料トライアル終了時の一時停止: トライアル終了時の一時停止は、より真の一時停止のように動作しますが、特定のシステムトリガーのシナリオにのみ適用されます。

サブスクリプションを一時停止できる機能は、以下の点で有用です。

• サブスクリプションをキャンセルすることなく、サブスクリプションのライフサイクルを API で制御したい加盟店チーム。
• 顧客維持フローや真の一時停止状態を必要とするサポートツールを構築するバックエンドエンジニア。
• 開発者が一時停止したウィンドウに対して請求、権利取り消し、Webhook の処理を検証しています。

サブスクリプションを一時停止する

サブスクリプション一時停止エンドポイント を使用して、サブスクリプションを一時停止できます。一時停止は即時に有効になります。サブスクリプションが一時停止されると、次のようになります。

• サブスクリプションのステータスは paused に更新されます。
• ステータス変更に関する通知は、customer.subscription.resumed、customer.subscription.updated、entitlements.active_entitlement_summary.updated の各 Webhook を介して受け取ることができ、それに応じてサービス提供を再プロビジョニングできます。
• 請求書の生成は一時停止中ずっと停止されますが、既存のサブスクリプション請求書は一時停止状態に影響を与えずに処理が進められます。
• current_period_end は、サブスクリプションを一時停止した時刻に更新されます。
• bill_for パラメーターを使用して、未使用のライセンス時間に対するクレジットの比例配分や、現在の従量ベースの使用量に対するデビットの作成など、一時停止時の請求動作を制御できます。請求書を即座に発行することも、保留中の請求書の項目を作成することも可能です。

以下の場合、サブスクリプションを一時停止することはできません。

• send_invoice 回収を使用
• 請求モード classic を使用している場合
• 試用期間中である、試用オファーが添付されている、またはキャンセルされている場合
• スケジュールが添付されている場合
• ケイデンスが添付されている場合

同様に、一時停止したサブスクリプションにスケジュールやケイデンスを添付することはできません。

クーポンを使用してサブスクリプションを一時停止した場合であっても、そのクーポンは元の有効性を保持し、一時停止によって期間が延長されることはありません。

この例は、API を使用してアクティブなサブスクリプションを即座に一時停止する方法を示しています。

curl https://api.stripe.com/v1/subscriptions/sub_1234567890/pause \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: preview" \
  -d type=subscription \
  -d "bill_for[unused_time_from][type]"=now \
  -d "bill_for[outstanding_usage_through][type]"=now \
  -d invoicing_behavior=pending_invoice_item

サブスクリプションの一時停止はカスタマーポータルに反映されますが、サブスクリプション登録者自身がサブスクリプションを一時停止することはできません。

サブスクリプションを再開する

API を使用して手動でサブスクリプションを再開する必要があります。再開は、charge_automatically 回収を使用するサブスクリプションでしか利用できません。再開しても請求書が生成されない場合、サブスクリプションのステータスは即座に active に更新されます。請求書が生成される場合、Stripe は請求書を即座に確定しますが、リクエスト内で支払いは試行しません。請求書支払いエンドポイント を使用して手動で支払いを試行する必要があります。

• 決済が成功すると、サブスクリプションのステータスが active に更新されます。
• 決済に失敗した場合、サブスクリプションのステータスは past_due に更新されます。
• 23 時間以内に決済が行われなかった場合、請求書は無効になり、サブスクリプションのステータスは paused されたままになります。

サブスクリプションのステータスが active に更新された後:

• 請求書の発行が再開されます。
• 請求サイクルアンカーはオプションでリセットされます。
• ステータス変更に関する通知は、customer.Subscription.resumed、customer.Subscription.updated、entitlements.active_entitlement_summary.updated という各 Webhook で受け取り、それに応じてサービス提供を再プロビジョニングすることができます。

この例は、API を使用して一時停止中のサブスクリプションを即座に再開する方法を示しています。

curl https://api.stripe.com/v1/subscriptions/sub_1234567890/resume \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: preview" \
  -d billing_cycle_anchor=unchanged \
  -d proration_behavior=create_prorations

一時停止イベントと再開イベントを特定する

Stripe は、一時停止および再開されたサブスクリプションについて、以下のイベントを送信します。

customer.subscription.paused の Webhook ペイロードの例 (主要フィールドを表示):

{
  "id": "evt_1SrpXjRnJ89Z4rKkFxe9waAz",
  "object": "event",
  ...
  "data": {
    "object": {
      "id": "sub_1SrpWtRnJ89Z4rKknfSwXkBc",
      "object": "subscription",
      ...
      "latest_invoice": "in_1SrpWtRnJ89Z4rKkzYBCF1MY",
      ...
      "status": "paused",
      ...
    }
  },
  ...
  "type": "customer.subscription.paused"
}