Agent Wranglers

USG-32Recommended

Bill commitment shortfalls and overages from the contract

Store each committed-use contract with its amount, period, what counts toward it and its overage price. At the period end, bill the shortfall or the overage on its own invoice line, computed by one tested function.

By Agent Wranglers. Updated .

How to do it

Larger customers often promise to spend an amount a year in return for a lower rate. At the end of the term, they owe the shortfall if they used less, and the overage rate if they used more. Keep the contract as data, never in a sales spreadsheet, so billing and the usage dashboard read the same terms. Show progress toward the commitment on the dashboard from Show live usage that matches the invoice. Write the true-up as its own line, so the customer can match it to the contract. Show each metered charge as its own line has the format.

Examples

JavaScript example

export function trueUpLines(contract, usedMinor) {
  if (usedMinor < contract.commitMinor) return [{ kind: 'shortfall', amountMinor: contract.commitMinor - usedMinor }]
  const overUnits = Math.ceil((usedMinor - contract.commitMinor) / contract.unitValueMinor)
  return overUnits > 0 ? [{ kind: 'overage', amountMinor: overUnits * contract.overageUnitMinor }] : []
}

Python example

import math

def true_up_lines(contract, used_minor):
    if used_minor < contract.commit_minor:
        return [{"kind": "shortfall", "amount_minor": contract.commit_minor - used_minor}]
    over_units = math.ceil((used_minor - contract.commit_minor) / contract.unit_value_minor)
    return [{"kind": "overage", "amount_minor": over_units * contract.overage_unit_minor}] if over_units else []

How to check

A unit test bills a 12,000 euro commitment with 9,000 euros of usage and gets a 3,000 euro shortfall line. With 15,000 euros of usage it gets the overage at the contract rate. Every active contract has an amount, a period and an overage price.

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/committed-use-true-up">Agent Wranglers usage-based billing playbook</a>. In code you write, add a comment next to it with the same link.