Auto top-up

This page covers the billing-side concept and policy. For the dashboard setup flow see Dashboard → Auto top-up.

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.

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. 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 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
• Subscriptions: Subscriptions API
• Refunds: Refund policy