比例配分

修正後のサブスクリプションの比例配分を処理します。

既存のサブスクリプションを変更する上で最も複雑なのが比例配分です。比例配分では、部分的な利用を反映し、サブスクリプション料金の一定割合を顧客に請求します。このページでは、比例配分がサブスクリプションでどのように作用するのか、また顧客の比例配分を処理する方法について説明します。

比例配分の仕組み

たとえば、サブスクリプションをアップグレードまたはダウングレードすると、比例配分による請求が発生することがあります。顧客が月額 10 USD のプランから 20 USD のオプションにアップグレードした場合、各オプションの使用時間に対して比例配分された金額が請求されます。請求期間の半ばで変更が発生した場合は、顧客は 5 USD の追加請求を受けます (最初の料金の未使用時間分が -5 USD で、新しい料金の使用時間分が 10 USD)。

比例配分は顧客に対して正確に請求することができますが、最終的な支払い額が予想とかい離する場合があります。マイナスの比例配分は自動的に返金されず、プラスの比例配分はすぐには請求されません。ただし、どちらも手動で行うことができます。

比例配分をプレビューして、変更を適用する前に金額を確認できます。クレジットの比例配分の仕組みについては、Stripe のガイドをご覧ください。

比例配分と割引

割引の調整額は、比例配分された請求書品目の amount に反映されます。請求書項目または請求書品目へのその他の割引は、discountable=false が指定されているため比例配分の適用対象外です。

これは、比例配分以外の動作と異なるものであり、discount_amounts に割引の調整額が示されます。

比例配分が発生するシナリオ

デフォルトでは、以下のシナリオで比例配分が発生します。

基本コストの異なる料金への変更
請求頻度の異なる料金への変更
有効なサブスクリプションへのトライアル期間の追加
数量の変更
ライセンス型 (ユーザー単位) のサブスクリプション (各請求期間の開始時に請求が行われるため)

独自の比例配分額の作成

Stripe の外部で計算した比例配分額をサブスクリプションに追加するには、(計算された比例配分額と等しい) マイナスの unit_amount が指定された add_invoice_items を次のエンドポイントに渡します。

比例配分の適用タイミング

比例配分は、請求サイクルの前に発生した支払いにのみ適用されます。従量課金は比例配分の対象にはなりません。

比例配分額は、API がサブスクリプションを更新するとすぐに算出されます。変更の前と後のサブスクリプションのコストを計算するために、現行の請求期間の開始日と終了日が使用されます。

日割り計算と未払いの請求書

Stripe は、更新時のサブスクリプションのステータスに基づいて日割り計算をし、サブスクリプションの以前の請求書がすべて最終的に支払われると仮定します。現期間の未払いの請求書があるときに顧客がサブスクリプションを変更した場合、その期間をまだ支払っていなくても、上位のプランの未使用の期間に対するクレジットを受け取る場合があります。

未払いの期間に対するクレジットを避けるために、サブスクリプションの最新の請求書が未払いの場合は日割り計算を無効にすることができます。サブスクリプションを更新する際は、proration_behavior を none に設定します。次のいずれかの方法を選択します。

元の請求サイクルを維持するには: 新しい支払いに対して手動で 1 回限りの請求書を作成します。
新しいプランに即座に請求し請求サイクルをリセットするには: billing_cycle_anchor を now に設定します。

どちらの方法でも、古い請求書が最終的に支払われた場合に、二重支払いが発生する可能性があります。これを回避するには、未払いの請求書を無効にします。

税金と比例配分

比例配分を行う際の税金の処理については、継続支払いにおける税金の徴収をご覧ください。

クレジットの比例配分

顧客が請求期間の終了前にサブスクリプションをダウングレードしたり、サブスクリプションアイテムをキャンセルしたりすると、クレジットの比例配分が発生します。Stripe では、サブスクリプションの billing_mode 設定に応じて、2 つの方法でクレジットを比例配分 (日割り / 秒割り計算) できます。

比例配分のない計算ロジック

次のシナリオでは、10 USD の月額サブスクリプションが 20 USD にアップグレードされ、proration_behavior が 10 日間 none に設定されます。この計算に適用される以前の引き落としはありません。その後、サブスクリプションは月額 10 USD にダウングレードされ、proration_behavior が always_invoice に設定されます。

このシナリオを設定するには、まず月額 10 USD のサブスクリプションを 2025 年 4 月 1 日付で作成します。

レスポンスには、このサブスクリプション用に作成された請求書が含まれます。

Create subscription response
{
  id: "sub_123",
  latest_invoice: {
    id: "in_123",
    total: 10_00,
    currency: "usd"
    }
}

その後、2025 年 4 月 11 日に、比例配分を作成せずにサブスクリプションを月額 20 USD にアップグレードします。

proration_behavior が none であるため、最新の請求書は変更されません。

Upgrade subscription response
{
  id: "sub_123",
  latest_invoice: {
    id: "in_123"
  }
}

最後に、2025 年 4 月 21 日にサブスクリプションを月額 10 USD にダウングレードし、比例配分を作成します。

billing_mode=classic の比例配分の計算ロジックでは、顧客が月額 20 USD の料金を支払ったことがない場合でも、現在の料金に基づいてクレジットの比例配分が作成されます。顧客が price_20_monthly の料金を支払っていない場合でも、最新の請求書では、20 USD の 3 分の 1 (-6.67 USD) が入金されます。併せて、10 USD の 3 分の 1 (3.33 USD) も引き落とされます。

