従量課金レガシー

サブスクリプションのトライアル期間中に、従量課金ベースで請求できます。トライアル期間中に発生した使用量は、通常の請求サイクルの総額には含められません。トライアル期間の終了後に使用量が発生し、それが次回の請求サイクルの終了時に請求されます。

トライアル期間とサブスクリプションの詳細をご覧ください。

Webhook とトライアル

システムでトライアルステータスの変更に関連するウェブイベントの監視と処理が適切に行われていることを確認します。

トライアルが終了し、サブスクリプションが trialing から active に移行する数日前に、customer.subscription.trial_will_end イベントを受信します。このイベントを受信したら、顧客に支払い方法の指定があり、請求可能な状態であることを確認します。必要に応じて、請求が行われることを顧客に通知します。

サブスクリプションと Webhook の詳細をご覧ください。

従量課金を使用すると、請求期間中の使用量に応じて顧客が支払う価格が変動します。請求期間を変えると、サブスクリプションのサービス期間の終了が早まり、短縮された請求期間中に発生した使用量に対して顧客に請求することになります。

キャンセルされたサブスクリプションを、再びアクティブにすることはできません。代わりに、顧客から更新された請求先情報を収集し、顧客のデフォルトの支払い方法を更新して、既存の顧客レコードから新しいサブスクリプションを作成します。

cancel_at_period_end を使用してサブスクリプションのキャンセルを予定している場合、cancel_at_period_end を false に更新することで、期間の終了時まではいつでもサブスクリプションを再度有効にできます。最終的な請求書には、請求期間の終了時にサブスクリプションがキャンセルされたときに測定された使用量も含まれます。

比例配分 (日割り / 秒割り計算)

顧客がサブスクリプションを変更すると、多くの場合、支払う金額の調整が発生します。この調整は比例配分と呼ばれます。create preview invoice (請求書プレビューの作成) エンドポイントを使用して、調整後の金額を顧客に表示できます。

フロントエンドで、請求書のプレビューの情報をバックエンドのエンドポイントに渡します。

function createPreviewInvoice(
  customerId,
  subscriptionId,
  newPriceId,
  trialEndDate
) {
  return fetch('/create-preview-invoice', {
    method: 'post',
    headers: {
      'Content-type': 'application/json',
    },
    body: JSON.stringify({
      customerId: customerId,
      subscriptionId: subscriptionId,
      newPriceId: newPriceId,
    }),
  })
    .then(response => {
      return response.json();
    })
    .then(invoice => {
      return invoice;
    });
}

バックエンドで、フロントエンドから呼び出すエンドポイントを定義します。請求書のプレビューを作成して、プレビューする変更を渡します。この例では、以前の価格 ID のサブスクリプションアイテムを削除し、使用量をクリアし、新しい価格 ID を追加する必要があります。これらの変更は実際には適用されず、プレビューの表示を定義するだけです。

# 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'

post '/create-preview-invoice' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  subscription = Stripe::Subscription.retrieve(data['subscriptionId'])

  invoice =
    Stripe::Invoice.create_preview(
      customer: data['customerId'],
      subscription: data['subscriptionId'],
      subscription_details: {
        items: [
          { id: subscription.items.data[0].id, deleted: true, clear_usage: true },
          { price: ENV[data['newPriceId']], deleted: false }
        ]
      }
    )

  invoice.to_json
end

請求しきい値を使用することにより、サブスクリプションサービス期間で顧客の未払いの使用量が特定の金額または使用量のしきい値に達した際に請求書を発行でき、また必要に応じてサブスクリプションの請求サイクルのアンカーをリセットすることもできます。請求書または決済の期間の途中で未払い金額や商品消費を制限するための予防措置が必要な場合には、請求しきい値の使用を検討してください。

サブスクリプションに金額のしきい値を追加する

通常の場合、しきい値の金額は販売商品の単価の倍数に設定します。

金額しきい値を低く設定すると、顧客は使用量の単位ごとに請求書を受け取ることになり混乱を招くおそれがあります。

この値は、最小通貨単位に使用される正の整数です (1 USD を請求する場合は 100 セント、小数点以下のない通貨 (日本円) で 100 円を請求する場合は 100)。値は 50 通貨単位以上にする必要があります。

サブスクリプションを作成または更新する際に、ダッシュボードで金額のしきい値を設定することもできます。

curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "billing_thresholds[amount_gte]"=10000 \
  -d "billing_thresholds[reset_billing_cycle_anchor]"="false"

サブスクリプションアイテムに使用量のしきい値を追加する

金額のしきい値の場合と同様に、請求書の作成頻度を抑えるため、使用量のしきい値は使用量の 1 ユニットよりも大きくすることをお勧めします。こうすることで、請求書の作成頻度を抑えることができます。Stripe では現在、ダッシュボードで使用量のしきい値を設定することはできません。

curl https://api.stripe.com/v1/subscription_items/si_CFhSgkWb0MyTWg \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "billing_thresholds[usage_gte]"=2000

