Spend limits, alerts and automatic top-up
Usage can grow faster than anyone planned. These controls keep it in check: a spend limit stops or flags usage at an amount, an alert warns before that, automatic top-up buys more credit before it runs out, and early usage invoices bill large usage before the period ends.
Every control is off until you create the first one. Spend is rated usage before tax and before credit, so a limit means the same thing whether credit or an invoice pays for the usage.
The controls for one customer are on the customer page: select View usage controls on the Usage controls card. Controls for the whole business are in Settings → Usage controls.
Set a spend limit
Open the customer's usage controls
Open the customer, select View usage controls, and select Create limit under Spend limits.
Select what the limit applies to
Under Limit, select All usage of this customer or One subscription. Then select the Interval and the Amount.
Select what happens at the limit
Stop new requests makes the access check refuse new requests until the interval resets. Send a notification only refuses nothing.
| Interval | Resets |
|---|---|
| Day | Each day, in your business time zone. |
| Week (Monday to Sunday) | Each Monday. |
| Calendar month | On the 1st, in your business time zone. |
| Billing period | At each renewal of the subscription. |
A shorter interval cannot have a higher limit than a longer one: a weekly limit above the monthly limit is refused when you save.
The access check is the call your app makes before each request. A limit with Stop new requests refuses when the spend in the interval, plus open holds, plus the estimate of the new request, is more than the limit. Usage is never refused when your app sends it, so usage that was already sent is billed.
When spend reaches a limit, with either setting, we send the spend_limit_reached webhook event
once for each interval. To email the customer too, turn on Spend limit reached in
Settings → Emails. It is off until you switch it on.
The Spend limits table shows each limit with what is Used in the current interval, Reached when the limit is reached, and who set it (You or Customer).
Limits your customer sets
In the customer portal, the Usage limits section shows your limits as Set by your provider. The customer can add a limit of their own with Add a spend limit, change it, or delete it. A customer limit always stops new requests, and it can never be higher than your limit for the same scope and interval. When both exist, the lower one applies.
Raise limits as customers pay
A limit tier raises a customer's limits when their lifetime paid amount reaches a level. A customer who has paid you more over time can spend more.
Open Settings → Usage controls and select Create tier under Limit tiers. Select the Currency, the Lifetime paid level, and the new limit for one or more intervals. You can have up to 10 tiers for each currency.
- Lifetime paid is the successful payments less the successful refunds.
- A tier never goes down. A refund after the customer reached a tier does not take it away.
- The higher of the customer's own limit and their tier applies. If you change the customer's limit after they reached the tier, your new limit applies, even when it is lower.
- When you delete a tier, customers who reached it keep it. No new customer reaches it.
Warn before the limit
An alert sends a notice when a value crosses a threshold. On the customer's usage controls, select Create alert. For every subscription to a plan, use Plan alerts in Settings → Usage controls: a plan alert also applies to new subscriptions.
| Watch | Thresholds in | Counted over |
|---|---|---|
| Usage quantity (of one meter) | Units, or Percent of the feature limit | The Interval you select |
| Spend | Amount, or Percent of the spend limit | The Interval you select |
| Credit balance | Amount, or Percent of the credit given | The calendar month |
| Credit runway | Days left | The calendar month |
Enter several Thresholds at once, for example 50, 80, 100. Select Send an email to the customer to email their billing address when a threshold fires.
Each threshold has a state:
| State | Means |
|---|---|
| Armed | Not crossed in this period. |
| Triggered | Crossed. It fires once in each period, and one large jump fires every threshold it passes. |
| Resolved | The value went back, for example after a top-up or voided usage, or the period ended (Period ended). |
The alert table shows each threshold with its Last value, when it Fired and when it Resets.
See the credit runway
The Credit runway card estimates how long the customer's credit lasts at the current rate. It shows the Balance, the Usage per day (last 7 days), the date it Runs out on about, and what Automatic top-up can still add this month, which the estimate includes.
The rate per day is the spend of the last 7 days divided by 7. With less than 24 hours of usage, the card shows "Not enough usage to estimate". The customer sees the same runway in the portal.
Top up credit automatically
Automatic top-up buys credit for the customer when the balance falls to an amount, or on a schedule. The credit is added only after the payment succeeds. There is one setup for each customer and currency.
On the Automatic top-up card, select Set up:
| Field | What to set |
|---|---|
| When | When the balance falls to an amount (with the Balance), or On a schedule: Every week on a day, or Every month on a Day of the month (1 to 31; in a shorter month, the last day). |
| How much | Add a fixed amount, or Fill up to a balance. |
| Monthly limit | The most we buy in one calendar month. Required. |
| Top-ups per day | 1 to 10, default 3. |
| Payment method | One method, or The customer's payment methods, in their order. |
| Tax on the credit | Tax at purchase or Tax when the credit is used. |
| Priority | 0 to 100. Credit with a lower number is used first. |
| Credit expires after (months) | Leave empty for no expiry. |
With a fixed amount, a top-up buys enough multiples of the amount to bring the balance above the threshold. Each purchase also stays inside the Purchase limits in Settings → Credits, and inside what is left of the monthly limit. When the monthly limit has no room, the top-up is skipped until the next month.
Recent automatic top-ups lists each purchase with its status (Notice sent, Charging, Payment pending, Succeeded, Failed, Cancelled), its amount, when it charges and its invoice.
When a top-up is declined
If the payment is declined, we void its invoice, turn automatic top-up off and email the customer (the Automatic top-up failed email). We do not try again. The card shows "The last payment was declined." When the customer has updated their payment method, select Turn on.
Turn off stops automatic top-up. A top-up that already has a notice out is cancelled.
Mandates that need a notice before each debit
Some mandates, such as recurring payments in India, need a notice to the payer before each debit. On these, the notice goes out first and the charge can happen 26 to 49 hours later on Indian gateways (10 days for a US bank account), by payment gateway. Until the credit arrives, the customer can run out.
So the threshold must cover that time at the current usage. When you save, we refuse a threshold that covers less, and the message gives the amount that is enough. For example, with a 26-hour notice time and usage of ₹12,000 a day, the threshold must be at least ₹13,000. The Covers line shows how many hours of usage the threshold covers now.
If usage grows past what the threshold covers, the card warns you and we send the
credit_auto_topup_threshold_low webhook event, at most once a week. We never change the
threshold for you.
A card or UPI mandate in India can pay at most ₹15,000 without the payer, so each top-up on one is at most ₹15,000. A setup that needs more is refused. Lower the amount, or use a netbanking mandate.
Invoice usage early
For usage that grows large inside a period, raise an invoice each time a subscription's unbilled usage reaches an amount, instead of one large invoice at the end.
Set an amount on the plan
Open the plan in Product Catalog. On the Invoice usage early card, set the Unbilled usage amount for each currency. Every subscription to the plan uses it.
Change it for one subscription
On the subscription page, the Invoice usage early card shows the amount that applies. Select Invoice early at its own amount or Do not invoice early. Use the plan setting goes back to the plan's amount.
We check about one minute after usage arrives. Each early invoice has the chip Interim usage invoice and is collected like any other invoice. Credit pays its usage lines before tax, as on any period invoice.
Each usage line on an early invoice shows the usage to date, what was billed before, and this invoice, for example: "Usage to date $1,240.00 · billed before $600.00 · this invoice $640.00".
At the end of the period, the final invoice bills the rest. All the invoices together bill exactly what one invoice would have billed:
- Discounts and the minimum spend apply only on the final invoice.
- If the final amount is less than the early invoices billed, for example after voided usage, we credit the difference on the early invoices with a credit note "Usage adjustment for this period".
- Usage whose amount can go down as it grows bills only at the end of the period: volume pricing, and meters that bill the last, lowest or average value. The plan card lists those prices.
Preview a rate change
Before you change a usage rate, see what it would cost your customers. Open the usage price and select Preview a rate change. Change the rates or tiers, then select Preview.
The preview re-rates each customer's last closed period at the new rates. It shows the number of Customers, the total Now and At the new rates, and the Change, then one row per customer, largest increase first. Tax, discounts and credit are not included. Customers with no closed period yet are left out.
The preview changes nothing. To change the rates, edit the price. It is available on usage prices that bill from a rate, not on prices that bill from the model price list or from the cost on each event.
Show usage in your app
The usage widget shows a customer their balance, runway, usage this period, estimated bill and limits, inside your own app.
Allow your app's origin
In Settings → Usage controls, under Usage widget, enter your app's address in Allowed
origins, one per line, for example https://app.example.com. Use https, except for
http://localhost. You can add up to 20. Select Save origins.
Copy the snippet
Copy the Snippet from the same card into your app's page.
Create a token from your backend
Your backend creates a token for the signed-in customer through the API. The token reads only that customer's usage and stops working after 15 minutes. See the developer recipe.
A browser can show the data only from an allowed origin.
Related
Prepaid credits
Sell and give prepaid credit for usage: credit units, credit packs, plan credits with rollover, tax before or after credit, blocking, overdraft and holds.
Ask Billy
Billy answers questions about your billing from your own data, checks every figure, shows you where to act, and prepares changes that you confirm.