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.

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

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.