サブスクリプションスケジュール

サブスクリプションスケジュールとその使用方法をご紹介します。

サブスクリプションスケジュールを使用して、時間の経過とともに発生するサブスクリプションへの変更を自動化します。スケジュールを介してサブスクリプションを直接作成することも、既存のサブスクリプションにスケジュールを追加することもできます。phases 属性を使用して、サブスクリプションに行う変更を定義します。スケジュールのすべてのフェーズが完了すると、end_behavior に基づいてスケジュールが完了します。

スケジュールで必要になる変更には、以下などがあります。

サブスクリプションを将来の日付から開始する
サブスクリプションを過去の日付にさかのぼる
サブスクリプションをアップグレードまたはダウングレードする

サブスクリプションスケジュールは、Stripe Billing ダッシュボードと API の両方で設定可能です。このビデオでは、ダッシュボードでのサブスクリプションスケジュールの仕組みを紹介しています。

ダッシュボードでのサブスクリプションスケジュール

サブスクリプションスケジュールの使用例については、ユースケースをご覧ください。

フェーズ

サブスクリプションスケジュールを作成する際には、phases 属性を使用して変更が発生するタイミングと、変更対象のサブスクリプションのプロパティを定義します。たとえば、サブスクリプションの最初の 3 カ月間に 50% オフのクーポンを提供するとします。このシナリオでは、最初のフェーズが 3 カ月間で、50% オフのクーポンを含むサブスクリプションスケジュールが作成されます。2 番目のフェーズでサブスクリプションは通常の料金に戻り、クーポンが削除されます。フェーズは連続的である必要があり、特定の時点でアクティブであるフェーズは 1 つのみになります。最大 10 フェーズの設定が可能です。

フェーズの長さを設定する

API またはダッシュボードを使用して、フェーズの長さを設定できます。

料金の interval (期間) によってサブスクリプションの請求頻度が決まります。たとえば、期間が 1 カ月の場合には毎月請求が行われます。フェーズには、iterations 属性があり、これを使用してフェーズの存続期間を指定します。この値に期間を乗じることでフェーズの長さが決定されます。サブスクリプションスケジュールで料金を 1 カ月分に指定し、iterations=2 と設定した場合には、フェーズが 2 カ月間続きます。

1 つのフェーズの end_date が、次のフェーズの start_date である必要があります。iterations を使用すると、自動的に start_date と end_date が適切に設定されます。これらの値を手動で設定することもできますが、Stripe では手動設定ではなく iterations を使用することをお勧めします。手動で開始日と終了日を設定するとエラーが起きやすいため、手動設定の使用は特別なユースケースのみにしてください。

次のフェーズに移行する

フェーズが end_date に達すると、フェーズ移行が自動的に発生します。フェーズが開始されると、Stripe は次のフェーズの属性に基づいてサブスクリプションを更新します。オプションで比例配分を有効にして、プラン内で未使用だった品目や時間をクレジットとしてユーザーに提供することもできます。

比例配分動作

次の 2 種類の比例配分動作の設定は、サブスクリプションスケジュールが変更された際に、Stripe が請求書の調整を処理する方法を制御します。

比例配分動作の更新のスケジュール:最上位の proration_behavior パラメーターは、現在のフェーズの請求書設定 (料金や数量の変更など) に影響を与えるようなサブスクリプションスケジュールの更新時に、比例配分の処理方法を制御します。
フェーズ移行時の比例配分動作:各フェーズには、そのフェーズへの移行時に Stripe が比例配分をどのように処理するかを制御する独自の proration_behavior 属性が指定されます。

比例配分動作の更新のスケジュール

サブスクリプションスケジュールを更新し、current_phase の請求書設定を変更する場合は、最上位の proration_behavior パラメーターを使用して比例配分の処理方法を制御できます。

このパラメーターは、Update a subscription APIのパラメーターと同様に機能し、次の値を受け付けます。

(デフォルト) create_prorations:請求書の変更に対して比例配分の調整が行われます。
none:更新に対して比例配分は作成されません。
always_invoice:比例配分が行われ、即座に請求書が確定します。

