Credits, tokens & top-ups

Customers hold one balance: tokens, shown to them as credits (one credit = 10,000 tokens by default). Plans grant tokens each cycle, customers build their own top-up, and every generation spends tokens at what it actually cost us upstream. Monetization → Top-up builder is the playground for testing top-ups.

How a token is priced

One setting ties everything together: the token value — how much provider cost one million tokens pay for (default ৳18 per 1M tokens).

• Spending. A generation costs provider cost ÷ token value tokens. A ৳3.66 Nano Banana 2 Lite image is 203,334 tokens (about 20 credits). Because every model is charged by its own cost, the profit on a token is the same whichever model the customer picks.
• Selling. Priced "from AI cost", tokens sell for their provider cost grossed up so gateway (5%), VAT (15%) and profit (40%) are all covered: one credit is ৳0.45, 500 credits ৳225, 2,000 credits ৳900.

The top-up builder

Customers don't pick from fixed packages. Like a mobile operator's "make your own pack", they choose how much they want and the system prices it:

500 credits → ৳225 · with the volume bonus on: 550 credits

The customer's app only sends what they chose. Every price, bonus and discount is worked out on our side, and worked out again at checkout. If it changed in between (a promotion ended), the customer is shown the new price before paying.

It has four parts. They are configured through the admin API (/v1/admin/topup/*, SUPER_ADMIN); the admin page is a playground for testing them (see below).

1. Components — what a top-up is built from

Component	What the customer picks	Default
Credits	50 – 20,000 credits, in 10s	On sale
Images	5 – 1,000 Nano Banana 2 Lite images	Off
Videos	1 – 200 five-second Veo 3.1 Lite clips	Off
Speech	1 – 5,000 thousand characters of speech	Off
Chat	10 – 100,000 chat replies	Off

Everything turns into tokens in the same wallet — "20 images" buys 20 images' worth of tokens, spendable on anything. Turn on the extra components when you want the top-up screen to talk in images and videos rather than just credits.

Each component is priced one of three ways:

• From AI cost (default) — always keeps the profit target, and follows model prices automatically.
• Fixed price per unit — e.g. ৳0.50 a credit.
• Volume tiers — every unit costs the price of the highest tier reached, e.g. ৳0.50 each, ৳0.40 each from 1,000, ৳0.35 each from 5,000.

2. Bonuses & promotions — rules

A rule gives something when its conditions hold:

Gives	Example
Bonus units	+50 credits
Extra tokens	20% more
Percentage off	10% off, up to ৳100
Fixed amount off	৳20 off

Condition	Example
Buys at least	500 credits
Spends at least	৳500 before discounts
Days	Friday and Saturday (Bangladesh time)
Customer	Everyone · first top-up only · accounts newer than N days
Paying with	bKash only
Dates	1 – 15 December
Limits	1,000 uses in total · once per customer

How rules combine:

• Groups don't stack. "500 credits → +50" and "2,000 credits → +300" in the group volume: a customer buying 2,000 gets +300, not +350. The higher priority wins.
• The profit floor protects us. If stacking rules would leave less than 10% profit (if every token is used), the lowest-priority rules are dropped until it doesn't. Total discounts never exceed 50% of the price.
• New rules start switched off. Four templates are ready: the two volume bonuses above, "Weekend: 20% extra credits" and "First top-up: +100 credits". All off — switch one on with PATCH /v1/admin/topup/rules/:id { "active": true }. Even all switched on at once, on the largest top-up, they stay above the floor.

Customers see rules they are one step away from as offers ("add 100 credits for +50 bonus", "sign in for your first top-up bonus").

3. Payment rules — which channel takes which amount

Channel	Default
SSLCommerz, bKash	Any amount
Carrier billing (DCB)	Only amounts listed here

Carrier billing can only charge amounts registered with Hullor for each carrier. List them with PUT /v1/admin/topup/payment-rules/dcb (e.g. ৳99, ৳499, ৳999, ৳1,999). A top-up at any other amount is offered on the other channels only. With none listed, carrier billing isn't offered for top-ups. You can also switch a channel off for top-ups or give it a minimum and maximum.

4. Settings

Setting	Default	Meaning
Tokens per credit	10,000	What one credit is. Changing it changes what every credit costs
Round up to	৳1	Amounts are rounded up to this
Minimum / maximum top-up	৳20 / ৳10,000	After discounts and rounding
Profit floor	10%	See rules above
Largest total discount	50%	Of the price before discounts

Change them with PUT /v1/admin/topup/settings. The master on/off switch is topUpEnabled in credit pricing (PUT /v1/admin/credits/pricing); the playground header shows whether top-ups are on sale.

Changes to settings, components, rules and payment rules need SUPER_ADMIN, take effect for new top-ups straight away, and are all in the audit log. Orders already placed keep exactly what they were sold with.

The playground

Monetization → Top-up builder is a playground and nothing else: it prices any top-up the way a customer would see it, using the live components, rules and pricing, without saving anything or anyone paying:

• set the credits (and any other components),
• pick who (returning customer, first top-up, not signed in, account age), when (today or a given weekday) and how (payment channel),
• and see the price, the credits they get, every rule (applied, or why not — including switched-off ones), where the money goes (gateway, VAT, AI cost, our profit) and which channels can take it.

Try a different token price there too; only the playground changes.

What happens when a customer pays

1. The order records the selection, the price, each rule applied and the credits and bonus it grants.
2. The gateway confirms. The payment is marked paid and the tokens added in one step, exactly once. A gateway confirming twice can't add tokens twice.
3. If the gateway reports a different amount than we charged, nothing is added and the order is left for someone to look at.
4. Checkouts not completed within a day become Expired. If the money still arrives, the tokens are still added.
5. A refund takes the tokens back as far as the balance allows (tokens already spent can't be recovered; the statement says how many). It never touches the customer's plan. A carrier "unsubscription" is not a refund and takes nothing back.

Recent top-up orders — what was chosen, the rules applied, the amount and the status — are at GET /v1/admin/topup/orders.

Worth knowing: a limited promotion ("first 1,000 customers") can go slightly over its limit if several customers pay at the very same moment. Limits count paid orders.

Plans at the default token value

Package	Price	Tokens	Provider cost at full use	Net margin
Basic	৳99 / week	1,008,240	৳18.15	62%
Beginner	৳499 / month	10,079,920	৳181.44	44%
Creator	৳999 / month	21,169,200	৳381.05	42%
Pro	৳1,999 / month	43,343,520	৳780.18	41%

Worth deciding: priced from AI cost, ৳499 of top-up buys about 1,109 credits (11.09M tokens) usable on every model, while the ৳499 Beginner plan gives 10.08M. If plans should be the better deal, price credits per unit or with tiers instead.

Checking real charges in the Playground

AI Platform → Playground → Test wallet. Set a balance and switch Charging on. Every run reserves, settles and refunds against that balance exactly as a customer's would, and shows the real charge.

Granting tokens by hand

Users → customer → Grant tokens. Enter a token count and a note; the note appears in the customer's statement. SUPER_ADMIN only.

History

• The old wallet had four balances (requests, text tokens, images, videos). Each customer's old balance converts to tokens the first time their account is used.
• Top-ups were briefly "any amount", then fixed packs. Both are replaced by the builder. Fixed packs are off sale; anything already bought stays in wallets.