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

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

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

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

サブスクリプションスケジュールは、Stripe Billing ダッシュボードと API の両方で利用可能です。ダッシュボードでのサブスクリプションスケジュールの機能を示す短いビデオをご紹介します。

このドキュメントの以降の部分では、サブスクリプションスケジュールについてさらに詳しく説明します。例のリストを確認するには、ユースケースページをご覧ください。

フェーズ

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

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

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

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

次のフェーズに移行する

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

比例配分動作

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

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

2. フェーズ移行時の比例配分動作:各フェーズには、そのフェーズへの移行時に 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 設定を更新します。

トライアルを使用する

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

スケジュールを完了する

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

フェーズ属性の継承

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

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

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

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

{
  ...
  "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": ""
      },
    }
  ],
}

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

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

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

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

ユースケースページにはさらに詳細な例がありますが、顧客を用いてサブスクリプションスケジュールを作成する基本的な例を以下に紹介します。この方法でスケジュールを作成すると、サブスクリプションも自動的に作成されます。

curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=cus_GBHHxuvBvO26Ea \
  -d start_date=now \
  -d end_behavior=release \
  -d "phases[0][items][0][price]"=price_1GqNdGAJVYItwOKqEHb \
  -d "phases[0][items][0][quantity]"=1 \
  -d "phases[0][iterations]"=12

curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d from_subscription=sub_GB98WOvaRAWPl6

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

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

curl https://api.stripe.com/v1/subscription_schedules/
{{SUBSCRIPTION_SCHEDULE_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "phases[0][items][0][price]"=
{{PRICE_ID}} \
  -d "phases[0][items][0][quantity]"=2 \
  -d "phases[0][start_date]"=1577865600 \
  -d "phases[0][end_date]"=1580544000

curl https://api.stripe.com/v1/subscription_schedules/
{{SUBSCRIPTION_SCHEDULE_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "phases[0][items][0][price]"=
{{PRICE_ID}} \
  -d "phases[0][items][0][quantity]"=1 \
  -d "phases[0][start_date]"=1577865600 \
  -d "phases[0][end_date]"=now \
  -d "phases[1][items][0][price]"=
{{PRICE_ID}} \
  -d "phases[1][items][0][quantity]"=2 \
  -d "phases[1][start_date]"=now \
  -d "phases[1][end_date]"=1580544000

curl https://api.stripe.com/v1/subscription_schedules/
{{SUBSCRIPTION_SCHEDULE_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "phases[0][items][0][price]"=
{{PRICE_ID}} \
  -d "phases[0][items][0][quantity]"=1 \
  -d "phases[0][start_date]"=1577865600 \
  -d "phases[0][end_date]"=1580544000 \
  -d "phases[1][items][0][price]"=
{{PRICE_ID}} \
  -d "phases[1][items][0][quantity]"=2 \
  -d "phases[1][iterations]"=1

請求書をプレビューする

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

curl https://api.stripe.com/v1/invoices/create_preview \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d schedule=
{{SUBSCRIPTION_SCHEDULE_ID}}

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

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

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

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

curl https://api.stripe.com/v1/invoices/create_preview \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "customer_details[address][line1]"="920 5th Ave" \
  -d "customer_details[address][city]"=Seattle \
  -d "customer_details[address][state]"=WA \
  -d "customer_details[address][postal_code]"=98104 \
  -d "customer_details[address][country]"=US \
  -d "schedule_details[phases][0][start_date]"=now \
  -d "schedule_details[phases][0][items][0][price]"=
{{PRICE_ID}} \
  -d "schedule_details[phases][0][items][0][quantity]"=1 \
  -d "schedule_details[phases][0][iterations]"=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 を使用して削除すると、関連付けられたサブスクリプションスケジュールフェーズが 2 つのフェーズに自動的に分割されます。

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

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

• proration_behavior
• billing_cycle_anchor
• cancel_at_period_end
• description
• metadata
• pause_collection

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

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