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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helodata.com/account-and-billing/auto-topup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.