Prepaid Credits in the Rate Plan Builder

Prepaid credits let a customer pay for credits up front, sometimes with a bonus on top, and have usage and other charges paid from the balance when an invoice is created. You set it up on a rate plan price in the builder: a Prepaid credits section for the credit settings, and a Paid from credits checkbox on each piece.

For how the wallet behaves after you publish (top-ups, drawdown, expiry, GST), read Prepaid Credits.

Prepaid credits are on rate plan prices only. Add-on prices and charge prices have no wallet. A price without any prepaid credit setting rates, taxes and invoices exactly as it did before.

Set up prepaid credits

Open the plan in the builder

Click New rate plan on a product, or edit a plan. Choose the price point (the tab, for example INR · Monthly) you want credits on. Credits are set for each price point.

Add the section

Under the pricing pieces, click + Add prepaid credits. The section Prepaid credits (INR) opens. It says: Customers pay up front and their charges are paid from the balance. Pick which pieces draw from it below. Use Remove prepaid credits to take it off the price point again.

Add credit packs

Under Credit packs: what they pay and what they get, click + Add pack. For each pack fill in Pack N pay (the price the customer pays) and Pack N credit (what they get). The row shows +X bonus or no bonus. Click Remove to delete a pack. You can have up to 10 packs.

Add free credits (optional)

Type an amount in Free credits granted (INR). A list Granted appears:

OptionAPI grantFrequencyWhat it does
Once, when the subscription startsONCEGiven when the subscription is activated.
Every billing periodEVERY_PERIODGiven at activation and at each renewal.

For Every billing period, a checkbox Unused credits roll over to the next period appears.

Set the expiry (optional)

In Bonus and free credits expire after, type a number of days. Leave it empty (the placeholder says Never) for no expiry. The note reads Credits a customer pays for never expire.

Choose what happens when the balance runs out

Pick one in When the balance runs out:

OptionAPI valueWhat it does
Bill the overage on the invoice (default)BILL_OVERAGEWhatever credits do not cover is invoiced and taxed as usual.
Top up automaticallyAUTO_TOP_UPA top-up invoice is raised for a chosen pack when the balance runs low.
Block further useBLOCKThe subscription’s entitlements report walletExhausted, so your product can stop service.

For Top up automatically, two more fields appear: Top up with (a list of your packs, shown as Pay X, get Y) and When the balance falls to (INR).

Tick Paid from credits on the pieces

Each piece (Base price, Per seat, each Usage, each Per-event fee, each One-time fee) now has a Paid from credits checkbox. Only ticked pieces are paid from the wallet.

Publish

Click Publish plan.

Settings

SettingBuilder labelAPI fieldAllowed valuesDefaultValidation (builder message / API error)
Credit packsCredit packscreditPacksList of {pay, credit}noneAt most 10: At most 10 packs / creditPacks allows at most 10 packs. Must be an array: creditPacks must be an array.
PayPack N paycreditPacks[].payNumber above 0nonePay must be above 0 / creditPacks pay must be greater than 0. Unique: Another pack already costs X / creditPacks has a duplicate pay of X.
CreditPack N creditcreditPacks[].creditNumber, at least paynoneCredit must be at least what they pay / creditPacks credit must be at least pay. Bonus = credit − pay.
Grant amountFree credits grantedgrantAmountNumber above 0noneGrant must be above 0 / grantAmount must be greater than 0.
Grant frequencyGrantedgrantFrequencyONCE, EVERY_PERIODONCE in the builderRequired when grantAmount is set: grantFrequency is required with grantAmount: ONCE, EVERY_PERIOD.
RolloverUnused credits roll over to the next periodrollovertrue or falsefalseOnly with EVERY_PERIOD: Rollover is only for credits granted every period / rollover is only allowed with grantFrequency EVERY_PERIOD. Non-boolean: rollover must be true or false.
Credit expiry daysBonus and free credits expire aftercreditExpiryDaysWhole number of 1 or morenone (never)Enter a whole number of days, at least 1 / creditExpiryDays must be an integer of at least 1.
Zero-balance actionWhen the balance runs outwalletZeroBalanceActionBILL_OVERAGE, AUTO_TOP_UP, BLOCKBILL_OVERAGEwalletZeroBalanceAction must be BILL_OVERAGE, AUTO_TOP_UP, BLOCK.
Auto top-up packTop up withautoTopUpPackIndex of a pack, counted from 0noneRequired with AUTO_TOP_UP: Choose one of the credit packs / autoTopUpPack must be the index of a credit pack.
Auto top-up thresholdWhen the balance falls toautoTopUpThresholdNumber of 0 or morenoneRequired with AUTO_TOP_UP: Enter a balance of 0 or more / autoTopUpThreshold must be a number of at least 0.
Paid from creditsPaid from creditsdrawsFromWallet (per component)true or falsefalse for base, seat and one-time pieces; the builder sets true for usage, per-event and pass-through piecesNeeds the price to have packs or a grant: drawsFromWallet needs the price to have creditPacks or a grantAmount. Non-boolean: Component N drawsFromWallet must be true or false.

All of these API errors are 422 and the message starts with the field name. The wallet settings are accepted on rate plan prices only: on an add-on or charge price you get 422 with wallet settings are only on rate plan prices.

⚠️

The auto top-up pack is an index, not an id. If you remove or re-order a pack, the index points at another pack. Check Top up with after you change the packs.

Examples

Convirza-style Scale plan, in INR. The plan fee is ₹0 and the customer buys credits:

PackPayCreditBonus
1₹100₹105₹5
2₹250₹265₹15
3₹500₹535₹35
4₹1,000₹1,080₹80

Zero-balance action Bill the overage on the invoice. Paid from credits is ticked on every usage piece, and on the recurring numbers piece.

Convirza-style Free plan. The plan is ₹0, with Free credits granted ₹20, Granted once, and no packs.

See the full worked month.

Limits

  • The builder opens a price whose wallet settings it cannot show (for example a pack list it cannot read) read-only.
  • The wallet takes the subscription’s currency. A top-up in another currency is rejected.
  • v1 writes reject the wallet fields. A v1 edit that changes only the description is allowed on a wallet price. See v1 is read-only for these settings.
  • Tenants’ own invoice PDF templates do not print the credit rows yet. The standard template does.