> For the complete documentation index, see [llms.txt](https://docs.helodata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helodata.com/account-and-billing/auto-topup.md).

# Auto top-up

This page covers the billing-side concept and policy. For the dashboard setup flow see [Dashboard → Auto top-up](/dashboard/auto-topup.md).

## What it is

Auto top-up automatically charges your default payment method when your prepaid USD balance drops below a configured threshold. The credit is added to your account immediately so traffic / API requests don't fail with `insufficient_balance`.

It's the most common pattern for production accounts that don't want operational interruptions.

## How it interacts with invoicing

Each auto top-up charge produces an **invoice** with one line:

```
Top-up — auto, threshold $50                $200.00
```

Same invoice format and treatment as any other paid event — see [Invoices](/account-and-billing/invoices.md).

## How it interacts with refunds

Auto top-up purchases are **refundable for the unused balance only**, under the same conditions as manual top-ups — see [Refund policy](/account-and-billing/refunds.md). You can't refund what you've already burned through proxy traffic.

If you suspect an auto top-up was triggered by abuse (compromised credentials, runaway scraper), file a dispute within 7 days and we'll investigate. Confirmed abuse usually results in a full refund of unconsumed credit.

## Daily cap as protection

The **daily cap** is your insurance against runaway charges:

* Set it to your maximum acceptable daily spend
* We won't auto-top-up beyond the cap, even if balance keeps draining
* If you hit the cap, requests start failing with `insufficient_balance` until the next day or until you raise the cap / top up manually

Without a daily cap, a buggy scraper could potentially charge your card thousands of dollars before you notice. **Always set one.**

## Multi-currency interaction

Auto top-up amounts are denominated in your **default currency** (set in **Address & tax**). If your card is in a different currency, the charge converts at the card's daily rate.

## When auto top-up doesn't help

Auto top-up keeps **balance** funded. It doesn't help:

* **Subscription renewals** — those bill the card directly on renewal day. If the card fails, the subscription enters its own dunning flow (3 retries over 7 days, then suspension).
* **API rate-limit errors** — those aren't about balance.
* **KYC blocks** — those aren't about balance either.

## Failure handling

If the auto top-up charge fails (declined card, fraud check, network):

1. We email you immediately with the decline reason from the card network.
2. The triggering request fails with `insufficient_balance`.
3. The next traffic request retries the same card.
4. After 3 failed attempts the auto top-up is paused; you must re-enable it after fixing the payment method.

If a backup payment method is on file, the second card is tried after the first's 3 retries.

## Accounting integration

For accounting workflows, you typically want:

* All auto top-up events visible as separate invoices (yes — we do that)
* Predictable billing cycles (use **subscriptions** instead of auto top-up if you need fixed monthly bills)
* Aggregated reporting (use [Reports](/api-reference/reports.md) for monthly rollups)

Some teams prefer to **disable auto top-up entirely** and use only subscriptions + monthly invoicing for predictability. That works fine — you just need to size the subscription tier above your monthly traffic.

## Related

* Dashboard setup: [Dashboard → Auto top-up](/dashboard/auto-topup.md)
* Subscriptions: [Subscriptions API](/api-reference/subscriptions.md)
* Refunds: [Refund policy](/account-and-billing/refunds.md)