コンテンツにスキップ
アカウント作成/サインイン
Stripe ドキュメントのロゴ
/
アカウントを作成サインイン
概要
Billing
概要Billing API について
サブスクリプション
税金
概要
レポート機能
概要複数のアカウントのレポート
データ
概要

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

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

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

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

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

サブスクリプションのスケジュールは、Stripe Billing ダッシュボードと API の両方で利用できます。

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

フェーズ

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

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

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

フェーズには duration 属性があり、これを使用してフェーズの存続期間を指定します。duration パラメーターには、week、month、year の値を使用できます。

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

次のフェーズに移行する

フェーズが 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 設定を更新します。

トライアルを使用する

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

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

スケジュールを完了する

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

フェーズ属性の継承

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

スケジュールの属性フェーズの属性
default_settings.billing_thresholdsphases.billing_thresholds
default_settings.collection_methodphases.collection_method
default_settings.default_payment_methodphases.default_payment_method
default_settings.invoice_settingsphases.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 に自動で移行します。

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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][duration][interval]"=month \
  -d "phases[0][duration][interval_count]"=12

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

  • 作成されるとすぐ開始します。
  • サブスクリプションが、 price_1GqNdGAJVYItwOKqEHb で商品のインスタンスに設定されます。
  • 12 カ月間継続し、その後、スケジュールからサブスクリプションをリリースします。

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

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d from_subscription=sub_GB98WOvaRAWPl6

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

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

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

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

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

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

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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

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

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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

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

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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][duration][interval]"=month \
  -d "phases[1][duration][interval_count]"=1

請求書をプレビューする

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

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/invoices/create_preview \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d schedule=
"{{SUBSCRIPTION_SCHEDULE_ID}}"

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

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

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

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

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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][duration][interval]"=month \
  -d "schedule_details[phases][0][duration][interval_count]"=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 つに分割されます。

  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 サイト上の会員専用コンテンツにアクセスできます。

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

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

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

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

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

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

定期支払いの変更

数量を増やす

クーポンを使用する

税率を変更する

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

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

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

分割支払い区分