サブスクリプションスケジュール
Subscription schedule (サブスクリプションスケジュール) を使用して、時間の経過とともに発生するサブスクリプションへの変更を自動化します。スケジュールを介してサブスクリプションを直接作成することも、既存のサブスクリプションにスケジュールを追加することもできます。phases 属性を使用して、サブスクリプションに行う変更を定義します。スケジュールのすべてのフェーズが完了すると、end_behavior に基づいてスケジュールが完了します。
スケジュールで必要になる変更には、以下などがあります。
- サブスクリプションを将来の日付から開始する
- サブスクリプションを過去の日付にさかのぼる
- サブスクリプションをアップグレードまたはダウングレードする
サブスクリプションスケジュールは、Stripe Billing ダッシュボードと API の両方で利用可能です。ダッシュボードでのサブスクリプションスケジュールの機能を示す短いビデオをご紹介します。
ダッシュボードでのサブスクリプションスケジュール
このドキュメントの以降の部分では、サブスクリプションのスケジュールについてさらに詳しく説明します。例のリストを確認するには、ユースケースページをご覧ください。
フェーズ
サブスクリプションのスケジュールを作成する際には、Phases (フェーズ) 属性を使用して変更が発生するタイミングと、変更対象のサブスクリプションのプロパティを定義します。たとえば、サブスクリプションの最初の 3 カ月間に 50% 割引のクーポンを提供するとします。このシナリオでは、最初のフェーズが 3 カ月間で、50% オフのクーポンを含むサブスクリプションのスケジュールを作成します。2 番目のフェーズでは、サブスクリプションは通常のコストに戻り、クーポンが削除されます。フェーズは順次的である必要があり、特定の時点でアクティブであるフェーズは 1 つのみになります。
フェーズの長さを設定する
価格の期間によってサブスクリプションの請求頻度が決まります。たとえば、期間が 1 カ月の場合には毎月請求が行われます。フェーズには、iterations 属性があり、これを使用してフェーズの存続期間を指定します。この値に期間を乗じることでフェーズの長さが決定されます。サブスクリプションのスケジュールで、期間が 1 カ月の価格が使用されていて、iterations=2
と設定した場合には、フェーズは 2 カ月間続きます。
1 つのフェーズの end_date
が、次のフェーズの start_date
である必要があります。iterations
を使用すると、自動的に start_date
と end_date
が適切に設定されます。これらの値を手動で設定することもできますが、Stripe では手動設定ではなく iterations
を使用することをお勧めします。手動で開始日と終了日を設定するとエラーが起きやすいため、手動設定の使用は特別なユースケースのみにしてください。
次のフェーズに移行する
フェーズの end_date
に達すると、フェーズの移行が自動的に発生します。フェーズが開始されると、Stripe により、次のフェーズの属性に基づいてサブスクリプションが更新されます。オプションとして、proration (比例配分) を有効にして、プランの未使用のアイテムや時間のクレジットをユーザに提供することもできます。
トライアルを使用する
フェーズにTrial end (トライアルの終了) を設定して、トライアル期間を追加できます。特定のフェーズ全体をトライアルにする場合には、trial_end
の値をフェーズの end_date
と同じにします。また、フェーズの一部のみをトライアルにする場合には、trial_end
を end_date
の前にします。更新をスケジュールする際には、各フェーズに新しい trial_end
を指定する必要があります。
スケジュールを完了する
サブスクリプションのスケジュールは、最後のフェーズが完了すると終了します。この時点で、サブスクリプションはその位置にとどまり、スケジュールとの関連付けはなくなります。スケジュールの最後のフェーズの完了後にサブスクリプションをキャンセルするには、end_behavior を cancel
に設定します。
フェーズ属性の継承
フェーズが有効になると、そのフェーズに設定された属性はすべて、サブスクリプションにも設定されます。そのフェーズが終了すると、次のフェーズによって変更されない限り、またはスケジュールにデフォルト設定がない限り、属性は変化しません。一部の属性はスケジュールとフェーズの両方に設定できます。これには以下が含まれます。
これらの属性の 1 つがスケジュールで定義されている場合、それはすべてのフェーズのデフォルトになります。スケジュールとフェーズの両方で同じプロパティが定義されている場合、フェーズ属性によってスケジュール属性が上書きされます。この動作については、以下で詳しく説明します。
スケジュール属性が存在 | フェーズ属性が存在 | 結果 |
---|---|---|
なし | なし | 顧客またはアカウント設定がデフォルト |
あり | なし | 設定されたスケジュール属性 |
あり | あり | 設定されたフェーズ属性 |
なし | あり | 設定されたフェーズ属性 |
フェーズメタデータを使用する
サブスクリプションスケジュールのフェーズを使用して、基本となるサブスクリプションにメタデータを設定できます。これにより、予定された更新を使用して、サブスクリプションのメタデータを制御できます。
サブスクリプションメタデータをサブスクリプションのインボイスにコピーする方法をご覧ください。
サブスクリプションスケジュールを作成する
ユースケースページにはさらに詳細な例がありますが、顧客を使用してサブスクリプションのスケジュールを作成する基本的な例を以下に紹介します。この方法でスケジュールを作成すると、サブスクリプションも自動的に作成されます。
注
サブスクリプションを直接作成する場合と異なり、collection_method
が charge_automatically
に設定されたサブスクリプション・スケジュールの最初のインボイスは、継続インボイスのように動作し、スケジュールのサブスクリプションが作成された時点でただちに確定「されません」。インボイスは draft
ステータスで開始し、作成の約 1 時間後 に Stripe によって確定されます。
たとえば、start_date=now
に設定した自動請求サブスクリプションのスケジュールを作成すると、draft
ステータスのサブスクリプションとインボイスも作成されます。これにより、 インボイスを編集するために 1 時間が確保されます。その後、確定時における非同期型の支払い試行の結果に基づき、インボイスは 自動的に open
または paid
ステータスに変わります。
このスケジュールでは以下のように設定されます。
- 作成されるとすぐ開始します。
- サブスクリプションが、
price_1GqNdGAJVYItwOKqEHb
で商品のインスタンスに設定されます。 - 12 回の反復を経た後に、サブスクリプションがスケジュールからリリースされます。
サブスクリプション ID を渡してサブスクリプションのスケジュールを作成することもできます。
この方法でスケジュールを作成すると、サブスクリプションの属性を使用してスケジュールの属性が設定されます。
他の Stripe API と同様に、Subscription Schedule (サブスクリプションスケジュール) を取得して更新できます。また、キャンセルしてリリースすることもできます。サブスクリプションのスケジュールをキャンセルすると、サブスクリプションも同様にキャンセルされます。サブスクリプションからスケジュールのみを削除する場合は、release コールを使用します。
コードなしでサブスクリプションスケジュールを作成する
Stripe Billing サブスクリプションエディターで、コードを使用せずに複数フェーズのサブスクリプションスケジュールを作成できます。そのためには、以下のステップを実行します。
- ダッシュボードで、サブスクリプションエディターを開きます。
- 顧客を追加します。
- 商品選択ドロップダウンに価格を追加します。
- サブスクリプションスケジュールの最初のフェーズの期間を設定します。
- + フェーズを追加をクリックします。
- 次のフェーズの期間を選択します。サブスクリプションを継続する場合は無期限を選択します。
- 新しいフェーズに必要な変更を加えます。数量の変更、価格の変更、クーポンの追加または削除、請求サイクル日のリセット、比例配分の動作の変更、メタデータの更新が可能です。フェーズでメタデータを変更すると、そのフェーズが有効になったときにサブスクリプションのメタデータが更新されます。
- 新しいフェーズを保存します。
- 必要に応じて、さらにフェーズを追加します。
- サブスクリプションを作成します。
サブスクリプションスケジュールを更新する
サブスクリプションのスケジュールでは、現在および以降のフェーズのみを更新できます。サブスクリプションのスケジュールを更新する際には、現在および以降のすべてのフェーズを渡す必要があります。また、以前に設定したパラメーターの中で保持するパラメーターも渡す必要があります。以前に設定したパラメーターはすべて、更新リクエストで渡さない限り、既存のフェーズで未設定になります。レスポンスには過去のフェーズに関する情報も含まれます。
現在または以降のフェーズは最大 10 個まで含めることができます。アクティブなフェーズを更新すると、その基礎となるサブスクリプションも同様に更新されます。たとえば、次の呼び出しでは既存の開始日と終了日が維持されますが、quantity
が 2 に更新されます。
現在のフェーズをすぐに終了して、新しいフェーズを開始することもできます。これにより、アクティブなフェーズが過去に移動し、新しいフェーズがサブスクリプションに即座に適用されます。以下の例では、現在のフェーズが終了し、新しいフェーズが開始します。
サブスクリプションのスケジュールにフェーズを追加するには、現在のフェーズを渡し、新しいフェーズを定義します。
コードなしでサブスクリプションスケジュールを更新する
Stripe Billing サブスクリプションエディターを使用して、既存のサブスクリプションを更新し、将来のサブスクリプションスケジュールのフェーズを設定できます。そのためには、以下のステップを実行します。
- ダッシュボードで、サブスクリプションページに移動して、既存のサブスクリプションを選択し、アクション > サブスクリプションを更新をクリックします。
- 終了日を選択して、サブスクリプションスケジュールの現在のフェーズの期間を設定します。
- +フェーズを追加をクリックします。
- 次のフェーズの期間を選択します。サブスクリプションを継続する場合は無期限を選択します。
- 新しいフェーズに必要な変更を加えます。数量の変更、価格の変更、クーポンの追加または削除、請求サイクル日のリセット、比例配分の動作の変更、メタデータの更新が可能です。フェーズでメタデータを変更すると、そのフェーズが有効になったときにサブスクリプションのメタデータが更新されます。
- 新しいフェーズを保存します。
- 必要に応じて、さらにフェーズを追加します。
- サブスクリプションを作成します。
請求書をプレビューする
サブスクリプションスケジュールの次回の請求書をプレビューするには、upcoming invoice API で schedule (スケジュール) パラメーターを使用します。
スケジュールの作成と更新をプレビューする
サブスクリプションスケジュールの作成または更新をプレビューするには、schedule_details のパラメーターを使用します。既存の schedule (スケジュール) を渡して、作成または更新のどちらなのかを Stripe に伝えます。
プレビューしようとしている現在と将来の phases (フェーズ) をすべて渡します。
たとえば、次のコードは、1
フェーズが 12
請求期間にわたって続くサブスクリプションスケジュールの初回の請求書をプレビューします。
ダッシュボードの制限事項
ダッシュボードで、コードを使用せずにサブスクリプションスケジュールを作成し、更新できます。
ダッシュボードでは、すべてのフェーズを対象として (フェーズごとではなく) 以下の設定を使用できます。
- 請求しきい値
- 決済手段
- インボイス設定
- サブスクリプションの説明
- トライアル日数 (第 1 フェーズでのみ機能します)
次のパラメーターはダッシュボードでサポートされません。
- サブスクリプションスケジュールのメタデータ
- フェーズアイテムのメタデータ
- 通貨
- すべての Connect パラメーター