---
title: "Bill commitment shortfalls and overages · Agent Wranglers"
url: https://agentwranglers.se/playbook/usage-billing/usage-on-invoices/committed-use-true-up
id: USG-32
level: Recommended
applies: payments
updated: 2026-10-27
build: a2a6bdfed830
tokens: 950
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Bill commitment shortfalls and overages from the contract

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Usage on invoices](https://agentwranglers.se/playbook/usage-billing/usage-on-invoices.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: USG-32
- Level: Recommended
- Chapter: [Usage on invoices](https://agentwranglers.se/playbook/usage-billing/usage-on-invoices.md)
- Rule: 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.
- 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.
- Applies when: The project takes payments.
- How: 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](https://agentwranglers.se/playbook/pricing/spend-caps-and-alerts/usage-dashboard.md). 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](https://agentwranglers.se/playbook/usage-billing/usage-on-invoices/itemised-usage-lines.md) has the format.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### JavaScript example

```js
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

```python
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 []
```

## Related rules

- PRC-9 [Show live usage that matches the invoice](https://agentwranglers.se/playbook/pricing/spend-caps-and-alerts/usage-dashboard.md) in Pricing, plans and entitlements
- USG-19 [Show each metered charge as its own line](https://agentwranglers.se/playbook/usage-billing/usage-on-invoices/itemised-usage-lines.md) in Usage-based billing

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/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.

- Previous: [Bill early when unbilled usage passes a threshold](https://agentwranglers.se/playbook/usage-billing/usage-on-invoices/threshold-billing.md)
- [Usage on invoices](https://agentwranglers.se/playbook/usage-billing/usage-on-invoices.md)