Prepaid CreditsOverview

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

PageWhat it covers
Drawdown and GSTWhich charges draw, the order credits are spent in, GST rules, the invoice and the amount due
Top-Ups and AdjustmentsThe top-up flow, adding and removing credits, chargeback reversal, carry-over on cancel
Zero-Balance ActionsBill the overage, auto top-up, block, and the daily job
Wallet TabThe Wallet tab on the customer page
Worked ExampleA full month, step by step, with the numbers
FAQs and LimitationsCommon 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-memos with wallet: true is 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

EntryWhat it isTaxed
Top-upCredits the customer bought. Posted when the top-up invoice is paid, for the price paid before tax.The top-up invoice carries the GST
BonusThe extra credits on a pack: credit minus price. Posted with the top-up.No
GrantFree credits that come with the planNo
AdjustmentCredits you add by handNo
DrawdownCredits spent on an invoiceCovered lines carry no GST
ExpiryCredits that lapsedNot 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.

PackPayGetBonus
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.

SettingBehaviour
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 onThe 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 offRollover on
At the next renewal₹20 of the old grant expires, a new ₹50 is postedThe ₹20 stays, a new ₹50 is posted
Balance after the renewal grant₹50₹70

Expiry

CreditExpires?
Paid credits (a top-up)Never
AdjustmentsNever
Bonus creditsAfter Bonus and free credits expire after days, if you set it
Once grantsAfter the same number of days
Every-period grantsFollow 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

  1. The customer buys a pack or a custom amount, through the top-up flow. GST is charged on that invoice.
  2. You grant credits with the plan, or add them by hand.
  3. At invoicing, the wallet pays the lines that draw, with no GST on the part it pays.
  4. What credits do not cover is billed, or the customer is topped up or blocked, depending on the zero-balance action.