この設定に関係なく、請求書以外のフィールド (メタデータなど) を変更しても比例配分は行われません。

フェーズ移行時の比例配分動作

フェーズごとに proration_behavior を定義することで、サブスクリプションがそのフェーズに入ったときに実行するアクションを制御できます。この設定は、フェーズ移行中に行われる比例配分にとりわけ適用されるものであり、フェーズのフィールドとして保存されます。

たとえば、phases[1] の開始時に数量を 1 から 3 に増やした場合、phases[1] の proration_behavior によって、phases[0] から phases[1] への移行時に比例配分の処理方法が決まります。

(デフォルト) create_prorations:請求書の変更に備えて、保留中の請求書品目が生成されます。
none:このフェーズに入ると、比例配分は行われません。
always_invoice:このフェーズに入ると、比例配分が行われ、すぐに請求書が作成されます。

将来のフェーズ移行で比例配分の処理方法を変更する必要がある場合は、将来のフェーズがアクティブになる前に、その proration_behavior 設定を更新します。

トライアルを使用する

API またはダッシュボードを使用して、サブスクリプションの最初のフェーズにトライアル期間を追加できます。

フェーズにトライアルの終了を設定して、トライアル期間を追加できます。特定のフェーズ全体をトライアルにする場合には、trial_end の値をフェーズの end_date と同じにします。また、フェーズの一部のみをトライアルにする場合には、trial_end を end_date の前にします。更新をスケジュールする際には、各フェーズに新しい trial_end を指定する必要があります。

スケジュールを完了する

サブスクリプションスケジュールは、最後のフェーズが完了すると終了します。この時点で、サブスクリプションはその位置にとどまり、スケジュールとの関連付けはなくなります。スケジュールの最後のフェーズの完了後にサブスクリプションをキャンセルするには、end_behavior を cancel に設定します。サブスクリプションの cancel_on_date は、サブスクリプションが最終フェーズに移行するまで設定されません。

フェーズ属性の継承

フェーズが有効になると、そのフェーズに設定された属性はすべて、サブスクリプションにも設定されます。そのフェーズが終了すると、次のフェーズによって変更されない限り、またはスケジュールにデフォルト設定がない限り、属性は変化しません。一部の属性はスケジュールとフェーズの両方に設定できます。これには以下が含まれます。

スケジュールの属性	フェーズの属性
default_settings.billing_thresholds	phases.billing_thresholds
default_settings.collection_method	phases.collection_method
default_settings.default_payment_method	phases.default_payment_method
default_settings.invoice_settings	phases.invoice_settings

これらの属性の 1 つがスケジュールで定義されている場合、それはすべてのフェーズのデフォルトになります。スケジュールとフェーズの両方で同じプロパティが定義されている場合、フェーズ属性によってスケジュール属性が上書きされます。この動作については、以下で詳しく説明します。

スケジュール属性が存在	フェーズ属性が存在	結果
なし	なし	顧客またはアカウント設定がデフォルト
あり	なし	設定されたスケジュール属性
あり	あり	設定されたフェーズ属性
なし	あり	設定されたフェーズ属性

フェーズメタデータを使用する

サブスクリプションスケジュールのフェーズを使用して、基本となるサブスクリプションにメタデータを設定できます。これにより、予定された更新を使用して、サブスクリプションのメタデータを制御できます。

フェーズのメタデータを API で使用するには、サブスクリプションスケジュールのフェーズに metadata を設定します。基本となるサブスクリプションがそのフェーズに移行すると、次のようになります。

空ではない値を持つフェーズからのメタデータは、サブスクリプションのメタデータにキーがまだ「存在しない」場合、そのメタデータに「追加」されます。
空ではない値を持つフェーズからのメタデータは、サブスクリプションのメタデータにキーがすでに「存在する」場合、そのメタ―データの「更新」に使用されます。
つフェーズからのメタデータが「空の値」である場合、サブスクリプションのメタデータの対応するキーの「設定解除」に使用されます。

サブスクリプションのメタデータ内のすべてのキーを設定解除するには、サブスクリプションを直接更新するか、フェーズのメタデータから各キーを個別に設定解除します。元になるサブスクリプションのメタデータを直接更新しても、現在のフェーズのメタデータには影響しません。

