Prepaid CreditsZero-Balance Actions

Zero-Balance Actions

When a wallet runs out, you choose what happens. The choice is the zero-balance action on the rate plan price, set in the builder under When the balance runs out.

ActionBuilder labelWhat happens
BILL_OVERAGE (default)Bill the overage on the invoiceWhat credits do not cover is invoiced and taxed as usual.
AUTO_TOP_UPTop up automaticallyWhen the projected balance falls to the threshold, a top-up order for the chosen pack is raised and collected like any other invoice. Lines still not covered are billed as overage.
BLOCKBlock further useWhen the projected balance is 0 or less, the subscription’s entitlements report walletExhausted: true, so your product can stop service. Lines still not covered are billed as overage, because usage that happened is still owed.

Bill the overage

This is the default. Nothing is blocked. If the credits cover only part of a charge, the rest is a normal invoice line with GST. See Drawdown and GST.

Example. Balance ₹20, eligible usage ₹50: ₹20 is paid from credits, the other ₹30 plus ₹5.40 GST is invoiced, so the invoice balance is ₹35.40.

Top up automatically

Settings

SettingBuilder labelAPI fieldRules
Pack to buyTop up withautoTopUpPackThe index of one of the price’s packs (counted from 0). Required.
ThresholdWhen the balance falls toautoTopUpThresholdA number of 0 or more. Required.

Behaviour

  • The daily check compares the projected balance with the threshold. When it is at or below it, BillHive raises a top-up order for the chosen pack and collects it like any other invoice. The customer’s saved payment method is used where there is one.
  • At most one open top-up order exists for a subscription at a time. The next daily check raises none while the first is still open.
  • Lines that credits still do not cover are billed as overage.

Example. Threshold ₹10, pack 0 (pay ₹100, get ₹105). The projected balance is ₹8. One top-up order is raised. The next day’s check raises nothing while it is open.

Block

When the projected balance is 0 or less, the subscription is marked wallet exhausted. Your product reads this and decides what to do.

  • On the v1 entitlements API the flag is the response header X-Wallet-Exhausted. See Entitlements.
  • On the v2 wallet API it is walletExhausted in GET /v2/subscriptions/{id}/wallet.
  • In the portal the Wallet tab shows Used up: further use is blocked.
  • It clears as soon as credits arrive: a paid top-up, an adjustment or a renewal grant. It does not wait for the daily run.
  • A price without the BLOCK action always reports false.
  • Usage that happens anyway is still billed. Block is a signal, not a stop inside BillHive.

Example. Action BLOCK, projected balance ₹0: entitlements show walletExhausted: true. After a paid top-up it is false.

The projected balance

projected = balance − unbilled eligible amount. The unbilled amount is the current period’s rated usage and event charges, plus any pending charges on components that are paid from credits, worked out the way the estimate does.

BillHive computes it:

  • on demand, when you call the wallet API or open the Wallet tab;
  • daily, in the daily job;
  • after each drawdown.

It is not checked on every usage event. A customer can go below zero between checks, and that usage is billed as overage.

⚠️

The projected balance can understate the next draw on renewals that are not on the period boundary. A block or an auto top-up can then come up to one period late. If the usage cannot be computed when you read the wallet, the API returns the plain balance as projected and sets projectedUnavailable: true. An auto top-up after a draw outside the workflow engine is left to the daily job.

The daily job

A scheduled workflow, wallet-daily-workflow, runs once a day at 00:15 IST. It runs for both the live and the sandbox data and handles each wallet on its own, so one failure does not stop the others.

StepWhat it does
Expire Wallet MemosExpires every posted wallet entry whose expiry date has passed and whose balance is above 0, by recording an Expiry for the balance left.
Check Wallet BalancesComputes the projected balance of each subscription with a wallet price, raises auto top-ups, and sets or clears walletExhausted for BLOCK prices.

Running the job twice is harmless. It acts only on entries that still have a balance, and expires each with one conditional update, and it raises no second top-up while one is open.

Example, expiry. A bonus entry expired yesterday with ₹12 left. The daily job records an Expiry of ₹12, and the entry’s balance is 0. A second run does nothing.

Limits

  • Balance checks run daily, after each drawdown and on request, not on every usage event.
  • The auto top-up pack is an index. Removing a pack moves the index.
  • The expiring-soon timers fall on the original term end while the renewal order is dated the next day. A renewal still worked when it was run by hand.