アラートとしきい値公開プレビュー

Use alerts to notify you when customers exceed meter usage thresholds, or to trigger an invoice when customers reach a specific billing threshold. You can create alerts that apply to specific customers or all customers.

Create usage alerts in your business workflows, such as the following:

• Email users: Allow customers to configure usage limits, and send an email when they hit their limit.
• De-provision access: Grant customers a free number of usage units to your service, and remove access when they exceed the limit.
• 営業チームにアップセルを通知: セルフサービスのユーザーが使用量のしきい値を超えた場合、企業の販売機会について営業チームに通知します。

Stripe provides a usage alert type called One-time per-customer usage alert. This alert triggers when a customer exceeds the specified usage level for the first time, and only triggers one time per customer, regardless of future usage.

Create usage alerts

You can configure alerts using the Stripe Dashboard or API.

For example, you can create a one-time alert for customers that triggers when they reach 100 API calls. When a customer reaches 100 API calls, you receive a webhook notifying you that the customer has exceeded the threshold.

Create billing thresholds

You can create billing thresholds to issue an invoice when a customer’s accrued usage in a subscription cycle reaches a specific monetary threshold. You can also reset a subscription’s billing cycle anchor when a customer reaches the monetary threshold.

Consider using billing thresholds to limit the amount owed or the products consumed between invoices or charges.

Monetary thresholds

When you add a monetary threshold to a subscription, set the value as a multiple of the cost of one unit of the product being sold. Setting a lower amount for the threshold results in your customers receiving an invoice for every unit of usage.

The value is a positive integer in the smallest currency unit (for example, 100 cents to charge 1 USD, or 100 to charge 100 JPY, a zero-decimal currency). Set the value to at least 50 currency units.

You can set monetary thresholds for a subscription using the Stripe Dashboard or the API.

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

Usage thresholds

When you add a usage threshold to a subscription item, set the value to exceed one unit of usage to prevent frequent invoicing. Stripe doesn’t support setting usage thresholds in the Dashboard.

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

Thresholds and the billing cycle anchor

By default, the billing cycle anchor of a subscription remains unchanged after a customer reaches the usage threshold. If a customer reaches the threshold mid-month of a monthly subscription, the subscription resets at the end of the month, similar to a subscription without thresholds.

You can change the default behavior by configuring the subscription to reset the billing cycle anchor after it reaches the threshold. Stripe treats this configured behavior as if the subscription naturally arrived at its rollover point at the end of the month.

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

しきい値と段階制料金

Stripe maintains tiers across threshold invoices. By default, tiers reset at the end of each billing period. You can change the default behavior by configuring the subscription to reset the billing cycle anchor after it reaches the threshold, similar to a subscription without thresholds.

For example, you run an ad platform with the following graduated tier structure for ad impressions:

Because Stripe bills usage retrospectively, you can set a temporary threshold of 100 USD for new customers. Under this plan, you bill your customer every 200 impressions for the first 10,000 impressions (200 × 0.50 USD = 100 USD). When the customer exceeds 10,000 impressions, they’re billed every 250 impressions (250 × 0.40 USD = 100 USD). This continues until the end of the billing period, at which point you can invoice all usage that wasn’t previously invoiced, and the subscription and tiers reset.

To reset tiers after reaching a threshold, you must configure the subscription to reset the billing cycle anchor after the usage reaches the thresholds that you set.

数量ベースの段階

Volume tiers define the pricing for all units of usage, as opposed to graduated tiers, which define pricing for a specific amount of usage. Some pricing models use volume tiers that decrease the unit cost at each successive tier. You can use these models to incentivize customers to use more of a product (for example, ad impressions, or GB of storage).

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

• しきい値のある請求書がすでに発行されています。
• Subsequent usage gets billed to customers at a lower unit cost.

たとえば、以下の段階制料金構造について考えてみます。

顧客が 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 の請求書を発行することになります。

To demonstrate how negative invoicing can occur, assume you set a monetary threshold of 5,000 USD. In this scenario, Stripe issues an invoice when the customer reaches 10,000 units of usage.

If the customer uses one more unit, the invoice total drops to 4,000.40 USD (10,001 × 0.40 USD = 4,000.40 USD). However, if the customer doesn’t consume more units, they’re owed 999.60 USD (5,000 USD − 4,000.40 USD = 999.60 USD). At the end of the billing period, Stripe credits this amount to the customer’s balance, which we use to pay future invoices.

If the customer continues to accrue usage, the cost of the usage reaches 5,000 USD again when the customer uses 12,500 units (5,000 USD / 0.40 USD = 12,500). However, the previous payment of 5,000 USD covers all of this usage. As a result, we don’t issue an invoice.

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

請求書 1:

請求書 2:

Listen for webhooks

After you configure an alert and start sending usage for that meter, you can listen for webhooks. These events trigger when there’s a status change in Stripe, such as creating a new subscription or invoice.

In your application, set up an HTTP handler to accept a POST request containing the webhook event, and verify the signature of the event.

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

post '/webhook' do
# You can use webhooks to receive information about asynchronous payment events.
# For more information, see https://stripe.com/docs/webhooks.
webhook_secret = ENV['STRIPE_WEBHOOK_SECRET']
payload = request.body.read
if !webhook_secret.empty?

開発中は、Stripe CLI を使用して Webhook をモニタリングし、アプリケーションに転送します。開発アプリの実行中に、新しい端末で以下を実行します。

stripe listen --forward-to localhost:4242/webhook

For production, set up a webhook endpoint URL in the Dashboard, or use webhook endpoints.

制限事項

Consider the following limitations for usage alerts:

• Alerts are only evaluated on usage data reported after alert creation.
• You can create a maximum of 25 alerts for each combination of a specific meter and customer. However, you can create an alert for a specific meter for each of your customers.
• 現在、アラートはテストクロックでは機能しません。

Consider the following limitations for billing thresholds:

• しきい値は、トライアルのサブスクリプションには適用されません。
• Billing thresholds aren’t evaluated in the 24 hours before a subscription ends. This helps limit confusion for a customer who receives multiple invoices on the same date.
• 金額のしきい値は、従量課金のサブスクリプションアイテムの定額手数料の合計費用以上にする必要があります。
• When determining if a monetary threshold has been reached, the value used excludes taxes but includes discounts and billing credits.
• Subscriptions are only allowed a single monetary threshold.
• Subscription items are only allowed a single usage threshold.
• Invoiced amounts or usage might be slightly higher than the specified thresholds because invoices aren’t issued at the exact moment a specified threshold is reached.
• パッケージごとの段階制料金は現在サポートされていません