以下の例は、2 つのフェーズがあるサブスクリプションスケジュールを示しています。各フェーズには独自のメタデータがあります。

{
  ...
  "object": "subscription_schedule",
  "phases": [
    { // Phase 1
      ...
      "metadata": {
        "channel": "self-serve",
        "region": "apac",
        "upsell-products": "alpha"
      },
    },
    { // Phase 2
      ...
      "metadata": {
        "channel": "sales",
        "churn-risk": "high",
        "upsell-products": ""
      },
    }
  ],
}

このスケジュールによって新しいサブスクリプションが作成され、サブスクリプションが Phase 1 になると、Phase 1 メタデータ内の 3 つのキーがサブスクリプションのメタデータに追加されます。このため、Phase 1 のサブスクリプションには以下のメタデータが存在することになります。

{
  ...
  "object": "subscription",
  "metadata": {
    "channel": "self-serve",
    "region": "apac",
    "upsell-products": "alpha"
  },
}

サブスクリプションが Phase 2 に入ると、サブスクリプションのメタデータは以下のように更新されます。

フェーズのメタデータに値が指定されており、サブスクリプションにそのキーを持つメタデータがすでに存在するため、channel の値は更新されます。
region の値はフェーズで指定されていないため、変わりません。
churn-risk は新しいキーであるため、追加されます。
フェーズで空の値が指定されているため、upsell-products は設定解除されます。

このため、Phase 2 のサブスクリプションには以下のメタデータが含まれます。

{
  ...
  "object": "subscription",
  "metadata": {
    "channel": "sales",
    "region": "apac",
    "churn-risk": "high"
  }
}

サブスクリプションメタデータをサブスクリプションの請求書にコピーする方法をご紹介します。

サブスクリプションスケジュールを作成する

この例は、顧客に対してサブスクリプションスケジュールを作成する方法を示しています。この方法でスケジュールを作成すると、サブスクリプションも自動的に作成されます。

注

サブスクリプションを直接作成する場合と異なり、collection_method が charge_automatically に設定されたサブスクリプションスケジュールの最初の請求書は、継続請求書のように機能し、サブスクリプションが作成された時点ではただちに確定_しません_。請求書は draft 状態で開始し、作成の約 1 時間後に Stripe によって確定されます。

たとえば、回収方法を自動請求に設定し、start_date=now を指定してサブスクリプションスケジュールを作成した場合、draft 状態のサブスクリプションと請求書も作成されます。請求書の編集は 1 時間以内に済ませる必要があります。その後、確定時の非同期型の支払い試行の結果に応じて、請求書のステータスは open または paid に自動で移行します。

このスケジュールでは以下のように設定されます。

作成されるとすぐ開始します。
サブスクリプションが、 price_1GqNdGAJVYItwOKqEHb で商品のインスタンスに設定されます。
12 回の反復を経た後に、サブスクリプションがスケジュールからリリースされます。

サブスクリプション ID を渡してサブスクリプションのスケジュールを作成することもできます。

この方法でスケジュールを作成すると、サブスクリプションの属性を使用してスケジュールの属性が設定されます。

他の Stripe API と同様に、サブスクリプションスケジュールを取得して更新できます。また、キャンセルしてリリースすることもできます。サブスクリプションスケジュールをキャンセルすると、サブスクリプションも同様にキャンセルされます。サブスクリプションからスケジュールのみを削除する場合は、リリースコールを使用します。

サブスクリプションスケジュールを更新する

サブスクリプションスケジュールは、現在および将来のフェーズのみ更新できます。

サブスクリプションスケジュールを更新する際は、現在および将来のすべてのフェーズを渡す必要があります。また、以前に設定されたパラメーターを保持する場合は、そのパラメーターも渡す必要があります。以前に設定されたパラメーターは、更新リクエストで渡さない限り、既存のフェーズでは設定されません。過去のフェーズに関する情報はレスポンスで受け取ることが可能です。

