Agent Wranglers

USG-30Recommended

Name the tier model of every metered price

Store with every tiered price whether it is graduated or volume. Graduated applies each tier's rate to the units inside it, and volume applies one rate to all units. Compute both in one tested function.

By Agent Wranglers. Updated .

How to do it

For a price of 10 cents for the first 1,000 units and 8 cents after, 1,500 units cost 140 euros graduated. The same price read as volume costs 120 euros. Payment providers support both, such as Stripe's graduated and volume tiers, so set the mode explicitly and show it on the pricing page. Write the tiers as data with an upper bound per tier and the last tier open, in the versioned price catalogue. Bill the period total once, never per event, or a volume price never reaches its lower rate.

Examples

JavaScript example

export function tieredAmountMinor(quantity, tiers, mode) {
  if (mode === 'volume') {
    const tier = tiers.find(t => t.upTo === null || quantity <= t.upTo)
    return quantity * tier.unitMinor
  }
  let previous = 0
  return tiers.reduce((sum, tier) => {
    const units = Math.max(0, Math.min(quantity, tier.upTo ?? Infinity) - previous)
    previous = tier.upTo ?? previous
    return sum + units * tier.unitMinor
  }, 0)
}

Python example

def tiered_amount_minor(quantity, tiers, mode):
    if mode == "volume":
        tier = next(t for t in tiers if t.up_to is None or quantity <= t.up_to)
        return quantity * tier.unit_minor
    total, previous = 0, 0
    for tier in tiers:
        upper = quantity if tier.up_to is None else min(quantity, tier.up_to)
        total += max(0, upper - previous) * tier.unit_minor
        previous = tier.up_to or previous
    return total

How to check

A unit test bills 1,500 units on the price above in each mode and gets 14,000 and 12,000 cents. A test bills a quantity exactly on a tier boundary and gets the documented result. Every tiered price in the catalogue has a mode.

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/usage-billing/usage-on-invoices/tiered-or-volume">Agent Wranglers usage-based billing playbook</a>. In code you write, add a comment next to it with the same link.