Agent Wranglers

PRC-13Recommended

Bill committed-use contracts against the commitment and true up at term end

Store each committed-use contract with its commitment amount, term, overage rate and true-up date. Draw usage down against the commitment, and bill any shortfall or overage once, on the true-up date, from the same usage records.

By Agent Wranglers. Updated .

How to do it

A customer who commits to 100,000 USD a year in exchange for a discount owes the difference if they use less. A customer who uses more pays the overage rate. Keep the contract terms as data with a version, the same way Keep prices in a versioned catalogue keeps prices. Show the customer the drawn-down amount and the days left in the term. Bill the true-up as its own invoice line with the commitment, the usage and the difference. Give each true-up a unique key per contract and term, so a rerun never bills twice. Hand the amounts to Recognise revenue as it is earned, since a minimum commitment changes when revenue counts.

Examples

TypeScript example

export function trueUpMinor(contract: { commitmentMinor: number }, usedMinor: number) {
  const shortfallMinor = Math.max(0, contract.commitmentMinor - usedMinor)
  const overageMinor = Math.max(0, usedMinor - contract.commitmentMinor)
  return { shortfallMinor, overageMinor }
}

export async function billTrueUp(db, contract, termId: string) {
  const usedMinor = await db.usageMinor(contract.id, termId)
  const { shortfallMinor, overageMinor } = trueUpMinor(contract, usedMinor)
  await db.insertInvoiceLine({ key: `true-up:${contract.id}:${termId}`, shortfallMinor, overageMinor })
}

Python example

def true_up_minor(commitment_minor: int, used_minor: int) -> tuple[int, int]:
    shortfall = max(0, commitment_minor - used_minor)
    overage = max(0, used_minor - commitment_minor)
    return shortfall, overage

def bill_true_up(db, contract, term_id: str) -> None:
    used = db.usage_minor(contract.id, term_id)
    shortfall, overage = true_up_minor(contract.commitment_minor, used)
    db.insert_invoice_line(key=f"true-up:{contract.id}:{term_id}", shortfall_minor=shortfall, overage_minor=overage)

How to check

A test runs a 12-month contract with a 10,000 USD commitment and 7,500 USD of usage. The true-up bills 2,500 USD once, and a second run bills nothing. A second test with 12,000 USD of usage bills 2,000 USD of overage.

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