現在または以降のフェーズは最大 10 個まで含めることができます。アクティブなフェーズを更新すると、その基礎となるサブスクリプションも同様に更新されます。たとえば、次の呼び出しでは既存の開始日と終了日が維持されますが、quantity が 2 に更新されます。

現在のフェーズをすぐに終了して、新しいフェーズを開始することもできます。これにより、アクティブなフェーズが過去に移動し、新しいフェーズがサブスクリプションに即座に適用されます。以下の例では、現在のフェーズが終了し、新しいフェーズが開始します。

サブスクリプションのスケジュールにフェーズを追加するには、現在のフェーズを渡し、新しいフェーズを定義します。

請求書をプレビューする

サブスクリプションスケジュールの次回の請求書をプレビューするには、プレビューの作成で schedule パラメーターを使用します。

スケジュールの作成と更新をプレビューする

サブスクリプションスケジュールの作成または更新をプレビューするには、schedule_details パラメーターを使用します。既存の schedule (スケジュール) を渡して、作成または更新のどちらなのかを Stripe に伝えます。

プレビューしようとしている現在と将来の phases (フェーズ) をすべて渡します。

たとえば、次のコードは、1 フェーズが 12 請求期間にわたって続くサブスクリプションスケジュールの初回の請求書をプレビューします。

その他の考慮事項

一般に、サブスクリプションスケジュールはサブスクリプションと同じ制限に従いますが、独自の制限もいくつか導入されています。さらに、サブスクリプションスケジュールとサブスクリプションの相互関係によって、予期しない動作が発生することがあります。サブスクリプションスケジュールを使用する際の制限、製品の動作、一般的なベストプラクティスを理解するには、以下のセクションをご覧ください。

制限

サブスクリプションスケジュールで定義できる現在のフェーズまたは将来のフェーズは、1 度に 10 件までです。過去のフェーズはこの制限にカウントされません。
複数の項目を持つサブスクリプションスケジュールフェーズを作成する場合は、サブスクリプションと同じ制限にも従います。

ダッシュボードの制限

ダッシュボードで、コードを使用せずにサブスクリプションスケジュールを作成し、更新できます。

ダッシュボードでは、すべてのフェーズを対象として (フェーズごとではなく) 以下の設定を使用できます。

請求しきい値
決済手段
請求書設定
サブスクリプションの説明
トライアル日数 (第 1 フェーズでのみ機能します)

次のパラメーターはダッシュボードでサポートされません。

サブスクリプションスケジュールのメタデータ
フェーズアイテムのメタデータ
通貨
すべての Connect パラメーター

スケジュールが関連付けらている場合のサブスクリプションの更新

時間が経過してスケジュールの次のフェーズになったときに、サブスクリプションスケジュールを使用して、サブスクリプションを自動的に変更します。サブスクリプションに直接加えた変更の一部は、サブスクリプションスケジュールのフェーズに反映されますが、反映されない変更もあります。このため、サブスクリプションを直接変更した場合、次のフェーズになったときにサブスクリプションスケジュールによって上書きされる可能性があります。

サブスクリプションへの変更をスケジュール設定する際は、以下のベストプラクティスに従ってください。

サブスクリプションにサブスクリプションのスケジュールが関連付けられている場合、Subscriptions APIではなく、 Subscription Schedule API を使用してサブスクリプションを変更します。
今後の API 更新のために、サブスクリプションスケジュール ID をサブスクリプション ID と一緒に保存します。サブスクリプションスケジュール ID は、API を使用して作成する場合、または subscription_schedule.created Webhook により　Stripe が自動作成する場合 (顧客がカスタマーポータルでダウングレードをスケジュールした場合など) に返されます。
サブスクリプションスケジュールがリリースされたときに、サブスクリプションスケジュール ID を破棄します。サブスクリプションを直接変更するか、新しいサブスクリプションスケジュールを作成します。サブスクリプションスケジュールがリリースされると、API を使用してリリース、または subscription_schedule.released Webhook イベントを通じてサブスクリプションスケジュール ID が返されます。
ダッシュボードを使用してサブスクリプションを変更します (可能な場合)。これにより、関連付けられているサブスクリプションスケジュールが自動的に更新されます。

