> 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/dashboard/auto-topup.md).

# 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**.