比例配分

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

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

比例配分の仕組み

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

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

You can preview a proration to view the amount before applying the changes. To learn more about how credit prorations work, read our guide.

比例配分と割引

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

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

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

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

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

独自の比例配分額の作成

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

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

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

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

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

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

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

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

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

税金と比例配分

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

Credit prorations

Credit prorations are issued when customers downgrade their subscriptions or cancel subscription items before the end of their billing period. Stripe offers two approaches for calculating credit prorations, depending on your subscription’s billing_mode setting.

Calculation logic with no prorations

In the following scenario, you upgrade a 10 USD monthly subscription to 20 USD with the proration_behavior set to none for 10 days. There’s no previous debit to base it on. Later, you downgrade the subscription to 10 USD a month with the proration_behavior set to always_invoice.

To set up this scenario, first you create a subscription for 10 USD/month on 2025-04-01:

The response includes the invoice that’s created for this subscription:

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

Then, on 2025-04-11, you upgrade the subscription to 20 USD/month without creating prorations:

The latest invoice remains unchanged because proration_behavior is none:

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

Finally, on 2025-04-21, you downgrade the subscription to 10 USD/month and create prorations:

The billing_mode=classic proration calculation logic creates a credit proration based on the current price, even though the customer never paid the 20 USD/month rate. The latest invoice credits a third of the month for 20 USD (-6.67 USD), even though the customer never paid for the price_20_monthly price. It also debits a third of the month for 10 USD (3.33 USD).

The calculation logic enabled with billing_mode=flexible creates a credit proration based on the last price billed for the subscription item. In this case, the latest invoice credits a third of a month for the 10 USD/month price billed on 2025-04-01 (3.33 USD) and debits a third of the month for the 10 USD price (3.33 USD). The credit and debit cancel out so the invoice total is 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"
    }
}

Calculation logic for coupons applied to multiple subscription items

Stripe weights the amount_off coupon on the credit proration to prevent over-billing.

In the following scenario, a 5 USD coupon is unevenly allocated to a 25 USD monthly subscription for a 10 USD item and 20 USD item.

To set up this scenario, you create a subscription with multiple items and a coupon on 2025-02-01:

Which returns this response:

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
          }]
        },
    ] }
  }
}

To cancel the 10 USD/month subscription item using billing_mode=classic:

To cancel the same item using billing_mode=flexible:

The default behavior distributes a 5 USD coupon to each item (2.5 USD each), canceling the cheaper item (5 USD) and resulting in a refund of 2.5 USD. Stripe calculates the total with the formula -0.5 x (10 USD price - 5 USD coupon) = -2.50 USD

The new behavior reflects the proportional discount applied to the canceled item, rather than potentially applying the full discount amount to the proration calculation. Stripe calculates the total using the formula -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 に設定します。

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

注