具体的には、サブスクリプションで次のいずれかのサブスクリプション属性を直接変更するときに、このアクションにより、新しいサブスクリプションスケジュールフェーズが自動的に作成される場合があります。

discounts
tax_rates
items
trial_end、trial_settings、trial_start
application_fee_percent
add_invoice_items
automatic_tax

たとえば、2 つのアイテムが含まれるサブスクリプションを考えてみましょう。このサブスクリプションには現在のサブスクリプションのステータスと同じ内容を反映した、単一フェーズのサブスクリプションスケジュールが紐付いています。もし API を使ってアイテムの 1 つを削除すると、紐付いたサブスクリプションスケジュールのフェーズは自動的に 2 つに分割されます。

終了したばかりで、2 つのサブスクリプションアイテムがあったフェーズ
サブスクリプションアイテムが 1 つのみの新しいフェーズ

サブスクリプションスケジュールフェーズが自動的に分割されると、以下のプロパティが現在のフェーズから新しいフェーズにコピーされます。

proration_behavior
billing_cycle_anchor
cancel_at_period_end
description
metadata
pause_collection

さらに Stripe は、以下の最上位のサブスクリプション属性を、サブスクリプションスケジュールまたはその default_settings にコピーすることがあります。

サブスクリプションの属性	新しいサブスクリプションスケジュールフェーズにコピーされました	サブスクリプションスケジュール `default_settings` にコピーされました
`coupon`
`trial_end`
`tax_rates`
`application_fee_percent`
`discounts`
`collection_method`
`invoice_settings`
`default_payment_method`
`default_source`
`transfer_data`
`on_behalf_of`
`currency`
`add_invoice_items`
`automatic_tax`
`items.prices`
`billing_thresholds`

サブスクリプションの metadata に対する更新は、関連付けられたサブスクリプションスケジュールに反映されません。

ユースケース

定期支払いスケジュールについて説明するため、The Pacific という架空の新聞会社の例を紹介します。この新聞社は 2 つのサブスクリプションオプションを提供しています。

「印刷版」では、顧客は紙に印刷された新聞を受け取ります。
_デジタル版_では、顧客は The Pacific の Web サイト上の会員専用コンテンツにアクセスできます。

両方のサブスクリプションともに、請求は月次です。以下の定期スケジュールのオプションをご覧ください。

将来の日付でサブスクリプションを開始する

デフォルトでは、印刷版の新しいサブスクリプションは翌月の 1 日に開始されます。これを行うには、start_date を将来の日付に設定します。以下のコードは、将来に開始されるサブスクリプションを作成します。

サブスクリプションを遡及適用する

顧客がデジタルプランに登録すると、The Pacific はそのサブスクリプションを現在の月の 1 日まで遡及適用します。この遡及適用により、過去の期間に対しても請求できるようになるほか、デジタル版の登録者は Web サイトにすぐにアクセスできるようになります。

既存のサブスクリプションにスケジュールを追加する

The Pacific で、元の顧客がスケジュールが設定されていないサブスクリプションを利用していることが発覚したと仮定します。これらのサブスクリプションはすでに存在するため、from_subscription 属性でサブスクリプション ID を渡してスケジュールを追加できます。この方法でサブスクリプション ID を渡すと、サブスクリプションの現在の請求期間に基づいて 1 つのフェーズを持つスケジュールが作成されます。

これらのスケジュールを追加しているときに、一部の顧客が印刷版の登録を決めたため、The Pacific はスケジュールに 2 番目のフェーズを追加して、1 カ月後に印刷版のプランを開始します。サブスクリプションのアップグレードのユースケースは、このプロセスの例を示したものです。

サブスクリプションのアップグレード

The Pacific は、最初に印刷版を 1 カ月登録した後、自動的にデジタル版を追加するオプションを提供しています。最初に印刷版を試してからサブスクリプションを続けるかキャンセルするかを決定できるため、一部の顧客はこのオプションを利用しています。

サブスクリプションのダウングレード

さらに The Pacific は、印刷版とデジタル版の両方の登録後、印刷版のみの登録にダウングレードするオプションも提供しています。顧客はこのオプションを使用して両方の出版物を試し、ニーズに合うかどうかを確認できます。

