# サブスクリプションスケジュール サブスクリプションスケジュールとその使用方法をご紹介します。 [サブスクリプションスケジュール](https://docs.stripe.com/api/subscription_schedules.md)を使用して、時間の経過とともに発生するサブスクリプションへの変更を自動化します。スケジュールを介してサブスクリプションを直接[作成](https://docs.stripe.com/api/subscription_schedules/create.md)することも、既存のサブスクリプションにスケジュールを追加することもできます。[phases](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases) 属性を使用して、サブスクリプションに行う変更を定義します。スケジュールのすべてのフェーズが完了すると、[end_behavior](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-end_behavior) に基づいてスケジュールが完了します。 スケジュールで必要になる変更には、以下などがあります。 - サブスクリプションを将来の日付から開始する - サブスクリプションを過去の日付にさかのぼる - サブスクリプションをアップグレードまたはダウングレードする サブスクリプションのスケジュールは、Stripe Billing ダッシュボードと API の両方で利用できます。 サブスクリプションスケジュールの使用例については、[ユースケース](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md#use-cases)をご覧ください。 ## フェーズ サブスクリプションスケジュールを作成する際には、[phases](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases) 属性を使用して変更が発生するタイミングと、変更対象のサブスクリプションのプロパティを定義します。たとえば、サブスクリプションの最初の 3 カ月間に 50% オフのクーポンを提供するとします。このシナリオでは、最初のフェーズが 3 カ月間で、50% オフのクーポンを含むサブスクリプションスケジュールが作成されます。2 番目のフェーズでサブスクリプションは通常の料金に戻り、クーポンが削除されます。フェーズは連続的である必要があり、特定の時点でアクティブであるフェーズは 1 つのみになります。最大 10 フェーズの設定が可能です。 ### フェーズの長さを設定する API またはダッシュボードを使用して、フェーズの長さを設定できます。 #### API フェーズには [duration](https://docs.stripe.com/api/subscription_schedules/update.md#update_subscription_schedule-phases-duration) 属性があり、これを使用してフェーズの存続期間を指定します。`duration` パラメーターには、`week`、`month`、`year` の値を使用できます。 1 つのフェーズの `end_date` が、次のフェーズの `start_date` である必要があります。`duration` を使用すると、自動的に `start_date` と `end_date` が適切に設定されます。これらの値を手動で設定することもできますが、Stripe では手動設定ではなく `duration` を使用することをお勧めします。手動で開始日と終了日を設定するとエラーが起きやすいため、手動設定の使用は特別なユースケースのみにしてください。 #### ダッシュボード フェーズの長さを設定するには： 1. ダッシュボードで、[サブスクリプションエディター](https://dashboard.stripe.com/subscriptions?create=subscription)を開きます。 1. 新しい顧客を追加するか、既存の顧客を見つけます。 1. 新しい商品を追加するか、既存の商品を見つけます。 1. **+ フェーズを追加**をクリックします。 1. フェーズの期間を選択します。**無期限**を選択して、サブスクリプションを無期限に有効にすることもできます。 ### 次のフェーズに移行する フェーズが `end_date` に達すると、フェーズ移行が自動的に発生します。フェーズが開始されると、Stripe は次のフェーズの属性に基づいてサブスクリプションを更新します。オプションで[比例配分](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases-proration_behavior)を有効にして、プラン内で未使用だった品目や時間をクレジットとしてユーザーに提供することもできます。 #### 比例配分動作 次の 2 種類の比例配分動作の設定は、サブスクリプションスケジュールが変更された際に、Stripe が請求書の調整を処理する方法を制御します。 1. **比例配分動作の更新のスケジュール**:最上位の [proration_behavior](https://docs.stripe.com/api/subscription_schedules/update.md#update_subscription_schedule-proration_behavior) パラメーターは、現在のフェーズの請求書設定 (料金や数量の変更など) に影響を与えるようなサブスクリプションスケジュールの更新時に、比例配分の処理方法を制御します。 1. **フェーズ移行時の比例配分動作**:各フェーズには、そのフェーズへの移行時に Stripe が比例配分をどのように処理するかを制御する独自の [proration_behavior](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases-proration_behavior) 属性が指定されます。 ##### 比例配分動作の更新のスケジュール サブスクリプションスケジュールを更新し、`current_phase` の請求書設定を変更する場合は、最上位の `proration_behavior` パラメーターを使用して比例配分の処理方法を制御できます。 このパラメーターは、[Update a subscription API](https://docs.stripe.com/api/subscriptions/update.md#update_subscription-proration_behavior)のパラメーターと同様に機能し、次の値を受け付けます。 - (デフォルト) `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 またはダッシュボードを使用して、サブスクリプションの最初のフェーズにトライアル期間を追加できます。 #### API フェーズに[トライアルの終了](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-trial_end)を設定して、トライアル期間を追加できます。特定のフェーズ全体をトライアルにする場合には、`trial_end` の値をフェーズの `end_date` と同じにします。また、フェーズの一部のみをトライアルにする場合には、`trial_end` を `end_date` の前にします。更新をスケジュールする際には、各フェーズに新しい `trial_end` を指定する必要があります。 #### ダッシュボード 新しいサブスクリプションの最初のフェーズにトライアル期間を追加するには： 1. ダッシュボードで、[サブスクリプションエディター](https://dashboard.stripe.com/subscriptions?create=subscription)を開きます。 1. 新しい顧客を追加するか、既存の顧客を見つけます。 1. 新しい商品を追加するか、既存の商品を見つけます。 1. **無料トライアル期間**で、無料トライアル期間の長さを設定します。 - フェーズ全体をトライアルにする場合は、トライアルの長さをフェーズの長さと同じに設定します。 - フェーズの一部のみをトライアルにする場合は、トライアルの長さをフェーズの長さより短く設定します。 既存のサブスクリプションの最初のフェーズにトライアル期間を追加するには： 1. ダッシュボードで、[サブスクリプション](https://dashboard.stripe.com/subscriptions)ページに移動して、既存のサブスクリプションを選択し、**アクション** > **サブスクリプションを更新**をクリックします。 1. サブスクリプションで、最初のフェーズの**編集**をクリックします。 1. **無料トライアル期間**で、無料トライアル期間の長さを設定します。 - フェーズ全体をトライアルにする場合は、トライアルの長さをフェーズの長さと同じに設定します。 - フェーズの一部のみをトライアルにする場合は、トライアルの長さをフェーズの長さより短く設定します。 1. **保存**をクリックしてフェーズを更新します。 1. **サブスクリプションを更新**をクリックします。 ### スケジュールを完了する サブスクリプションスケジュールは、最後のフェーズが完了すると終了します。この時点で、サブスクリプションはその位置にとどまり、スケジュールとの関連付けはなくなります。スケジュールの最後のフェーズの完了後にサブスクリプションをキャンセルするには、[end_behavior](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-end_behavior) を `cancel` に設定します。サブスクリプションの [cancel_on_date](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-cancel_at) は、サブスクリプションが最終フェーズに移行するまで設定されません。 ### フェーズ属性の継承 フェーズが有効になると、そのフェーズに設定された属性はすべて、サブスクリプションにも設定されます。そのフェーズが終了すると、次のフェーズによって変更されない限り、またはスケジュールにデフォルト設定がない限り、属性は変化しません。一部の属性はスケジュールとフェーズの両方に設定できます。これには以下が含まれます。 | スケジュールの属性 | フェーズの属性 | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | [default_settings.billing_thresholds](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-default_settings-billing_thresholds) | [phases.billing_thresholds](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases-billing_thresholds) | | [default_settings.collection_method](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-default_settings-collection_method) | [phases.collection_method](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-collection_method) | | [default_settings.default_payment_method](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-default_settings-default_payment_method) | [phases.default_payment_method](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-default_payment_method) | | [default_settings.invoice_settings](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-default_settings-invoice_settings) | [phases.invoice_settings](https://docs.stripe.com/api/subscription_schedules/create.md#create_subscription_schedule-phases-invoice_settings) | これらの属性の 1 つがスケジュールで定義されている場合、それはすべてのフェーズのデフォルトになります。スケジュールとフェーズの両方で同じプロパティが定義されている場合、フェーズ属性によってスケジュール属性が上書きされます。この動作については、以下で詳しく説明します。 | スケジュール属性が存在 | フェーズ属性が存在 | 結果 | | ----------- | --------- | ------------------ | | なし | なし | 顧客またはアカウント設定がデフォルト | | あり | なし | 設定されたスケジュール属性 | | あり | あり | 設定されたフェーズ属性 | | なし | あり | 設定されたフェーズ属性 | ### フェーズメタデータを使用する サブスクリプションスケジュールのフェーズを使用して、基本となるサブスクリプションにメタデータを設定できます。これにより、予定された更新を使用して、サブスクリプションのメタデータを制御できます。 #### API フェーズのメタデータを API で使用するには、サブスクリプションスケジュールのフェーズに [metadata](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-phases-metadata) を設定します。基本となるサブスクリプションがそのフェーズに移行すると、次のようになります。 - 空ではない値を持つフェーズからのメタデータは、サブスクリプションのメタデータにキーがまだ「存在しない」場合、そのメタデータに「追加」されます。 - 空ではない値を持つフェーズからのメタデータは、サブスクリプションのメタデータにキーがすでに「存在する」場合、そのメタ―データの「更新」に使用されます。 - つフェーズからのメタデータが「空の値」である場合、サブスクリプションのメタデータの対応するキーの「設定解除」に使用されます。 サブスクリプションのメタデータ内のすべてのキーを設定解除するには、サブスクリプションを直接更新するか、フェーズのメタデータから各キーを個別に設定解除します。元になるサブスクリプションのメタデータを直接更新しても、現在のフェーズのメタデータには影響しません。 以下の例は、2 つのフェーズがあるサブスクリプションスケジュールを示しています。各フェーズには独自のメタデータがあります。 ```json { ... "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` のサブスクリプションには以下のメタデータが存在することになります。 ```json { ... "object": "subscription", "metadata": { "channel": "self-serve", "region": "apac", "upsell-products": "alpha" } } ``` サブスクリプションが `Phase 2` に入ると、サブスクリプションのメタデータは以下のように更新されます。 - フェーズのメタデータに値が指定されており、サブスクリプションにそのキーを持つメタデータがすでに存在するため、`channel` の値は更新されます。 - `region` の値はフェーズで指定されていないため、変わりません。 - `churn-risk` は新しいキーであるため、追加されます。 - フェーズで空の値が指定されているため、`upsell-products` は設定解除されます。 このため、`Phase 2` のサブスクリプションには以下のメタデータが含まれます。 ```json { ... "object": "subscription", "metadata": { "channel": "sales", "region": "apac", "churn-risk": "high" } } ``` #### ダッシュボード [Billing ダッシュボードのサブスクリプションエディター](https://dashboard.stripe.com/subscriptions?create=subscription)を使用して、サブスクリプションスケジュールの各フェーズのメタデータ項目の追加、編集、削除を行うことができます。新しいフェーズが有効になると、そのフェーズのメタデータと一致するように、Subscription オブジェクトのメタデータが更新されます。 1. ダッシュボードで、[サブスクリプションエディター](https://dashboard.stripe.com/subscriptions?create=subscription)を開きます。 1. 新しい顧客を追加するか、既存の顧客を見つけます。 1. 新しい商品を追加するか、既存の商品を見つけます。 1. 新規または既存のフェーズで、**+ メタデータを追加**をクリックします。 1. **キー**と**値**を入力し、**保存**をクリックします。 [サブスクリプションメタデータをサブスクリプションの請求書にコピー](https://docs.stripe.com/billing/invoices/subscription.md#subscription-metadata)する方法をご紹介します。 ## サブスクリプションスケジュールを作成する Connect プラットフォームが [customer-configured Accounts](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer) を使用している場合は、Stripe の [ガイド](https://docs.stripe.com/connect/use-accounts-as-customers.md)をご確認の上、コード内の `Customer` およびイベント参照を同等の Accounts v2 API リファレンスに置き換えてください。 この例は、顧客に対してサブスクリプションスケジュールを作成する方法を示しています。この方法でスケジュールを作成すると、サブスクリプションも自動的に作成されます。 > サブスクリプションを直接作成する場合と異なり、`collection_method` が `charge_automatically` に設定されたサブスクリプションスケジュールの最初の請求書は、継続請求書のように機能し、サブスクリプションが作成された時点ではただちに確定_しません_。請求書は `draft` 状態で開始し、[作成の約 1 時間後](https://docs.stripe.com/billing/subscriptions/webhooks.md#understand) に Stripe によって確定されます。 > > たとえば、回収方法を自動請求に設定し、`start_date=now` を指定してサブスクリプションスケジュールを作成した場合、`draft` 状態のサブスクリプションと請求書も作成されます。[請求書の編集](https://docs.stripe.com/api/invoices/update.md)は 1 時間以内に済ませる必要があります。その後、確定時の非同期型の支払い試行の結果に応じて、請求書のステータスは `open` または `paid` に自動で移行します。 #### API ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -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 を渡してサブスクリプションのスケジュールを作成することもできます。 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d from_subscription=sub_GB98WOvaRAWPl6 ``` この方法でスケジュールを作成すると、サブスクリプションの属性を使用してスケジュールの属性が設定されます。 他の Stripe API と同様に、[サブスクリプションスケジュール](https://docs.stripe.com/api/subscription_schedules.md)を取得および更新できます。キャンセルしたり、リリースしたりすることも可能です。サブスクリプションスケジュールをキャンセルすると、サブスクリプションも同様にキャンセルされます。サブスクリプションからスケジュールのみを削除する場合は、[リリース](https://docs.stripe.com/api/subscription_schedules/release.md)コールを使用します。 #### ダッシュボード マルチフェーズサブスクリプションスケジュールを作成するには： 1. ダッシュボードで、[サブスクリプションエディター](https://dashboard.stripe.com/subscriptions?create=subscription)を開きます。 1. 新しい顧客を追加するか、既存の顧客を見つけます。 1. 新しい商品を追加するか、既存の商品を見つけます。 1. サブスクリプションスケジュールの最初のフェーズの期間を設定します。 1. **+ フェーズを追加**をクリックします。 1. フェーズの期間を選択します。**無期限**を選択して、サブスクリプションを無期限に有効にすることもできます。 1. 新しいフェーズに必要な変更を加えます。数量の変更、価格の変更、クーポンの追加または削除、請求期間日のリセット、比例配分の動作の変更、メタデータの更新が可能です。フェーズでメタデータを変更すると、そのフェーズが有効になったときにサブスクリプションのメタデータが更新されます。 1. 新しいフェーズを保存します。 1. 必要に応じて、さらにフェーズを追加します。 1. **サブスクリプションのスケジュール**をクリックします。 ## サブスクリプションスケジュールを更新する サブスクリプションスケジュールは、現在および将来のフェーズのみ更新できます。 #### API サブスクリプションスケジュールを更新する際は、現在および将来のすべてのフェーズを渡す必要があります。また、以前に設定されたパラメーターを保持する場合は、そのパラメーターも渡す必要があります。以前に設定されたパラメーターは、更新リクエストで渡さない限り、既存のフェーズでは設定されません。過去のフェーズに関する情報はレスポンスで受け取ることが可能です。 現在または以降のフェーズは最大 10 個まで含めることができます。アクティブなフェーズを更新すると、その基礎となるサブスクリプションも同様に更新されます。たとえば、次の呼び出しでは `quantity` が 2 に更新されます。 ```curl curl https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTIONSCHEDULE_ID}} \ -u "<>:" \ -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 curl https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTIONSCHEDULE_ID}} \ -u "<>:" \ -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 curl https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTIONSCHEDULE_ID}} \ -u "<>:" \ -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 ``` #### ダッシュボード 既存のサブスクリプションを将来のサブスクリプションスケジュールフェーズに更新するには、以下のようにします。 1. ダッシュボードで、[サブスクリプション](https://dashboard.stripe.com/subscriptions)ページに移動して、既存のサブスクリプションを選択し、**アクション** > **サブスクリプションを更新**をクリックします。 1. 終了日を選択して、サブスクリプションスケジュールの現在のフェーズの期間を設定します。 1. **+フェーズを追加**をクリックします。 1. 次のフェーズの期間を選択します。**無期限**を選択して、サブスクリプションを無期限に有効にすることもできます。 1. 新しいフェーズに必要な変更を加えます。数量の変更、価格の変更、クーポンの追加または削除、請求期間日のリセット、比例配分の動作の変更、メタデータの更新が可能です。フェーズでメタデータを変更すると、そのフェーズが有効になったときにサブスクリプションのメタデータが更新されます。 1. 新しいフェーズを保存します。 1. 必要に応じて、さらにフェーズを追加します。 1. **サブスクリプションのスケジュール**をクリックします。 ## 請求書をプレビューする サブスクリプションスケジュールの次回の請求書をプレビューするには、[プレビューの作成](https://docs.stripe.com/api/invoices/create_preview.md)で [schedule](https://docs.stripe.com/api/invoices/create_preview.md#create_create_preview-schedule) パラメーターを使用します。 ```curl curl https://api.stripe.com/v1/invoices/create_preview \ -u "<>:" \ -d schedule="{{SUBSCRIPTIONSCHEDULE_ID}}" ``` ### スケジュールの作成と更新をプレビューする サブスクリプションスケジュールの作成または更新をプレビューするには、[schedule_details](https://docs.stripe.com/api/invoices/create_preview.md#create_create_preview-schedule_details) パラメーターを使用します。既存の [schedule (スケジュール)](https://docs.stripe.com/api/invoices/create_preview.md#create_create_preview-schedule) を渡して、作成または更新のどちらなのかを Stripe に伝えます。 プレビューしようとしている現在と将来の [phases (フェーズ)](https://docs.stripe.com/api/invoices/create_preview.md#create_create_preview-schedule_details-phases) をすべて渡します。 たとえば、次のコードは、 `12` カ月にわたって続く `1` フェーズのサブスクリプションスケジュールの初回請求書をプレビューします。 ```curl curl https://api.stripe.com/v1/invoices/create_preview \ -u "<>:" \ -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 件までです。過去のフェーズはこの制限にカウントされません。 - 複数の項目を持つサブスクリプションスケジュールフェーズを作成する場合は、[サブスクリプションと同じ制限](https://docs.stripe.com/billing/subscriptions/quantities.md#billing-periods-with-multiple-prices)にも従います。 ### ダッシュボードの制限 [ダッシュボード](https://dashboard.stripe.com/test/subscriptions)で、コードを使用せずにサブスクリプションスケジュールを作成し、更新できます。 ダッシュボードでは、すべてのフェーズを対象として (フェーズごとではなく) 以下の設定を使用できます。 - 請求しきい値 - 決済手段 - 請求書設定 - サブスクリプションの説明 - トライアル日数 (第 1 フェーズでのみ機能します) 次のパラメーターはダッシュボードでサポートされません。 - サブスクリプションスケジュールのメタデータ - フェーズアイテムのメタデータ - 通貨 - すべての Connect パラメーター ### スケジュールが関連付けらている場合のサブスクリプションの更新 時間が経過してスケジュールの次のフェーズになったときに、[サブスクリプションスケジュール](https://docs.stripe.com/api/subscription_schedules.md)を使用して、サブスクリプションを自動的に変更します。サブスクリプションに直接加えた変更の一部は、サブスクリプションスケジュールのフェーズに反映されますが、反映されない変更もあります。このため、サブスクリプションを直接変更した場合、次のフェーズになったときにサブスクリプションスケジュールによって上書きされる可能性があります。 サブスクリプションへの変更をスケジュール設定する際は、以下のベストプラクティスに従ってください。 - サブスクリプションにサブスクリプションのスケジュールが関連付けられている場合、[Subscriptions](https://docs.stripe.com/api/subscriptions.md#subscriptions) APIではなく、 [Subscription Schedule](https://docs.stripe.com/api/subscription_schedules.md) API を使用してサブスクリプションを変更します。 - 今後の API 更新のために、サブスクリプションスケジュール ID をサブスクリプション ID と一緒に保存します。サブスクリプションスケジュール ID は、[API を使用して作成](https://docs.stripe.com/api/subscription_schedules/create.md)する場合、または [subscription_schedule.created](https://docs.stripe.com/api/events/types.md#event_types-subscription_schedule.created) Webhook により　Stripe が自動作成する場合 (顧客が[カスタマーポータル](https://docs.stripe.com/customer-management/configure-portal.md#configure-subscription-management)でダウングレードをスケジュールした場合など) に返されます。 - サブスクリプションスケジュールがリリースされたときに、サブスクリプションスケジュール ID を破棄します。サブスクリプションを直接変更するか、新しいサブスクリプションスケジュールを作成します。サブスクリプションスケジュールがリリースされると、[API を使用してリリース](https://docs.stripe.com/api/subscription_schedules/release.md)、または [subscription_schedule.released](https://docs.stripe.com/api/events/types.md#event_types-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 つを削除](https://docs.stripe.com/api/subscription_items/delete.md) すると、紐付いたサブスクリプションスケジュールのフェーズは自動的に 2 つに分割されます。 1. 終了したばかりで、2 つのサブスクリプションアイテムがあったフェーズ 1. サブスクリプションアイテムが 1 つのみの新しいフェーズ サブスクリプションスケジュールフェーズが自動的に分割されると、以下のプロパティが現在のフェーズから新しいフェーズにコピーされます。 - `proration_behavior` - `billing_cycle_anchor` - `cancel_at_period_end` - `description` - `metadata` - `pause_collection` さらに Stripe は、以下の最上位のサブスクリプション属性を、サブスクリプションスケジュールまたはその [`default_settings`](https://docs.stripe.com/api/subscription_schedules/object.md#subscription_schedule_object-default_settings) にコピーすることがあります。 | サブスクリプションの属性 | 新しいサブスクリプションスケジュールフェーズにコピーされました | サブスクリプションスケジュール `default_settings` にコピーされました | | ------------------------- | ------------------------------- | -------------------------------------------- | | `coupon` | ✓ Supported | - Unsupported | | `trial_end` | ✓ Supported | - Unsupported | | `tax_rates` | ✓ Supported | - Unsupported | | `application_fee_percent` | ✓ Supported | ✓ Supported | | `discounts` | ✓ Supported | - Unsupported | | `collection_method` | ✓ Supported | ✓ Supported | | `invoice_settings` | ✓ Supported | ✓ Supported | | `default_payment_method` | ✓ Supported | ✓ Supported | | `default_source` | ✓ Supported | ✓ Supported | | `transfer_data` | ✓ Supported | ✓ Supported | | `on_behalf_of` | ✓ Supported | ✓ Supported | | `currency` | ✓ Supported | - Unsupported | | `add_invoice_items` | ✓ Supported | - Unsupported | | `automatic_tax` | ✓ Supported | ✓ Supported | | `items.prices` | ✓ Supported | - Unsupported | | `billing_thresholds` | ✓ Supported | ✓ Supported | サブスクリプションの `metadata` に対する更新は、関連付けられたサブスクリプションスケジュールに反映されません。 ## ユースケース 定期支払いスケジュールについて説明するため、The Pacific という架空の新聞会社の例を紹介します。この新聞社は 2 つのサブスクリプションオプションを提供しています。 - 「印刷版」では、顧客は紙に印刷された新聞を受け取ります。 - _デジタル版_では、顧客は The Pacific の Web サイト上の会員専用コンテンツにアクセスできます。 両方のサブスクリプションともに、請求は月次です。以下の定期スケジュールのオプションをご覧ください。 ### 将来の日付でサブスクリプションを開始する デフォルトでは、印刷版の新しいサブスクリプションは翌月の 1 日に開始されます。これを行うには、`start_date` を将来の日付に設定します。以下のコードは、将来に開始されるサブスクリプションを作成します。 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d customer="{{CUSTOMER_ID}}" \ -d start_date=1690873200 \ -d end_behavior=release \ -d "phases[0][items][0][price]"={{PRICE_PRINT}} \ -d "phases[0][items][0][quantity]"=1 \ -d "phases[0][duration][interval]"=month \ -d "phases[0][duration][interval_count]"=12 ``` ### サブスクリプションを遡及適用する 顧客がデジタルプランに登録すると、The Pacific はそのサブスクリプションを現在の月の 1 日まで遡及適用します。この遡及適用により、過去の期間に対しても請求できるようになるほか、デジタル版の登録者は Web サイトにすぐにアクセスできるようになります。 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d customer="{{CUSTOMER_ID}}" \ -d start_date=1688194800 \ -d end_behavior=release \ -d "phases[0][items][0][price]"={{PRICE_DIGITAL}} \ -d "phases[0][items][0][quantity]"=1 \ -d "phases[0][duration][interval]"=month \ -d "phases[0][duration][interval_count]"=12 ``` ### 既存のサブスクリプションにスケジュールを追加する The Pacific で、元の顧客がスケジュールが設定されていないサブスクリプションを利用していることが発覚したと仮定します。これらのサブスクリプションはすでに存在するため、`from_subscription` 属性でサブスクリプション ID を渡してスケジュールを追加できます。この方法でサブスクリプション ID を渡すと、サブスクリプションの現在の請求期間に基づいて 1 つのフェーズを持つスケジュールが作成されます。 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d from_subscription="{{SUBSCRIPTION_ID}}" ``` これらのスケジュールを追加しているときに、一部の顧客が印刷版の登録を決めたため、The Pacific はスケジュールに 2 番目のフェーズを追加して、1 カ月後に印刷版のプランを開始します。[サブスクリプションのアップグレード](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md#upgrading-subscriptions)のユースケースは、このプロセスの例を示したものです。 ### サブスクリプションのアップグレード The Pacific は、最初に印刷版を 1 カ月登録した後、自動的にデジタル版を追加するオプションを提供しています。最初に印刷版を試してからサブスクリプションを続けるかキャンセルするかを決定できるため、一部の顧客はこのオプションを利用しています。 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d customer="{{CUSTOMER_ID}}" \ -d start_date=now \ -d end_behavior=release \ -d "phases[0][items][0][price]"={{PRICE_PRINT}} \ -d "phases[0][items][0][quantity]"=1 \ -d "phases[0][duration][interval]"=month \ -d "phases[0][duration][interval_count]"=1 \ -d "phases[1][items][0][price]"={{PRICE_PRINT}} \ -d "phases[1][items][0][quantity]"=1 \ -d "phases[1][items][1][price]"={{PRICE_DIGITAL}} \ -d "phases[1][items][1][quantity]"=1 \ -d "phases[1][duration][interval]"=month \ -d "phases[1][duration][interval_count]"=11 ``` ### サブスクリプションのダウングレード さらに The Pacific は、印刷版とデジタル版の両方の登録後、印刷版のみの登録にダウングレードするオプションも提供しています。*顧客* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments)はこのオプションを使用して両方の出版物を試し、ニーズに合うかどうかを確認できます。 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d customer="{{CUSTOMER_ID}}" \ -d start_date=now \ -d end_behavior=release \ -d "phases[0][items][0][price]"={{PRICE_DIGITAL}} \ -d "phases[0][items][0][quantity]"=1 \ -d "phases[0][items][1][price]"={{PRICE_PRINT}} \ -d "phases[0][items][1][quantity]"=1 \ -d "phases[0][duration][interval]"=month \ -d "phases[0][duration][interval_count]"=1 \ -d "phases[1][items][0][price]"={{PRICE_PRINT}} \ -d "phases[1][items][0][quantity]"=1 \ -d "phases[1][duration][interval]"=month \ -d "phases[1][duration][interval_count]"=11 ``` ### 定期支払いの変更 Pacific は、広告付きの基本オプションと、広告なしのプレミアムオプションの 2 種類の印刷版のサブスクリプションオプションを提供しています。プレミアムオプションの一部の顧客が、次回の請求期間から広告付きの基本オプションに変更することを決定しました。既存のサブスクリプションを使用してスケジュールを作成し、その後に新しいフェーズとして広告付きの基本オプションでスケジュールを更新します。 #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. Stripe.api_key = '<>' # Create a subscription schedule with the existing subscription schedule = Stripe::SubscriptionSchedule.create({ from_subscription: 'sub_ERf72J8Sc7qx7D', }) # Update the schedule with the new phase Stripe::SubscriptionSchedule.update( schedule.id, { phases: [ { items: [ { price: schedule.phases[0].items[0].price, quantity: schedule.phases[0].items[0].quantity, }, ], start_date: schedule.phases[0].start_date, end_date: schedule.phases[0].end_date, }, { items: [ { price: '{{PRICE_PRINT_BASIC}}', quantity: 1, }, ], duration: { interval: 'month', interval_count: 1, }, }, ], }, ) ``` ### 数量を増やす また、定期支払いの数量の増加をスケジュールすることもできます。以下のスケジュールは、1 カ月という期間でデジタル発行の 1 つのインスタンスを開始します。2 番目のフェーズでは、数量が 11 カ月間、2 に増加します。 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d customer="{{CUSTOMER_ID}}" \ -d start_date=now \ -d end_behavior=release \ -d "phases[0][items][0][price]"="{{PRICE_ID}}" \ -d "phases[0][items][0][quantity]"=1 \ -d "phases[0][duration][interval]"=month \ -d "phases[0][duration][interval_count]"=1 \ -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]"=11 ``` ### クーポンを使用する The Pacific は時折、特別なサブスクリプションを提供しています。以下のスケジュールでは、印刷版を 6 か月間 50% オフで利用できます。このスケジュールの 2 番目のフェーズ (残りの 6 カ月間) でクーポンは削除されます ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d customer="{{CUSTOMER_ID}}" \ -d start_date=now \ -d end_behavior=release \ -d "phases[0][items][0][price]"="{{PRICE_ID}}" \ -d "phases[0][items][0][quantity]"=1 \ -d "phases[0][duration][interval]"=month \ -d "phases[0][duration][interval_count]"=6 \ -d "phases[0][discounts][0][coupon]"="{{COUPON_ID}}" \ -d "phases[1][items][0][price]"="{{PRICE_ID}}" \ -d "phases[1][items][0][quantity]"=1 \ -d "phases[1][duration][interval]"=month \ -d "phases[1][duration][interval_count]"=6 ``` ### 税率を変更する The Pacific は複数の管轄区域で事業を行っており、一部の区域ではサブスクリプションビジネスに対する独自の税率を設けています。これらの管轄区域の 1 つでは、顧客がサブスクリプションを最初に登録した最初の月の請求と、その後の継続請求に対して 2 種類の税率が設定されます。 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d customer="{{CUSTOMER_ID}}" \ -d start_date=now \ -d end_behavior=release \ -d "phases[0][items][0][price]"="{{PRICE_ID}}" \ -d "phases[0][items][0][quantity]"=1 \ -d "phases[0][items][0][tax_rates][0]"=txr_2J8lmBBGHJYyuUJqF6QJtaAA \ -d "phases[0][duration][interval]"=month \ -d "phases[0][duration][interval_count]"=1 \ -d "phases[1][items][0][price]"="{{PRICE_ID}}" \ -d "phases[1][items][0][quantity]"=1 \ -d "phases[1][items][0][tax_rates][0]"=txr_2J8lmBBGHJYyuUJqF6QJtbBB \ -d "phases[1][duration][interval]"=month \ -d "phases[1][duration][interval_count]"=11 ``` ### スケジュールからサブスクリプションをリリースする ステータスが `not_started` または `active` の場合、スケジュールからサブスクリプションを[リリース](https://docs.stripe.com/api/subscription_schedules/release.md)することができます。サブスクリプションをリリースするとそのサブスクリプションは残りますが、スケジュールや残りのフェーズは削除されます。 ```curl curl -X POST https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTIONSCHEDULE_ID}}/release \ -u "<>:" ``` ### スケジュールとサブスクリプションをキャンセルする サブスクリプションスケジュールにアクティブなサブスクリプションが含まれる場合は、それとそれに関連するサブスクリプションも直ちにキャンセルされます。サブスクリプションスケジュールは、ステータスが `not_started` または `active` の場合にのみキャンセルできます。 ```curl curl -X POST https://api.stripe.com/v1/subscription_schedules/{{SUBSCRIPTIONSCHEDULE_ID}}/cancel \ -u "<>:" ``` ### 請求サイクルの起点をリセットする The Pacific では、長年の印刷版の顧客に対し、毎月、顧客が最初に購読を開始した日に請求しています。この日は、請求サイクルの起点です。 このような顧客がデジタル版に移行すると、The Pacific は移行日を翌月の 1 日にスケジュールします。また、請求サイクルの起点も同じ日にリセットします。 以下のサンプルコードを使用してサブスクリプションを作成することにより、請求サイクルの起点がリセットされることを確認できます。ダッシュボードでサブスクリプションを確認すると、デジタル版が 1 日に開始されるとすぐに顧客に次回の請求書が請求されるようにスケジュールされていることがわかります。 起点をリセットしない場合の動作を確認するには、請求サイクルの起点を `phase_start` に設定する行を削除して、サンプルコードを再度実行します。この行がないと、取引が 1 日に発生するにもかかわらず、ダッシュボードの次回の請求書は、本日から丸 1 カ月経過してから請求されます。 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d customer="{{CUSTOMER_ID}}" \ -d start_date=now \ -d "phases[0][items][0][price]"={{PRICE_PRINT}} \ -d "phases[0][items][0][quantity]"=1 \ -d "phases[0][end_date]"=1690873200 \ -d "phases[1][items][0][price]"={{PRICE_DIGITAL}} \ -d "phases[1][items][0][quantity]"=1 \ -d "phases[1][duration][interval]"=month \ -d "phases[1][duration][interval_count]"=11 \ -d "phases[1][billing_cycle_anchor]"=phase_start ``` ### 分割支払い区分 分割払いプランを使用すると、顧客は、設定された期間の支払いを、全額を支払い終えるまで分割して支払うことができます。たとえば、The Pacific が新しい印刷機を購入する際、古い印刷機を他の出版会社に販売します。小規模の出版会社は、全額を最初に支払う資金的な余裕がないことが多いため、分割払いを使用します。 ほとんどの印刷機について、The Pacific は月あたり 1,000 ドルを請求するため、再利用可能な価格が作成されます。 ```curl curl https://api.stripe.com/v1/prices \ -u "<>:" \ -d unit_amount=100000 \ -d currency=usd \ -d product=prod_Hh99apo1OViyGW \ -d "recurring[interval]"=month ``` 印刷機の型、モデル、使用年数に応じて、The Pacific が請求する金額は異なります。この例では、1 カ月当たり 1,000 ドルを 6 カ月間請求し、合計 6,000 ドルを請求します。 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d customer="{{CUSTOMER_ID}}" \ -d start_date=now \ -d end_behavior=cancel \ -d "phases[0][items][0][price]"="{{PRICE_ID}}" \ -d "phases[0][items][0][quantity]"=1 \ -d "phases[0][iterations]"=6 ``` `iterations` の数に価格の期間を乗じて顧客に対する請求回数 (この例では 6 回の月次支払い) が決定されます。`end_behavior` は、最後の繰り返し終了後にサブスクリプションがどのようになるかを決定します。分割払いプランでは、サブスクリプションは必要なくなるため、`end_behavior` は `cancel` に設定されます。 まれに、The Pacific が請求する金額が通常の 1,000 ドル/月よりも少ない場合があります。この場合、`price_data` を使用して 1 回限りの使用の価格を作成します。この例では、500 ドルの価格を作成し、6 カ月間、毎月請求します。 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -d customer="{{CUSTOMER_ID}}" \ -d start_date=now \ -d end_behavior=cancel \ -d "phases[0][items][0][price_data][currency]"=usd \ -d "phases[0][items][0][price_data][product]"=prod_Hh99apo1OViyGW \ -d "phases[0][items][0][price_data][recurring][interval]"=month \ -d "phases[0][items][0][price_data][unit_amount]"=50000 \ -d "phases[0][items][0][quantity]"=1 \ -d "phases[0][iterations]"=6 ```