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.
| Action | Builder label | What happens |
|---|---|---|
BILL_OVERAGE (default) | Bill the overage on the invoice | What credits do not cover is invoiced and taxed as usual. |
AUTO_TOP_UP | Top up automatically | When 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. |
BLOCK | Block further use | When 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
| Setting | Builder label | API field | Rules |
|---|---|---|---|
| Pack to buy | Top up with | autoTopUpPack | The index of one of the price’s packs (counted from 0). Required. |
| Threshold | When the balance falls to | autoTopUpThreshold | A 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
walletExhaustedinGET /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
BLOCKaction always reportsfalse. - 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.
| Step | What it does |
|---|---|
| Expire Wallet Memos | Expires 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 Balances | Computes 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.