Skip to content
Docs

Billing and reporting

Prepaid advertiser wallets

Advertisers who pay up front, the balance on the ledger, manual and invoiced top-ups, low-balance alerts and automatic pausing of offers.

Some advertisers pay before traffic runs. Turn on the prepaid wallet on the advertiser's Wallet tab and their approved revenue is drawn from a balance instead of being invoiced afterwards.

How the balance works

The balance is a ledger account, advertiser_prepaid:{advertiser}:{currency}, in the same double-entry ledger as everything else (see Billing and payouts):

  • a top-up credits it (Dr cash / Cr advertiser_prepaid);
  • every approved conversion of the advertiser draws its revenue from it (Dr advertiser_prepaid / Cr revenue); a reversed approval puts the money back.

Turning the wallet on sets the advertiser's billing mode to prepaid, which is what makes the ledger draw from the wallet. The Wallet tab shows the balance, spend over 7 and 30 days, how many days the balance lasts at that pace, the top-ups and every credit and draw.

Top-ups

  • Money received: book an amount that has arrived (wire, card, anything); it is credited at once.
  • Pro-forma invoice: send the advertiser a pro-forma with a due date (it arrives as an "invoice issued" email). It stays awaiting payment until you press Payment received, then it is credited.
  • Advertisers can also ask for a top-up from their portal (Billing → Top-ups); you receive the request and book it when the money arrives.

Alerts and automatic pausing

Each wallet has an alert threshold and a pause level (default 0):

  • When the balance falls to or below the threshold, the advertiser's users and your team get one alert ("Prepaid balance low"). It is sent again only after the balance has recovered and dipped again.
  • When the balance reaches the pause level and automatic pausing is on, every active offer of the advertiser is paused (reason "prepaid balance used up") and both sides get "Prepaid balance used up".
  • When a top-up lifts the balance above the pause level, exactly the offers the wallet paused resume. Offers you paused yourself stay paused.

The workers check every wallet once a minute; a top-up or a settings change re-checks at once. Pausing and resuming are written to the audit log. Advertisers can switch the wallet emails off in their notification preferences.

Billing → Prepaid wallets lists every wallet with its balance, threshold, state and paused offers.

API

GET/PUT /advertisers/{id}/wallet, GET /advertisers/{id}/wallet/ledger, POST /advertisers/{id}/wallet/topups (method manual or invoice), POST /advertisers/{id}/wallet/topups/{tid}/confirm | cancel, GET /billing/wallets; advertisers read their own wallet with GET /advertiser/wallet.