比例配分の仕組み

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

比例配分の作用

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

比例配分では、顧客に対して正確に請求することができますが、支払い額が予測とは異なる場合があります。マイナスの比例配分が顧客に自動的に返金されたり、プラスの比例配分が直ちに請求されたりすることはありません。ただし、手動でそのようにすることは可能です。

比例配分をプレビューし、変更を適用する前に金額を確認できます。

比例配分と割引

discounts からの調整は、比例配分のインボイスアイテムの amount に反映されます。インボイスアイテムレベル またはインボイスラインアイテムレベルの追加割引は、discountable=false が設定されているため比例配分に適用されません。

この動作は、discount_amounts で割引の調整を示す非比例配分とは異なります。

比例配分がトリガーされる内容

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

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

独自の比例配分を手動で作成する

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

• CreateSubscription
• UpdateSubscription
• CreateSubscriptionSchedule
• UpdateSubscriptionSchedule

比例配分が適用されるタイミング

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

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

税金と比例配分

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

比例配分のプレビュー

将来の請求書を取得して、サブスクリプションへの変更をプレビューできます。この 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_4eC39HqLyjWDarjtT1zdp7dc'

# 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.upcoming({
  customer: 'cus_4fdAW5ftNQow1a',
  subscription: 'sub_49ty4767H20z6a',
  subscription_items: items,
  subscription_proration_date: proration_date,
})

次のレスポンス例を展開して、以下を確認できます。

• 36 ～ 38 行目に、以前の価格の未使用時間に対するクレジット。
• 107 ～ 109 行目に、新しい価格で使用した時間に対するコスト。
• 276 ～ 279 行目に、請求書の新しい小計と合計。

{
  "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,
  "billing_reason": "upcoming",

サブスクリプションを変更する前に、この情報を使用して顧客に変更を確認できます。ただし、Stripe は秒単位で比例配分するため、比例配分された金額は、プレビューされてから実際に更新が実行されるまでの間に変化する可能性があります。この問題を回避するには、変更をプレビューする際に請求書に subscription_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_4eC39HqLyjWDarjtT1zdp7dc'

subscription = Stripe::Subscription.update(
  'sub_49ty4767H20z6a',
  {
    items: [
      {
        id: subscription.items.data[0].id,
        price: 'price_CBb6IXqvTLXp3f',
      },
    ],
    proration_date: proration_date,
  }
)

比例配分の無効化

比例配分は proration_behavior パラメーターによって制御され、デフォルトでは create_prorations に設定されています。

proration_behavior パラメーターを none に設定することにより、比例配分をリクエストごとに無効にすることができます。Subscription の今後の比例配分をすべて無効にするパラメーターはありません。比例配分を無期限に無効にする場合は、比例配分を生成するすべてのリクエストに対して proration_behavior を none に設定します。

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

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