しきい値と請求サイクルの起点

顧客の使用量がしきい値に達したときに、そのサブスクリプションの請求サイクルの起点に変化があるわけではありません (デフォルト設定)。たとえば、月次のサブスクリプションの途中でしきい値に達した場合には、そのサブスクリプションは、しきい値のないサブスクリプションと同様にその月の末日にリセットされます。

この動作を変更して、しきい値に達すると請求サイクルの起点がリセットされるようにすることができます。そうすることにより、サブスクリプションが月末に本来のロールオーバーポイントに達したときと同様の方法で、しきい値への到達を効率的に処理できます。

curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "billing_thresholds[reset_billing_cycle_anchor]"="true"

従量制のサブスクリプションに aggregate_usage=last_ever が設定されている場合は、reset_billing_cycle_anchor=true を使用できないのでご注意ください。

しきい値と段階制料金

段階は、しきい値のある請求書全体で管理されます。しきい値のないサブスクリプションと同様に、段階は請求期間の終了時にのみリセットされますが、しきい値に達したときに請求サイクルの起点をリセットするようにサブスクリプションを設定することもできます。

たとえば、広告インプレッションに対して graduated 段階構造が設定された、広告プラットフォームを運営しているとします。

使用量は実際の使用が発生した後に請求されるため、新しい顧客に対するしきい値は暫定的に 100 USD にします。このスキームでは、最初の 1 万回のインプレッションまでは 200 インプレッションごとに顧客に請求します (200 x 0.50 USD = 100 USD)。顧客のインプレッションが 1 万回を超えると、250 インプレッションごとに顧客に請求します (250 x 0.40 USD = 100 USD)。これが請求期間の最後まで続き、この最後の時点で未請求の使用量が請求され、サブスクリプションと段階がリセットされます。

しきい値に達したときに段階をリセットするには、サブスクリプションの設定で使用量が設定したしきい値に達したときに請求サイクルの起点がリセットされるようにする必要があります。

数量ベースの段階

数量ベースの段階は、特定の使用量の料金を定義する段階的な階層とは異なり、すべての使用量ユニットの料金を定義します。一部の料金体系モデルでは、段階が上がるたびに単価が下がる数量ベースの段階を使用しています。このようなモデルを使用することで、顧客の使用量の増加を促すことができます (例: 広告インプレッション、ストレージのギガバイト数など)。

これをしきい値と組み合わせた場合、この料金体系モデルでは以下の状況でマイナス金額のラインアイテムを含む請求書が生成されることがあります。

1. しきい値のある請求書がすでに発行されています。
2. その後の使用量は低い単価で請求されます。

たとえば、以下の段階があるとします。

顧客が 10,000 ユニットを使用すると、請求書の合計は 5,000 USD (10,000 x 0.50 USD = 5,000 USD) になります。その後さらに使用を続けることで、「すべて」の使用量が、低い単価である 0.40 USD で請求されます。このため、顧客がもう 1 ユニット使用すると、請求書は 4,000.40 USD に「減少」します (10,001 x 0.40 USD = 4,000.40 USD)。

サブスクリプションにしきい値がない場合、Stripe は請求期間の終了時に 4,000.40 USD の請求書を発行することになります。

5,000 USD の金額しきい値が存在する場合に、どのようにしてマイナスの請求が発生するのかを確認してみましょう。このシナリオでは、顧客の使用量が 10,000 ユニットに達すると Stripe が請求書を発行します。

顧客がもう 1 ユニット使用すると、請求書の合計は 4,000.40 USD (10,001 x 0.40 USD = 4,000.40 USD) に減少します。ただし、顧客がそれ以上 1 ユニットも使用しなければ、999.60 USD の「超過支払い額」が生じます (5,000 USD - 4,000.40 USD = 999.60 USD)。請求期間の最後に、Stripe はこの金額を顧客の残高に加え、将来の請求書の支払いに充当します。

顧客が使用を続けたと仮定します。この使用量のコストは、顧客が 12,500 ユニットを使用すると、再び 5,000 USD に達します (5,000 USD ÷ 0.40 USD = 12,500)。ただし、前回の支払いの 5,000 USD がこの使用量に充当されるため、請求書は発行されません。

Stripe は、合計使用量が 25,000 ユニット (合計費用が 10,000 USD) に達するか、請求期間の終了まで (どちらか早く発生した方)、請求書を発行しません。以下の表は、使用量が 25,000 ユニットに達した場合に発行される 2 種類の請求書に表示されるラインアイテムを示しています。

請求書 1

請求書 2

制限と注意事項

