--- title: "Spend limits, alerts and automatic top-up" description: "Cap and watch usage spend: spend limits and tiers, alerts, credit runway, automatic top-up, early usage invoices, a rate-change preview and a usage widget." canonical_url: "https://twominutebilling.com/help/guides/usage-and-ai-billing/spend-limits-and-auto-top-up" --- # Spend limits, alerts and automatic top-up > Cap and watch usage spend: spend limits and tiers, alerts, credit runway, automatic top-up, early usage invoices, a rate-change preview and a usage widget. 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](https://twominutebilling.com/help/developers/recipes/spend-limits-and-auto-top-up#show-usage-in-your-app). A browser can show the data only from an allowed origin. ## Related - [Prepaid credits](https://twominutebilling.com/help/guides/usage-and-ai-billing/prepaid-credits) - [Meters and rate cards](https://twominutebilling.com/help/guides/usage-and-ai-billing/meters-and-rate-cards) - [Usage pricing](https://twominutebilling.com/help/guides/usage-and-ai-billing/usage-pricing) - [Bill from the AI model price list](https://twominutebilling.com/help/guides/usage-and-ai-billing/model-price-list) - [Spend limits, alerts and automatic top-up with the API](https://twominutebilling.com/help/developers/recipes/spend-limits-and-auto-top-up) - [Prepaid AI credits with the API](https://twominutebilling.com/help/developers/recipes/prepaid-ai-credits) - [Bill AI tokens with the API](https://twominutebilling.com/help/developers/recipes/bill-ai-tokens) ## Sitemap See the full [sitemap](https://twominutebilling.com/sitemap.md) for all pages.