定期支払いの変更

Pacific は、広告付きの基本オプションと、広告なしのプレミアムオプションの 2 種類の印刷版のサブスクリプションオプションを提供しています。プレミアムオプションの一部の顧客が、次回の請求期間から広告付きの基本オプションに変更することを決定しました。既存のサブスクリプションを使用してスケジュールを作成し、その後に新しいフェーズとして広告付きの基本オプションでスケジュールを更新します。

数量を増やす

また、定期支払いの数量の増加をスケジュールすることもできます。以下のスケジュールは、1 カ月という期間でデジタル発行の 1 つのインスタンスを開始します。2 番目のフェーズでは、数量が 11 カ月間、2 に増加します。

クーポンを使用する

The Pacific は時折、特別なサブスクリプションを提供しています。以下のスケジュールでは、印刷版を 6 か月間 50% オフで利用できます。このスケジュールの 2 番目のフェーズ (残りの 6 カ月間) でクーポンは削除されます

税率を変更する

The Pacific は複数の管轄区域で事業を行っており、一部の区域ではサブスクリプションビジネスに対する独自の税率を設けています。これらの管轄区域の 1 つでは、顧客がサブスクリプションを最初に登録した最初の月の請求と、その後の継続請求に対して 2 種類の税率が設定されます。

スケジュールからサブスクリプションをリリースする

ステータスが not_started または active の場合、スケジュールからサブスクリプションをリリースすることができます。サブスクリプションをリリースするとそのサブスクリプションは残りますが、スケジュールや残りのフェーズは削除されます。

スケジュールとサブスクリプションをキャンセルする

サブスクリプションスケジュールにアクティブなサブスクリプションが含まれる場合は、それとそれに関連するサブスクリプションも直ちにキャンセルされます。サブスクリプションスケジュールは、ステータスが not_started または active の場合にのみキャンセルできます。

請求サイクルの起点をリセットする

The Pacific では、長年の印刷版の顧客に対し、毎月、顧客が最初に購読を開始した日に請求しています。この日は、請求サイクルの起点です。

このような顧客がデジタル版に移行すると、The Pacific は移行日を翌月の 1 日にスケジュールします。また、請求サイクルの起点も同じ日にリセットします。

以下のサンプルコードを使用してサブスクリプションを作成することにより、請求サイクルの起点がリセットされることを確認できます。ダッシュボードでサブスクリプションを確認すると、デジタル版が 1 日に開始されるとすぐに顧客に次回の請求書が請求されるようにスケジュールされていることがわかります。

起点をリセットしない場合の動作を確認するには、請求サイクルの起点を phase_start に設定する行を削除して、サンプルコードを再度実行します。この行がないと、取引が 1 日に発生するにもかかわらず、ダッシュボードの次回の請求書は、本日から丸 1 カ月経過してから請求されます。

分割支払い区分

分割払いプランを使用すると、顧客は、設定された期間の支払いを、全額を支払い終えるまで分割して支払うことができます。たとえば、The Pacific が新しい印刷機を購入する際、古い印刷機を他の出版会社に販売します。小規模の出版会社は、全額を最初に支払う資金的な余裕がないことが多いため、分割払いを使用します。

ほとんどの印刷機について、The Pacific は月あたり 1,000 ドルを請求するため、再利用可能な価格が作成されます。

印刷機の型、モデル、使用年数に応じて、The Pacific が請求する金額は異なります。この例では、1 カ月当たり 1,000 ドルを 6 カ月間請求し、合計 6,000 ドルを請求します。

iterations の数に価格の期間を乗じて顧客に対する請求回数 (この例では 6 回の月次支払い) が決定されます。end_behavior は、最後の繰り返し終了後にサブスクリプションがどのようになるかを決定します。分割払いプランでは、サブスクリプションは必要なくなるため、end_behavior は cancel に設定されます。

まれに、The Pacific が請求する金額が通常の 1,000 ドル/月よりも少ない場合があります。この場合、price_data を使用して 1 回限りの使用の価格を作成します。この例では、500 ドルの価格を作成し、6 カ月間、毎月請求します。