• しきい値は、トライアルのサブスクリプションには適用されません。
• 金額しきい値は、使用量ベースのサブスクリプション項目の定額料金の合計より大きくなければなりません。
• サブスクリプションの終了までの 24 時間は、Billing しきい値が評価されません。これは、同じ日に複数の請求書を受け取った顧客の混乱を防ぐのに役立ちます。
• サブスクリプションに設定できる金額のしきい値は 1 つのみです。
• サブスクリプションアイテムに設定できる使用量のしきい値は 1 つのみです。
• 使用量の報告はリアルタイムで行われるため、指定されたしきい値に達した瞬間に請求書が発行されるとは限りません。請求金額または使用量が指定のしきい値よりも若干高くなる場合があります。
• 金額のしきい値に達したかどうかの判断に使用される金額に税金は含まれませんが、割引や該当する比例配分は含まれます。
• サブスクリプションで、last_ever 総計モードが使用されている場合は、reset_billing_anchor オプションを有効にできません。

使用量に基づく料金体系モデルは、計測しているユニットが厳密には合計に従わない状況にも適用できます。

たとえば Typographic は、書き込まれたワード数に基づき課金を行う、コピーライティングサービスを提供しています。Typographic は、コピーライティングサービスの使用量に応じた料金に、定額の月額料金を加算した額を、月末に顧客に請求します。Typographic は、1 カ月あたりできるだけ多くのワード数を、各顧客に請求をしたいと考えています。これは、aggregate_usage パラメーターを使用して設定できます。

curl https://api.stripe.com/v1/prices \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d nickname="Copywriting service" \
  -d product={{PRODUCT_ID}} \
  -d unit_amount=10000 \
  -d currency=usd \
  -d "recurring[interval]"=month \
  -d "recurring[usage_type]"=metered \
  -d "recurring[aggregate_usage]"=max

顧客が 6 月 1 日に、2,000 ワード書き込み、さらに 6 月 15 日に 1,000 ワード書き込みました。その後で、6 月 20 日に最初の 2,000 ワードのうちの 1,000 ワード分のクレジットが提供されたとします。この場合、月末の請求金額は 200 USD になります (この月の最大使用量が 2,000 ワードで、ワード単価が 0.10 USD)。

aggregate_usage パラメーターは、サブスクリプションでの使用量記録の処理方法を決定します。このパラメーターには以下のオプションがあります。

• sum: (パラメーターを指定しない場合に渡される) デフォルト値。合計請求額は、請求期間の全使用量の記録の合計に従います。
• last_during_period: 合計請求額は、請求期間の最新の使用量記録に従います。請求期間中に使用が記録されなかった場合は、使用量 0 の使用量に応じた合計請求額になります。
• last_ever: 合計請求額は、提供された最新の使用量記録に基づきます。現行の請求期間中に使用が記録されなかった場合、Stripe は以前の使用量記録を探します。使用量記録が見つからない場合は、合計請求額は使用量 0 に従います。
• max: 合計請求額は、請求期間の最大の使用量記録に従います。請求期間中に使用が記録されなかった場合は、0 の使用量に応じた合計請求額になります。

どのオプションを選択するかは、使用量の処理方法によって異なります。また、使用量の記録方法を表示するために、Usage Record API の action パラメーターの値も設定します。

curl https://api.stripe.com/v1/prices \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "currency"="usd" \
  -d "recurring[interval]"="month" \
  -d "recurring[usage_type]"="metered" \
  -d "product_data[name]"="Gold special" \
  -d "nickname"="Gold special price" \
  -d "unit_amount"=3000

サブスクリプションを作成する場合

• quantity を渡さないでください。
• サブスクリプションアイテム の ID は必ず記録してください。この値を Usage Record API に渡して使用量を報告します。

単価をかける前に使用量を集計するには、transform_quantity オプションを使用します。これは、料金の合計を求める前に、さまざまな数量や使用量を報告するのに便利です。

Typographic は提供商品を拡大してカスタムフォントデザインサービスを追加することにしました。カスタムデザインは労働集約的であるため、カスタマイズのレベルに応じて追加料金 (別の Product) を請求します。デザイナーはカスタマイズの実行に要した時間を正確に記録しますが、Typographic の顧客への請求は分単位では行われません。分単位ではなく、同社はカスタマイズに要した時間が 1 時間未満であっても 1 時間単位で請求します。

まず、フォントカスタマイズ用商品を作成します。

curl https://api.stripe.com/v1/products \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d name="Font Customization Service" \
  -d unit_label=Hours

次に、フォントカスタマイズサービス商品の料金を作成します。1 時間単位で 150 USD を請求し、使用時間が 1 時間に満たない場合も切り上げて 1 時間分を請求します。

curl https://api.stripe.com/v1/prices \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d nickname="Customization Per Hour Rate" \
  -d unit_amount=15000 \
  -d currency=usd \
  -d "recurring[interval]"=month \
  -d "recurring[usage_type]"=metered \
  -d product={{FONT_CUSTOMIZATION_SERVICE_PRODUCT_ID}} \
  -d "transform_quantity[divide_by]"=60 \
  -d "transform_quantity[round]"=up

デザイナーが 150 分のカスタマイズを利用した場合、その顧客は 3 時間のカスタマイズ (2 時間 30 分を切り上げ) 分として 450 USD が請求されます。