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:

  1. Quantity: the seats bought, or the usage of the period.
  2. Billable quantity = max(0, quantity − included quantity).
  3. Model amount from the billable quantity, using the charge model.
  4. Period amount = model amount × proration. Proration applies to recurring components only.
  5. Minimum and cap: the amount is raised to the minimum and lowered to the cap, when they are set. They are not prorated.
  6. Cycles: the amount is multiplied by the number of cycles on the order.
  7. 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:

ButtonCharge model
Per unit (default)PER_UNIT
PacksPACKAGE
StepsSTAIRSTEP
TiersGRADUATED, 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

  1. Click Tiers under How is it priced?
  2. 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.
  3. 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.
  4. Click + Add row to add a band, or Remove to delete one (you always keep at least one row).

Settings

SettingAPI fieldAllowed valuesDefaultRules
Charge modelchargeModelGRADUATEDnone
Tier fromtiers[].fromUnitNumbernoneBands are contiguous.
Tier up totiers[].toUnitNumber or null (open-ended)noneThe 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 pricetiers[].unitPriceNumber of 0 or morenonePrice of one unit in the band.
Flat feetiers[].flatAmountNumber of 0 or more0Added 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.

BandUnits in the bandPriceAmount
1 to 1,0001,000₹0.50₹500
1,001 to 5,0004,000₹0.40₹1,600
5,001 and above1,000₹0.30₹300
Line total6,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

  1. Click Steps under How is it priced?
  2. The note reads Steps: one price for the band the quantity lands in.
  3. Fill the rows. Each row has Row N up to and Row N price (in the currency). The last row reads X and above.
  4. Click + Add row or Remove.

Settings

SettingAPI fieldAllowed valuesDefaultRules
Charge modelchargeModelSTAIRSTEPnone
Step limitstiers[].fromUnit, tiers[].toUnitNumbers; the last toUnit is nullnoneSteps are contiguous, as for volume.
Step pricetiers[].flatAmountNumber of 0 or morenoneBuilder error: Enter a price for this step.
Unit price of a steptiers[].unitPriceMust be 00API error: Component N STAIRSTEP tiers must have a unitPrice of 0.
TierstiersAt least onenoneAPI 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.

QuantityStepAmount
600501+₹4,000
250101 to 500₹3,000
0none₹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

  1. Click Packs under How is it priced?
  2. Type the Price per pack (the label of the price field changes to this, and for seats to Price per pack of seats).
  3. Type the Pack size.
  4. Pick Partial packs:
Option in the builderAPI roundingWhat it does
Charge a full pack (default)UPRounds the packs up
Ignore the part packDOWNRounds the packs down
Charge the fractionPROPORTIONALCharges 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

SettingAPI fieldAllowed valuesDefaultRules
Charge modelchargeModelPACKAGEnone
Pack sizepackageSizeNumber above 0noneRequired. Builder error: Pack size must be above 0. API error: Component N PACKAGE needs a packageSize greater than 0.
RoundingroundingUP, DOWN, PROPORTIONALUP in the builder; required in the APIAPI error: Component N PACKAGE needs a rounding of UP, DOWN, PROPORTIONAL.
Price per packunitPriceNumber of 0 or morenoneThe price of one pack.
TierstiersNonenoneAPI error: Component N PACKAGE does not take tiers.
Where allowedpackageSize 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.

RoundingPacksAmount
UP33 × ₹500 = ₹1,500
DOWN22 × ₹500 = ₹1,000
PROPORTIONAL2.52.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:

ModeWhat it chargesBuilder note
SimpleOne percentage of the total value in the periodOne percentage of the total transaction value in the period.
Per transactionEach transaction pays a fixed fee plus the percentage, kept between a minimum and a maximumEach transaction pays its own fee: the fixed fee plus the percentage, kept between the minimum and maximum. A refund reverses its fee.
SlabsPercentage bands on the period’s total value, graduated or volumeUp 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

SettingAPI fieldAllowed valuesRules
PercentageunitPrice0 to 100unitPrice (the percentage) must be between 0 and 100
Fixed fee per transactionfixedFeeNumber of 0 or morePer transaction mode
Minimum per transactionperTxnMinNumber of 0 or moreMust not be above the maximum: perTxnMin must be <= perTxnMax
Maximum per transactionperTxnMaxNumber of 0 or more
How the slabs applytierModeGRADUATED, VOLUMERequired with slabs: tiers on a PERCENTAGE component require tierMode
Slabstiers[].toUnit, tiers[].unitPriceUp-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:

TransactionFixed fee + 2%Kept between ₹10 and ₹500
₹3002 + 6 = ₹8₹10 (minimum)
₹10,0002 + 200 = ₹202₹202
₹50,0002 + 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 applyAmount
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 slab1.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

SettingAPI fieldAllowed valuesDefaultRules
MinimumminAmountNumber of 0 or morenonePer component, per period.
CapmaxAmountNumber of 0 or morenonePer component, per period.
BothminAmount ≤ maxAmountBuilder error: Cap must be at least the minimum. API error: Component N minAmount must not exceed maxAmount.
Wrong numberComponent N minAmount must be a number >= 0 (same for maxAmount).
On a flat componentnot allowedComponent 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)

CaseSetupQuantityAmount
CapPer unit ₹0.004, 5,000 included, cap ₹1018,000₹10 (would be ₹52)
MinimumPer unit ₹0.004, minimum ₹201,000₹20 (would be ₹4)
Minimum, no usagesame0₹20
Minimum, recurring and proratedSeat ₹100 a month, minimum ₹150, half a month, 1 seat1₹150 (the prorated ₹50 is raised to the minimum)
Package with included₹500 per 1,000, 1,000 included, rounding UP2,500₹1,000 (2 packs)

How it appears on the invoice

The line name says why the amount is what it is.

SituationLine text
PackageEmails — 3 packs of 1000
StairstepContacts — 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.

LineQtyUnit priceAmountCGST 9%SGST 9%
Rate plan1₹15.00₹15.00₹1.35₹1.35
Emails — 3 packs of 10003₹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.