比例配分

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

比例配分の仕組み

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

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

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

比例配分と割引

割引の調整額は、比例配分された請求書品目の 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_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_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"

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