比例配分

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

比例配分の仕組み

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

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

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

比例配分と割引

All invoice items that are prorations (prorations=true) are set to discountable=false. Discounts applied to an invoice containing prorations are only applied to invoice items and invoice line items that aren’t prorations. Any discounts previously applied to the subscription and affecting the amount of the proration are reflected in the proration invoice item’s amount.

Non-prorations show discount adjustments in 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 日に毎月 のサブスクリプションを作成します。

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 日に、比例配分を作成せずにサブスクリプションを月額 にアップグレードします。

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

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

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

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

curl https://api.stripe.com/v1/subscriptions/sub_123 \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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_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"

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