Charge Models
A charge model says how a component turns a quantity into an amount. This page covers the models beyond flat and per unit: graduated (tiers), volume, stairstep (steps), package (packs), percentage, and the minimum and cap that can be put on any component except a flat one. Flat and per unit are on Price Components.
How an amount is worked out
For every component the engine follows the same order:
- Quantity: the seats bought, or the usage of the period.
- Billable quantity =
max(0, quantity − included quantity). - Model amount from the billable quantity, using the charge model.
- Period amount = model amount × proration. Proration applies to recurring components only.
- Minimum and cap: the amount is raised to the minimum and lowered to the cap, when they are set. They are not prorated.
- Cycles: the amount is multiplied by the number of cycles on the order.
- The result is kept to 6 decimals. On the invoice the line is rounded to paise.
With no new setting used, the result is the same as for a plain flat or per-unit price.
Choose a model in the builder
Turn on a seat or usage piece
In the rate plan builder, click the Per seat or Usage tile. See Price Components.
Pick How is it priced?
Click one of the four buttons under the piece:
| Button | Charge model |
|---|---|
| Per unit (default) | PER_UNIT |
| Packs | PACKAGE |
| Steps | STAIRSTEP |
| Tiers | GRADUATED, or VOLUME when you tick the volume box |
Fill in the fields
Each model has its own fields, described below. Wrong entries are marked and block saving.
Add limits if you need them
Click + Add minimum or cap. See Minimum and cap.
The base piece always stays a flat amount, so it has no How is it priced? choice.
Graduated (Tiers)
Each band of quantity is priced at its own rate. Only the units inside a band are charged at that band’s price. Use it for pricing that gets cheaper, or dearer, as use grows, and where the first units should keep their price.
In the builder
- Click Tiers under How is it priced?
- Leave Volume pricing: the whole quantity gets the price of its tier unticked. The note shows Graduated: each band is charged at its own price.
- Fill the rows. Each row has Row N up to (the upper limit of the band), Row N price per unit and an optional Row N flat fee. The last row has no limit and reads X and above.
- Click + Add row to add a band, or Remove to delete one (you always keep at least one row).
Settings
| Setting | API field | Allowed values | Default | Rules |
|---|---|---|---|---|
| Charge model | chargeModel | GRADUATED | none | |
| Tier from | tiers[].fromUnit | Number | none | Bands are contiguous. |
| Tier up to | tiers[].toUnit | Number or null (open-ended) | none | The last tier is open-ended. Builder error: Enter a number above 0 for the first row, Must be higher than the row above for the others. |
| Unit price | tiers[].unitPrice | Number of 0 or more | none | Price of one unit in the band. |
| Flat fee | tiers[].flatAmount | Number of 0 or more | 0 | Added once for each band the quantity reaches. Never charged when the billable quantity is 0. |
Worked example
Bands: 1 to 1,000 units at ₹0.50, 1,001 to 5,000 at ₹0.40, and 5,001 and above at ₹0.30. The customer uses 6,000 units.
| Band | Units in the band | Price | Amount |
|---|---|---|---|
| 1 to 1,000 | 1,000 | ₹0.50 | ₹500 |
| 1,001 to 5,000 | 4,000 | ₹0.40 | ₹1,600 |
| 5,001 and above | 1,000 | ₹0.30 | ₹300 |
| Line total | 6,000 | ₹2,400 |
The band amounts add up to the line amount. The invoice shows one line and keeps the bands in its line details.
Volume
The tier the total quantity lands in prices every unit. Use it when a big customer should get the big-tier price on everything.
In the builder
Click Tiers, then tick Volume pricing: the whole quantity gets the price of its tier. The note changes to Volume: every unit is charged at the tier the total lands in. The rows are the same as for graduated.
Settings
Same as graduated, with chargeModel set to VOLUME. The flat fee of the tier is charged once.
The tier is the first one whose upper limit is empty or at least the billable quantity. If the quantity falls in a gap between tiers, the next tier up is used. Past the last tier, the last tier is used.
Worked example
The same bands as above, now as volume. With 6,000 units the total lands in the last band, so all 6,000 units cost ₹0.30: 6,000 × ₹0.30 = ₹1,800. With 800 units the total lands in the first band: 800 × ₹0.50 = ₹400.
Stairstep (Steps)
The quantity picks one step, and the charge is that step’s flat price, whatever the exact quantity inside it. Use it for size-based plans, such as “up to 100 contacts ₹800, up to 500 ₹3,000”.
In the builder
- Click Steps under How is it priced?
- The note reads Steps: one price for the band the quantity lands in.
- Fill the rows. Each row has Row N up to and Row N price (in the currency). The last row reads X and above.
- Click + Add row or Remove.
Settings
| Setting | API field | Allowed values | Default | Rules |
|---|---|---|---|---|
| Charge model | chargeModel | STAIRSTEP | none | |
| Step limits | tiers[].fromUnit, tiers[].toUnit | Numbers; the last toUnit is null | none | Steps are contiguous, as for volume. |
| Step price | tiers[].flatAmount | Number of 0 or more | none | Builder error: Enter a price for this step. |
| Unit price of a step | tiers[].unitPrice | Must be 0 | 0 | API error: Component N STAIRSTEP tiers must have a unitPrice of 0. |
| Tiers | tiers | At least one | none | API error: Component N STAIRSTEP needs at least one tier. |
The step is the first one whose upper limit is empty or at least the billable quantity. A quantity in a gap falls to the next step up. Past the last step the last step is used. A billable quantity of 0 charges ₹0.
Worked example (acceptance table)
Steps: 1 to 100 ₹800, 101 to 500 ₹3,000, 501 and above ₹4,000.
| Quantity | Step | Amount |
|---|---|---|
| 600 | 501+ | ₹4,000 |
| 250 | 101 to 500 | ₹3,000 |
| 0 | none | ₹0 |
On an invoice the line says which step applied, for example Contacts — 501+ step.
Package (Packs)
Units are sold in packs of a fixed size at a price per pack. A rounding rule decides what happens to a part pack. Use it for “₹500 per 1,000 API calls”.
In the builder
- Click Packs under How is it priced?
- Type the Price per pack (the label of the price field changes to this, and for seats to Price per pack of seats).
- Type the Pack size.
- Pick Partial packs:
| Option in the builder | API rounding | What it does |
|---|---|---|
| Charge a full pack (default) | UP | Rounds the packs up |
| Ignore the part pack | DOWN | Rounds the packs down |
| Charge the fraction | PROPORTIONAL | Charges the exact fraction of a pack, to 6 decimals |
The note under the fields reads The price above is the price of one pack.
Settings
| Setting | API field | Allowed values | Default | Rules |
|---|---|---|---|---|
| Charge model | chargeModel | PACKAGE | none | |
| Pack size | packageSize | Number above 0 | none | Required. Builder error: Pack size must be above 0. API error: Component N PACKAGE needs a packageSize greater than 0. |
| Rounding | rounding | UP, DOWN, PROPORTIONAL | UP in the builder; required in the API | API error: Component N PACKAGE needs a rounding of UP, DOWN, PROPORTIONAL. |
| Price per pack | unitPrice | Number of 0 or more | none | The price of one pack. |
| Tiers | tiers | None | none | API error: Component N PACKAGE does not take tiers. |
| Where allowed | packageSize and rounding on any other model give Component N packageSize is only allowed on PACKAGE components. |
Packs = billable quantity ÷ pack size, rounded as chosen. Amount = packs × price per pack. Rounding applies to the period total, not to each usage event. Billing every call per started minute, for example, is not supported.
Worked example (acceptance table)
₹500 per pack of 1,000 calls, 2,500 calls in the period.
| Rounding | Packs | Amount |
|---|---|---|
| UP | 3 | 3 × ₹500 = ₹1,500 |
| DOWN | 2 | 2 × ₹500 = ₹1,000 |
| PROPORTIONAL | 2.5 | 2.5 × ₹500 = ₹1,250 |
With 1,000 calls included and rounding UP: billable = 1,500, which is 2 packs, so ₹1,000.
Percentage
The charge is a percentage of a money value recorded in usage events, such as the value of each payment you process or each order on your marketplace. Use it for payment-gateway, marketplace and commission pricing.
Percentage is available on usage pieces only. In the builder, pick Percentage under How is it priced?, then choose one of three modes:
| Mode | What it charges | Builder note |
|---|---|---|
| Simple | One percentage of the total value in the period | One percentage of the total transaction value in the period. |
| Per transaction | Each transaction pays a fixed fee plus the percentage, kept between a minimum and a maximum | Each transaction pays its own fee: the fixed fee plus the percentage, kept between the minimum and maximum. A refund reverses its fee. |
| Slabs | Percentage bands on the period’s total value, graduated or volume | Up to amount, and the % charged on it. Each slab starts where the one above ends. |
A preview under the fields (Try it) shows what an example transaction value or a monthly total would cost.
Settings
| Setting | API field | Allowed values | Rules |
|---|---|---|---|
| Percentage | unitPrice | 0 to 100 | unitPrice (the percentage) must be between 0 and 100 |
| Fixed fee per transaction | fixedFee | Number of 0 or more | Per transaction mode |
| Minimum per transaction | perTxnMin | Number of 0 or more | Must not be above the maximum: perTxnMin must be <= perTxnMax |
| Maximum per transaction | perTxnMax | Number of 0 or more | |
| How the slabs apply | tierMode | GRADUATED, VOLUME | Required with slabs: tiers on a PERCENTAGE component require tierMode |
| Slabs | tiers[].toUnit, tiers[].unitPrice | Up-to amount and a percentage of 0 to 100 |
Other rules:
- Per-transaction settings and slabs can’t be combined:
tiers cannot be combined with fixedFee, perTxnMin or perTxnMax. - Per transaction and slabs need a meter that sums a value (aggregation SUM).
- An included quantity isn’t allowed on a percentage piece.
- These settings are refused on other charge models, and on a component that isn’t usage.
Worked example: per transaction
₹2 + 2% per transaction, at least ₹10, at most ₹500. Three payments in the month:
| Transaction | Fixed fee + 2% | Kept between ₹10 and ₹500 |
|---|---|---|
| ₹300 | 2 + 6 = ₹8 | ₹10 (minimum) |
| ₹10,000 | 2 + 200 = ₹202 | ₹202 |
| ₹50,000 | 2 + 1,000 = ₹1,002 | ₹500 (maximum) |
| Total | ₹712 |
The invoice line reads, for example, Payments — 3 transactions · ₹2 + 2% · 1 at minimum ₹10 · 1 at maximum ₹500.
Refunds. A usage event with a negative value is a refund and reverses the fee its amount would have paid. If the ₹10,000 payment is refunded (−₹10,000) in the same period, ₹202 comes off, so that sale and its refund net to ₹0. A period never bills below ₹0.
Worked example: slabs
Slabs 2% up to ₹1,00,000, then 1.5%. Total value in the month ₹1,50,000.
| How the slabs apply | Amount |
|---|---|
| Graduated: each slab is charged at its own % | 2% × 1,00,000 + 1.5% × 50,000 = 2,000 + 750 = ₹2,750 |
| Volume: the whole total gets the % of its slab | 1.5% × 1,50,000 = ₹2,250 |
Worked example: simple
2% of a month’s total of ₹1,50,000 = ₹3,000.
Minimum and cap
A minimum raises a low charge to a floor, for example “usage, at least ₹200 a month”. A cap lowers a high charge to a ceiling, for example “overage capped at ₹5,000”. They can be set on any component except a flat one.
In the builder
Click + Add minimum or cap under a seat or usage piece. Two fields open: Minimum and Cap, each with the currency. Remove clears both.
Settings
| Setting | API field | Allowed values | Default | Rules |
|---|---|---|---|---|
| Minimum | minAmount | Number of 0 or more | none | Per component, per period. |
| Cap | maxAmount | Number of 0 or more | none | Per component, per period. |
| Both | minAmount ≤ maxAmount | Builder error: Cap must be at least the minimum. API error: Component N minAmount must not exceed maxAmount. | ||
| Wrong number | Component N minAmount must be a number >= 0 (same for maxAmount). | |||
| On a flat component | not allowed | Component N minAmount is not allowed on FLAT components |
Rules
- The limits are not prorated. A half-month first period still gets the full minimum.
- A zero-usage period with a minimum charges the minimum.
- Usage shown at purchase as “billed on usage” is not clamped. The minimum applies when the usage is rated.
- On a plan change, the clamped full-period amount is the one that is prorated, for the charge and for the credit, so they stay symmetric.
- A one-time component ignores minimum and cap.
- When a minimum or cap changes the amount, the line text says so (see below).
Worked examples (acceptance table)
| Case | Setup | Quantity | Amount |
|---|---|---|---|
| Cap | Per unit ₹0.004, 5,000 included, cap ₹10 | 18,000 | ₹10 (would be ₹52) |
| Minimum | Per unit ₹0.004, minimum ₹20 | 1,000 | ₹20 (would be ₹4) |
| Minimum, no usage | same | 0 | ₹20 |
| Minimum, recurring and prorated | Seat ₹100 a month, minimum ₹150, half a month, 1 seat | 1 | ₹150 (the prorated ₹50 is raised to the minimum) |
| Package with included | ₹500 per 1,000, 1,000 included, rounding UP | 2,500 | ₹1,000 (2 packs) |
How it appears on the invoice
The line name says why the amount is what it is.
| Situation | Line text |
|---|---|
| Package | Emails — 3 packs of 1000 |
| Stairstep | Contacts — 501+ step |
| Minimum applied | … — minimum charge |
| Cap applied | … — capped |
When a limit and a pack or step both apply, the line text names the limit. The pack or step is kept in the line details.
Pack lines show the packs as the quantity and the price per pack as the unit price, so quantity × unit price equals the line amount. Step and limit lines show quantity 1 and the amount as the unit price.
Example renewal invoice, INR, GST 18%. A plan with a ₹15 base fee and an Emails package priced ₹500 per 1,000 (rounding UP) renews after a period with 2,500 emails and no included quantity.
| Line | Qty | Unit price | Amount | CGST 9% | SGST 9% |
|---|---|---|---|---|---|
| Rate plan | 1 | ₹15.00 | ₹15.00 | ₹1.35 | ₹1.35 |
| Emails — 3 packs of 1000 | 3 | ₹500.00 | ₹1,500.00 | ₹135.00 | ₹135.00 |
| Subtotal | ₹1,515.00 | ||||
| GST | ₹272.70 | ||||
| Total | ₹1,787.70 |
Limits and notes
- The v1 API and the classic form show these prices (stairstep as Volume Pricing at the first step, package as Per Unit Pricing at the pack price) but cannot edit them. See v1 is read-only for these settings.
- The builder opens a plan with tiers it cannot reproduce read-only.
- A tier band of one unit is allowed.
- Add-on prices: the minimum and cap apply per add-on period, so the renewal and the invoice agree.
- A credit for a plan change on an add-on that uses components is worked out as price × quantity and rounded to 2 decimals.
- Not covered: a minimum commitment for the whole subscription, true-up and ramps.