比例配分

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

比例配分の仕組み

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

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

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

比例配分と割引

比例配分 (prorations=true) のすべての請求書アイテムは、discountable=false に設定されます。比例配分を含む請求書に適用される割引は、比例配分ではない請求書アイテムと請求書ラインアイテムにのみ適用されます。サブスクリプションに以前適用され、比例配分の金額に影響する割引は、比例配分インボイスアイテムの金額に反映されます。

非比例配分ではdiscount_amounts の割引調整が表示されます。

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

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

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

独自の比例配分額の作成

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

• CreateSubscription
• UpdateSubscription
• CreateSubscriptionSchedule
• UpdateSubscriptionSchedule

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

比例配分は請求期間より前に発生した請求にのみ適用されます。従量課金は比例配分の対象になりません。

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

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

Stripe は更新時のサブスクリプションのステータスに基づいて日割り計算を行います。その際、そのサブスクリプションに対するそれ以前の請求書はすべて支払い済みであると仮定します。顧客が現在の利用期間に対する請求書が未払いのままサブスクリプションを変更すると、未使用の期間に対してより高額なプランの価格に応じたクレジットを受け取ることがあります。このクレジットは、その期間分の支払いをまだ行っていなくても適用されます。

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

1. 元の請求期間を維持する: 新しい請求に対して1 回限りの請求書を手動で作成します。
2. 新しいプランの決済を即時に行い、請求期間をリセットするには: billing_cycle_anchor を now に設定します。詳細については、請求期間を現在時刻にリセットするをご覧ください。

いずれの方法でも、顧客が最終的に古い請求書を支払うと、二重決済につながる可能性があります。これを回避するには、未払いの請求書を無効にします。

税金と比例配分

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

クレジットの比例配分

顧客が請求期間終了前にサブスクリプションをダウングレードするか、サブスクリプションアイテムをキャンセルすると、クレジット比例配分が発行されます。Stripe は、サブスクリプションのbilling_modeを classic または flexible のどちらに設定しているかに応じて、クレジット比例配分の計算に 2 つの方法を提供します。

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

次のシナリオでは、proration_behavior を 10 日間 none に設定して、 の月次サブスクリプションを にアップグレードします。基準となる以前の引き落としはありません。後で、proration_behavior を always_invoice に設定して、サブスクリプションを月次 にダウングレードします。

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

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "items[0][price]"=price_10_monthly

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

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

次に、4 月 11 日に、日割り料金を作成せずに月額 20 USD に サブスクリプションをアップグレード します。

curl https://api.stripe.com/v1/subscriptions/sub_123 \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "items[0][id]"=sub_item_1 \
  -d "items[0][price]"=price_20_monthly \
  -d proration_behavior=none

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

{
  id: "sub_123",
  latest_invoice: {
    id: "in_123"
  }
}

最後に、4 月 21 日に サブスクリプションをダウングレード して月額 10 USD に変更し、日割り料金を作成します。

curl https://api.stripe.com/v1/subscriptions/sub_123 \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "items[0][id]"=sub_item_1 \
  -d "items[0][price]"=price_10_monthly \
  -d proration_behavior=always_invoice

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

# 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 のクーポンが不均等に割り当てられます。

このシナリオを設定するには、2 月 1 日に複数のアイテムとクーポンを含むサブスクリプションを作成します。

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "items[0][price]"=price_20_monthly \
  -d "discounts[0][coupon]"=five_dollars_off

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

{
  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 を使用して の月次サブスクリプションアイテムをキャンセルするには、以下のようにします。

curl https://api.stripe.com/v1/subscription_items/si_10_monthly \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d proration_behavior=create_prorations

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

curl https://api.stripe.com/v1/subscription_items/si_10_monthly \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d proration_behavior=create_prorations \
  -d billing_mode=flexible

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

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

比例配分のプレビュー

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

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

# Set proration date to this moment:
proration_date = Time.now.to_i

subscription = Stripe::Subscription.retrieve('sub_49ty4767H20z6a')

# See what the next invoice would look like with a price switch
# and proration set:
items = [{
  id: subscription.items.data[0].id,
  price: 'price_CBb6IXqvTLXp3f', # Switch to new price
}]

invoice = Stripe::Invoice.create_preview({
  customer: 'cus_4fdAW5ftNQow1a',
  subscription: 'sub_49ty4767H20z6a',
  subscription_details: {
    items: items,
    proration_date: proration_date,
  }
})

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

• 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_details.proration_date 値を渡します。サブスクリプションを更新する際には、サブスクリプションの proration_date パラメーターを使用して、同じ日付を渡します。これにより、比例配分が同時に計算されます。

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

subscription = Stripe::Subscription.update(
  'sub_49ty4767H20z6a',
  {
    items: [
      {
        id: subscription.items.data[0].id,
        price: 'price_CBb6IXqvTLXp3f',
      },
    ],
    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 に設定します。

curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "items[0][id]"="si_1AkFf6LlRB0eXbMtRFjYiJ0J" \
  -d "items[0][price]"="price_CBb6IXqvTLXp3f" \
  -d "proration_behavior"="none"

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