Prepaid Credits
Prepaid credits let a customer pay for credits up front, sometimes with a bonus on top, and have their charges paid from the balance instead of billed in cash. Every invoice shows how much came from credits and how much is still owed. GST is charged once, when the credits are bought. It is not charged again when they are spent.
This is the model used by pay-as-you-go products such as Convirza: a Free plan that comes with ₹20 of credits, and a Scale plan where ₹100 buys ₹105 of credits and usage is deducted from the balance.
When to use it
- You sell usage (minutes, SMS, API calls) and want customers to buy credits first.
- You want to reward bigger purchases with a bonus: ₹100 buys ₹105, ₹1,000 buys ₹1,080.
- You want to give free credits with a plan, once or every period.
- You want to stop service or top up automatically when credits run out.
Set it up in the rate plan builder: see Prepaid Credits in the Rate Plan Builder.
In this section
| Page | What it covers |
|---|---|
| Drawdown and GST | Which charges draw, the order credits are spent in, GST rules, the invoice and the amount due |
| Top-Ups and Adjustments | The top-up flow, adding and removing credits, chargeback reversal, carry-over on cancel |
| Zero-Balance Actions | Bill the overage, auto top-up, block, and the daily job |
| Wallet Tab | The Wallet tab on the customer page |
| Worked Example | A full month, step by step, with the numbers |
| FAQs and Limitations | Common questions and what is not covered |
What the wallet is
The wallet is a balance of credits that belongs to one subscription. Only that subscription’s charges draw from it.
There is no separate ledger. Every movement in a wallet is a credit memo or an application of a credit memo, so the wallet uses the same records you already know from Credit Balance. Wallet credit memos are kept apart from ordinary credits:
- Automatic credit application, refunds and credits on orders never touch wallet credits.
- Ordinary credits (for example from a cancellation or a downgrade) never fund the top-up invoice. A top-up invoice can only be paid by a payment.
- Wallet credits are never refunded and cannot be cashed out.
- You cannot create a wallet credit memo through the v1 credit memo API.
POST /credit-memoswithwallet: trueis refused. Only the wallet API and the workflows write wallet entries.
The balance of a subscription is the sum of the remaining balance of its posted wallet entries that have not expired. The account page shows each subscription’s balance and a total.
Kinds of wallet entry
| Entry | What it is | Taxed |
|---|---|---|
| Top-up | Credits the customer bought. Posted when the top-up invoice is paid, for the price paid before tax. | The top-up invoice carries the GST |
| Bonus | The extra credits on a pack: credit minus price. Posted with the top-up. | No |
| Grant | Free credits that come with the plan | No |
| Adjustment | Credits you add by hand | No |
| Drawdown | Credits spent on an invoice | Covered lines carry no GST |
| Expiry | Credits that lapsed | Not applicable |
Top-up, Bonus, Grant and Adjustment are credit memos. Drawdown and Expiry are recorded as applications of those memos.
Packs and bonus
A credit pack is a pair of numbers: what the customer pays and what they get. The bonus is the difference.
| Pack | Pay | Get | Bonus |
|---|---|---|---|
| 1 | ₹100 | ₹105 | ₹5 |
| 2 | ₹250 | ₹265 | ₹15 |
| 3 | ₹500 | ₹535 | ₹35 |
| 4 | ₹1,000 | ₹1,080 | ₹80 |
Rules: pay must be above 0, credit must be at least pay, at most 10 packs, and no two packs with the same pay.
A custom amount is also possible. It buys exactly its value with no bonus.
When the customer buys a pack, two entries are posted on payment: a Top-up for what they paid, and a Bonus for the extra. Only the bonus can expire.
Grants
A grant gives free credits with the plan.
| Setting | Behaviour |
|---|---|
Once (ONCE) | Given when the subscription is activated, including activation after a trial. It is given once per subscription: running activation again gives nothing more. |
Every period (EVERY_PERIOD) | Given when the subscription is activated and again at each renewal, before the drawdown. |
| Rollover off (default) | At the end of the period, what is left of that period’s grant expires. The drawdown for the closed period runs first, so usage billed in arrears can still use that period’s grant. |
| Rollover on | The unused part stays and adds to the next grant. Only for EVERY_PERIOD. |
Grants are never prorated.
The first design gave an every-period grant at renewal only. As built, an every-period grant is also given at activation for the first period.
Example, ₹50 every period, ₹30 used.
| Rollover off | Rollover on | |
|---|---|---|
| At the next renewal | ₹20 of the old grant expires, a new ₹50 is posted | The ₹20 stays, a new ₹50 is posted |
| Balance after the renewal grant | ₹50 | ₹70 |
Expiry
| Credit | Expires? |
|---|---|
| Paid credits (a top-up) | Never |
| Adjustments | Never |
| Bonus credits | After Bonus and free credits expire after days, if you set it |
| Once grants | After the same number of days |
| Every-period grants | Follow the rollover setting, not the expiry days |
The expiry date is stamped on the entry when it is posted, as the posting date plus the expiry days. A daily job expires entries whose date has passed (see Zero-Balance Actions). Credits that expire before an invoice’s date are not used on that invoice.
Example. Expiry is 30 days. A customer buys the ₹100 → ₹105 pack and uses nothing for 31 days. The ₹5 bonus expires. The ₹100 stays.
Which charges draw from the wallet
Each component has a Paid from credits setting.
- The builder turns it on by default for usage, per-event and pass-through pieces, and off for the base fee, seats and one-time fees.
- A recurring per-unit piece can be switched on, as in the Convirza example where the phone numbers draw.
- Setting it on a piece needs the price to have packs or a grant, because otherwise the wallet could never be funded.
- A line draws from the wallet when its own component is ticked, even after a plan change to a price with no wallet.
- Add-on prices have no wallet.
See Drawdown and GST for how credits are spent.
Where credits come from, at a glance
- The customer buys a pack or a custom amount, through the top-up flow. GST is charged on that invoice.
- You grant credits with the plan, or add them by hand.
- At invoicing, the wallet pays the lines that draw, with no GST on the part it pays.
- What credits do not cover is billed, or the customer is topped up or blocked, depending on the zero-balance action.