Auto top-up: stop watching your balance

A prepaid balance has one weak spot: somebody has to remember to refill it. Until today that meant a low-balance email, a trip to the Billing page and a card form, usually at a bad moment. Auto top-up is a new option that does the refill for you, if you want it to.

It is your choice

Auto top-up is off on every account, and it stays off until you turn it on yourself. We never save a card or charge one on our own. If you would rather top up by hand, do nothing: manual top-ups and the low-balance emails work exactly as they did yesterday.

What it does

If you turn it on, you choose two figures on the Billing page: a threshold and an amount. When your balance drops below the threshold, HonkIO charges your saved card for the amount and adds it to your balance. The setting reads like a sentence:

When my balance drops below $10.00, add $25.00.

Your numbers stay active

Number rent comes out of your balance once a month. When the balance cannot cover it, the number is suspended, and a suspended number is eventually released. Losing a number your customers already know is the most expensive way to forget a top-up.

Auto top-up looks ahead. In the 24 hours before rent is due, it checks whether your balance covers the rent. If it does not, it tops up first, even when you are still above your threshold. It does this at most once for each rent date.

Your sends keep going

A message with no balance behind it is refused. With auto top-up on, a balance that crosses your threshold is refilled about a minute later, so a busy afternoon no longer ends in rejected sends.

One caveat, so nobody is surprised: your balance is checked about once a minute, and a large burst can still reach $0 between checks. Pick a threshold that leaves room for your busiest minute.

You stay in charge of your card

• One charge per dip: the amount is always at least the threshold, so a single top-up brings your balance back above it
• Your limits still apply: every charge counts toward your top-up limits, and a charge that would exceed them is skipped
• No retries on a failed card: if a charge fails, auto top-up pauses and we email you. Nothing more is charged until you turn it back on
• A receipt every time: each charge sends an email with the credit, the tax and your new balance
• Off in one click: turn it off on the Billing page and the saved card is removed

Turning it on, if you want it

Open Billing in the dashboard and find Auto top-up. Set your threshold and amount, tick the authorization and pay your first top-up. That payment saves the card, and your bank may ask you to confirm it once. The smallest threshold is $5.00 and the smallest amount is $10.00. Sales tax is added to each charge the same way it is on a manual top-up.

While auto top-up is working, the low-balance warning emails stop, because there is nothing for you to do. If it is ever paused, the warnings come back.

For developers

The settings can only be changed in the dashboard, so an API key can never raise what your card is charged. Reading them is open to any key: GET /v1/auto-topup returns your threshold and amount, the saved card, whether it is paused and why, and the recent attempts.

curl https://api.honkio.ca/v1/auto-topup \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

Two webhook events report each result. account.auto_topup_succeeded carries what triggered the charge, the credit, the tax, the total and your new balance. account.auto_topup_paused carries the reason. The data of a successful top-up looks like this:

{
  "attempt_id": "ata_a1b2c3d4e5f6a1b2c3d4e5f6",
  "trigger": "threshold",
  "amount_cents": 2500,
  "tax_cents": 325,
  "total_cents": 2825,
  "balance_cents": 3100
}

The full rules are in the pricing and limits guide, and the event fields are on the webhook events page.