billing_mode=flexible が指定された計算ロジックでは、サブスクリプション項目に対して最後に請求された料金に基づき、クレジットの比例配分が作成されます。この場合、最新の請求書では、2025 年 4 月 1 日に請求された月額 10 USD の 3 分の 1 (3.33 USD) が入金され、10 USD の料金の 3 分の 1 (3.33 USD) が引き落とされます。クレジットとデビットが相殺されるため、請求書の合計額は 0 USD になります。

前

後

# Default behavior
# billing_mode = classic
{
  id: "sub_123",
  latest_invoice: {
    id: "in_456",
    total: -3_34,
    currency: "usd"
    }
}

# New behavior
# billing_mode = flexible
{
  id: "sub_123",
  latest_invoice: {
    id: "in_456",
    total: 0,
    currency: "usd"
    }
}

複数のサブスクリプション項目に適用されるクーポンの計算ロジック

Stripe は過剰請求を防ぐために、クレジットの日割り計算の amount_off クーポンに重みを付けます。

次のシナリオでは、10 USD と 20 USD の項目が含まれる 25 USD の月額サブスクリプションに、5 USD のクーポンが不均等に割り当てられます。

このシナリオを設定するには、複数の項目を含むサブスクリプションと 1 つのクーポンを 2025 年 2 月 1 日付で作成します。

これにより、次のレスポンスが返されます。

Create subscription with multiple items and a coupon response
{
  id: "sub_123",
  latest_invoice: {
    id: "in_123",
    total: 25_00,
    currency: "usd",
    lines: {
      data: [
      {
        id: "ili_1",
        amount: 10_00,
        price: "price_10_monthly",
        discount_amounts: [{
          discount: "di_a",
          amount: 1_66 }] },
      {
        id: "ili_2",
        amount: 20_00,
        price: "price_20_monthly",
        discount_amounts: [{
          discount: "di_a",
          amount: 3_34
          }]
        },
    ] }
  }
}

billing_mode=classic を使用して月額 10 USD のサブスクリプション項目をキャンセルするには、以下のようにします。

billing_mode=flexible を使用して同じ項目をキャンセルするには、以下のようにします。

デフォルトの動作では、各項目 (2.5 USD) に 5 USD のクーポンが割り当てられ、安い方の項目 (5 USD) がキャンセルされ、2.5 USD の返金が行われます。Stripe は、-0.5 x (10 USD price - 5 USD coupon) = -2.50 USD という式を使用して合計を計算します。

新しい動作では、割引額の全額が比例配分計算に適用されるのではなく、キャンセルされた項目に適用された割引額が反映されます。Stripe は、 -0.5 x (10 USD price - 1.66 USD discount amount) = -4.17 USD という式を使用して合計を計算します。

前

後

# Default behavior
# billing_mode = classic
{
  "id": "sub_123",
  "latest_invoice": {
    "id": "in_456",
    "total": -250,
    "currency": "usd"
  }
}

# New behavior
# billing_mode = flexible
{
  "id": "sub_123",
  "latest_invoice": {
    "id": "in_789",
    "total": -417,
    "currency": "usd"
  }
}

比例配分のプレビュー

請求書プレビューを作成して、サブスクリプションに加えられた変更をプレビューできます。この API コールでサブスクリプションは変更されません。代わりに、渡されたパラメーターのみに基づいて次回請求書が返されます。price または quantity を変更すると、比例配分が行われます。この例では price を変更し、比例配分の計算日を設定しています。

次のサンプルレスポンスを展開すると、以下を確認できます。

36～38 行目: 以前の料金での未使用分に対するクレジット。
107～109 行目: 新しい料金での使用分に対するコスト。
276～279 行目: 請求書の新しい小計と合計。

{
  "id": "upcoming_in_1OujwkClCIKljWvsq5v2ICAN",
  "account_country": "US",
  "account_name": "Test account",
  "amount_due": 3627,
  "amount_paid": 0,
  "amount_remaining": 3627,
  "application_fee_amount": null,
  "attempt_count": 0,
  "attempted": false,

この情報を使用して、サブスクリプションを変更する前に顧客に変更を確認します。Stripe は秒単位で比例配分を行うため、プレビューしてから更新が行われるまでの間に、比例配分額が変わる可能性があります。これを回避するには、変更をプレビューする際に請求書に subscription_proration_date を渡します。サブスクリプションを更新する際は、比例配分が同時に計算されるように、サブスクリプションの proration_date パラメーターを使用して同じ日付を渡します。

比例配分の動作を制御する

比例配分は proration_behavior パラメーターによって制御され、create_prorations、always_invoice、none のいずれかのパラメーターが指定されます。

デフォルトの動作

proration_behavior のデフォルトのパラメーターは create_prorations であり、該当する場合は比例配分された請求書品目が作成されます。このような比例配分の項目は、特定の条件の場合に限り、直ちに請求されます。

比例配分を即時に作成する

サブスクリプションを変更した後、同じ請求サイクルで顧客にただちに請求するには、サブスクリプションの変更時に proration_behavior を always_invoice に設定します。これにより比例配分が計算され、すぐに請求書が生成されます。

比例配分の無効化

リクエストごとに比例配分を無効にしたい場合は、proration_behavior パラメーターを none に設定します。パラメーターを指定しない場合、サブスクリプションの今後のすべての比例配分がオフになります。比例配分を無期限で無効にしたい場合は、比例配分を作成するすべてのリクエストで proration_behavior を none に設定します。

比例配分を無効にすると、次の請求書が生成されたときに、顧客は新しい料金で全額を請求されます。