Key concepts

Each term below has one example. Most examples use the same customer: account 2077, labelled Customer B, billed in USD.

Contract

One customer's usage terms, identified by the account id your usage data uses. A contract holds a label for statements, a currency, what counts as usage, clause references, and one or more segments.

Example: account 2077, label "Customer B", currency USD, term 1 January 2026 to 1 January 2027. Usage rows with account_id 2077 count against it. See modeling a contract.

Segment

The terms in force for a stretch of the contract, from a start date (inclusive) to an end date (exclusive). A new contract is segment 1. Each amendment closes the current segment on its effective date and opens a new one. Earlier periods are never recalculated.

Example: segment 1 runs 1 January to 1 July 2026 with 30,000 included credits per quarter. Amendment 1 takes effect on 1 July, so segment 2 runs 1 July 2026 to 1 January 2027 with 40,000 per quarter. See amendments.

Commit

What the customer agreed to pay for a segment's term, entered as the commit amount. TrueUpp uses it to price a minimum-commit shortfall line: the commit amount divided by the credits granted over the term gives the commit rate.

Example: a one-year segment with 30,000 included credits per quarter and a commit amount of $120,000. Over the year it grants 120,000 credits, so the commit rate is $1.00 per credit. See shortfall lines.

Included credits

The credits a segment grants each true-up period before any overage. Unused included credits lapse at the end of the period unless the contract has rollover.

Example: 30,000 included credits per quarter. In a quarter where the customer uses 26,000 credits, 26,000 are drawn from included and 4,000 are left unused.

Metric weight

How many credits one unit of a metric draws, set as credits per unit in the credit pool. Every metric in the pool draws on the same included credits. Metric names must match your usage data exactly; a metric that isn't in the pool is left out and raises a Review exception.

Example: api_requests at 1 credit per unit and exports at 5. A month with 26,000 API requests and 1,200 exports uses 26,000 + 6,000 = 32,000 credits.

Free allowance

Units of a metric that are free each calendar month, set per metric as free units / month. Free units come off before anything is drawn. They don't pool across metrics, don't roll over and don't count toward overage.

Example: the first 2,000 api_requests each month are free. In the month above, 32,000 credits are used, 2,000 are free, and 30,000 are drawn from included credits.

Rollover lot

Unused included credits that carry into later periods. Each lot has its own expiry date, is drawn before the period's included credits (earliest expiry first), and lapses if it isn't used by then. Rolled credits don't roll again.

Example: in January the customer uses 600 of 1,000 included credits and 200 roll over. That 200-credit lot is created on 1 February and expires on 1 March, so it covers February's usage. February's first 200 credits come from the lot, the next 1,000 from February's included credits. See rollover, amendments and late usage.

Rollover cap

The most that can roll over, as a percentage of one of two things: the commit (the period's included credits) or what's left unused. TrueUpp never assumes which; you choose it on every contract that has rollover.

Example: a 20% cap on 1,000 included credits, with 600 used and 400 unused. As 20% of the commit, 200 roll over. As 20% of what's left unused, 80 roll over. The other credits lapse.

Grace

Extra credits per period used after included credits and before overage. Grace is free, never rolls over, and resets each period.

Example: 50 grace credits per month. A month that needs 1,100 credits against 1,000 included uses 1,000 included, 50 grace, and bills 50 as overage.

Overage tier

A price band for credits above everything included. Each tier has an upper limit counted in overage credits, and the last tier is open-ended. Tiers fill from the bottom up, and reset each true-up period or each calendar month.

Example: the first 5,000 overage credits at $1.00 and the rest at $0.75. A quarter with 8,000 overage credits costs 5,000 × $1.00 + 3,000 × $0.75 = $7,250.00. See tiers, rounding and currency.

True-up period

How often usage is settled against the contract: monthly, quarterly or annually. Periods are counted from the segment's start date. A segment that starts or ends partway through a period produces a partial period, whose included credits are prorated by days unless you turn that off.

Example: a quarterly contract starting 1 January has periods January to March, April to June, and so on. A monthly segment ending on 16 June has a last period of 1 to 16 June: 15 of June's 30 days, so 500 of its 1,000 included credits.

Run

One calculation pass over your contracts. A run closes every period that ended by the date you choose, and counts only usage imported before its cutoff; later imports belong to the next run. You can start runs by hand or set a scheduled close day.

Example: on 3 October you start a run that closes periods ending by 1 October, with a cutoff of now. It covers Q3 for quarterly contracts and September for monthly ones. See running the close.

Line

An amount a run drafts for a contract and period. A line is an overage line (the period's true-up), an adjustment (late usage for an earlier period) or a shortfall (unused commit at the end of a term). Lines move from draft to approved, pushed and invoiced. A later run replaces a draft with a new version if its numbers change.

Example: Customer B's Q3 overage line: 8,000 overage credits, $7,250.00, status draft.

Trace

The step-by-step calculation behind a line, stored with it and shown exactly as it was calculated: usage by metric, free allowance, rollover lots drawn, included credits drawn, grace, overage units, and the tier pricing. Each step shows its clause reference, or a warning where there isn't one.

Example: api_requests 26,000 × 1 credit = 26,000; exports 1,200 × 5 credits = 6,000; monthly free allowance −2,000; included credits drawn −30,000 of 30,000 granted (clause "MSA Schedule B §1"); overage units 0; amount $0.00.

Exception (Review, Data, Info)

Something a run found that a person should look at, listed in the exceptions inbox. There are three severities.

• Review blocks approval of its line until someone resolves it with a note. Example: usage arrives for a metric that isn't in the contract's pool.
• Data blocks approval of the line for that contract and period until someone acknowledges it with a note. Example: a month inside the period has no usage rows, so it was treated as zero.
• Info never blocks. You can suppress an Info code for a contract. Example: 120 credits of a rollover lot expired unused.

See exceptions for every code.

Adjustment

A line that posts usage for a period whose line was already approved or pushed. TrueUpp prices the late usage under that period's terms, continuing its tiers, and posts the difference on the next open period, pointing back at the period it relates to.

Example: March was pushed at 1,200 overage units, with the first 1,225 at $0.50 and the rest at $0.40. Fifty more units for March arrive in April. The adjustment is 25 × $0.50 + 25 × $0.40 = $22.50, posted on April's line. See rollover, amendments and late usage.

Locked period

A period whose line is approved, pushed, invoiced, or voided in the billing system after it was pushed. A locked line never changes. Later runs replay the period and post any difference as an adjustment.

Example: Q2 was approved on 4 July. A run on 10 July with corrected Q2 usage leaves the Q2 line as approved and drafts an adjustment on Q3 instead.