# Auto top-up

Auto top-up automatically charges your default payment method when balance drops below a threshold, so traffic requests never fail with `insufficient_balance`. This page is the dashboard setup. For the billing-side concept and refund implications, see [Account → Auto top-up](/account-and-billing/auto-topup.md).

## Enable

1. **Billing → Auto top-up → Enable**.
2. Fill in:
   * **Threshold** — when balance drops below this USD value, trigger
   * **Top-up amount** — how much to charge per trigger
   * **Payment method** — pick from your saved cards
   * **Daily cap** — maximum spend per day (sanity guard)
3. **Save**.

\[screenshot: Auto top-up settings]

### Recommended values

| Workload size     | Threshold | Top-up amount | Daily cap |
| ----------------- | --------- | ------------- | --------- |
| Hobby (<10 GB/mo) | $5        | $20           | $20       |
| Small team        | $50       | $200          | $500      |
| Production        | $500      | $2,000        | $5,000    |

The daily cap is a safety net — without it, an abuse loop (e.g. a buggy scraper hitting traffic limits) could rack up runaway charges.

## What triggers it

Auto top-up is checked **before every billed event**:

* Gateway: each request that would consume traffic
* API: each `POST /orders`
* Renewals: when a subscription renews

If balance < threshold, the gateway pauses **for that request only** while it charges the card, then proceeds. The latency cost is one extra \~2-second card charge on the triggering request, which is why we keep the threshold above zero.

## What if the card fails?

The original request fails with `insufficient_balance`. We:

1. Email you immediately.
2. Mark the payment method as **failing**; the next traffic request triggers a retry with the same card.
3. After 3 failed attempts, the auto top-up is paused until you take action.

If you have a second payment method, mark it **default** while you sort out the first.

## Stop / pause

* **Pause** — temporarily turn off without losing config. Useful while testing.
* **Disable** — remove the config entirely. Re-enable via the same form.

## Top up manually one-shot

If you don't want recurring charges, top up manually:

**Billing → Payment methods → Top up** → pick amount → confirm. The balance is added instantly.

## Auto top-up + subscriptions

Auto top-up exists for **prepaid** balance. Subscriptions (monthly plans) bill directly to your card on the renewal date and don't touch balance unless balance is enough to cover the renewal first.

So an account with a $500/mo subscription **and** auto top-up enabled at $50 threshold will:

1. Have $500 charged to the card on renewal day (subscription)
2. Have +$200 charged separately whenever per-request usage drains balance to $50

## API

```bash
curl -X POST -H "Authorization: Bearer API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "threshold_usd":   50,
       "topup_amount_usd": 200,
       "payment_method_id": "pm_01HX...",
       "daily_cap_usd":    500
     }' \
     https://api.helodata.com/v1/billing/auto-topup
```

## Common pitfalls

* **Threshold too low (e.g. $1)** — by the time the trigger fires, you may already be at zero. Keep the threshold above your worst-case one-second spend.
* **Daily cap too tight** — production workloads can blow through it during a load test. Match the cap to your max acceptable daily spend, not your average.
* **No backup card** — if your only card fails near a renewal, the subscription also fails. Add a backup in **Payment methods**.


---

# 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/dashboard/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.