Modeling a contract
Every field on the TrueUpp contract form with an example: account id, term, included credits, pool, tiers, rollover, clause references and currency.
On this page
A contract in TrueUpp is one customer's usage terms, entered once from the order form. Open Contracts › New contract. While you type, a Sample panel beside the form (Sample month, Sample quarter or Sample year) works out one period with the real calculation engine, so you can check the terms against the order form before you save.
To bring in many contracts at once, or the YAML from a TrueUpp audit, see importing contract terms. To understand any term below, see key concepts.
The examples on this page model one contract: Customer B, quarterly, 30,000 included credits per quarter.
The customer
| Field | What it is | Example |
|---|---|---|
| Account id | The customer's id exactly as it appears in your usage data. Usage rows with this account_id count against the contract. One contract per account id. | 2077 |
| Label | The name printed on statements. Use a company name or a redacted label. | Customer B |
| Currency | The currency the contract is priced and billed in. | USD |
TrueUpp stores no end-customer personal data. If a label looks like an email address or a person's name, the form warns you. If it isn't personal data, click It's not personal data, save.
Usage for an account id that had no contract yet is held as unmapped. It attaches to the contract when you save it.
Term and true-up period
| Field | What it is | Example |
|---|---|---|
| Term starts | The first day the terms apply. | 2026-01-01 |
| Term ends (exclusive) | The first day no longer covered. A calendar-year term ends on 1 January of the next year. | 2027-01-01 |
| True-up period | How often usage is settled: Monthly, Quarterly or Annual. Periods are counted from the start date. | Quarterly |
Included credits, grace and commit
| Field | What it is | Example |
|---|---|---|
| Included credits per period | The credits each full period grants before overage. The label follows the true-up period ("per quarter"). | 30,000 |
| Grace per period (optional) | Credits used after included credits and before overage. Never rolls over. | 500 |
| Commit amount (optional) | What the customer committed to pay for the term, in the contract's currency. It prices a minimum-commit shortfall line. | 120,000 |
The commit amount does nothing on its own. It matters only when Minimum-commit shortfall is billable is ticked. See minimum commits and shortfall lines.
Credit pool
One row per metric that draws on the included credits. Add rows with + Add metric.
| Column | What it is | Example |
|---|---|---|
| Metric | The metric name exactly as it appears in your usage data. | api_requests |
| Credits per unit | How many credits one unit draws. Defaults to 1. | 1 (and 5 for exports) |
| Free units / month (optional) | Units of this metric that are free each calendar month. They don't pool, roll over or count toward overage. | 2,000 |
With the example pool, a month of 26,000 API requests and 1,200 exports uses 26,000 + 6,000 = 32,000 credits, of which 2,000 are free.
Usage for a metric that isn't in the pool isn't counted, and raises a Review exception so someone checks it.
Overage tiers
Each row is a price band for overage credits. Add bands with + Add tier.
| Column | What it is | Example |
|---|---|---|
| Up to (credits of overage) | The band's upper limit, counted in overage credits, not total usage. The last band has no limit. | 5,000 |
| Rate per credit | The price per overage credit in the contract's currency. | 1.00, then 0.75 for everything above |
| Tiers reset | Whether bands start again each true-up period or each calendar month within it. | each quarter (the true-up period) |
For how bands fill, the reset choice and rounding, with worked numbers, see tiers, rounding and currency.
Rollover
Tick Unused included credits roll over if the contract lets unused credits carry forward.
| Field | What it is | Example |
|---|---|---|
| Cap (%) | The most that can roll over, as a percentage. Must be more than 0 and at most 100. Defaults to 20. | 25 |
| % of what? (required) | Whether the cap is a percentage of the commit (the period's included credits) or of what's left unused. TrueUpp never assumes; the form shows both readings in numbers. | of the commit |
| Rolled credits expire | Either after a number of following periods, or a number of days after the period ends. | 60 days after period end |
With the example, a quarter that leaves 10,000 credits unused rolls over 7,500 (25% of 30,000). Read as 25% of what's left unused, it would be 2,500. See rollover, amendments and late usage.
Proration and shortfall
- Prorate partial periods by days (on by default). When the term starts or ends partway through a period, that period's included credits are cut in proportion to its days. A monthly term ending on 16 June gets 15/30 of June's credits. Turn it off to grant the full amount.
- Minimum-commit shortfall is billable (Growth). At the end of the term, TrueUpp drafts a line for committed credits that weren't drawn, priced from the commit amount. See minimum commits and shortfall lines.
What counts as usage
| Field | What it is | Default |
|---|---|---|
| Count rows with status = failed | Whether line-level rows marked failed count. | On |
| Count retries (rows with retry_of) | Whether rows that retry an earlier request count. | On |
These change nothing for monthly aggregate usage, which has no status. You can change them later on the contract page under What counts as usage; the next run applies the change. See usage CSV formats.
Clause references
Each term in use gets a free-text reference to the clause it came from, such as Order Form §3.1. The form shows a box for each term the contract uses: included credits, credit pool and overage tiers always; free allowance, grace and rollover when you use them.
References print next to every number on the trace and on audit statements, so a customer's finance team can check each figure against their copy of the order form.
- On the contract page, Clause references holds contract-wide defaults. A segment's own reference, set on the form or when amending, wins for that segment.
- An amendment needs its own clause reference and a note before it saves.
- A term without a reference shows "no clause reference" on the trace, and each run raises an Info exception (
missing_clause_reference) listing what's missing. It never blocks approval.
Checks before you save
The Save contract button stays off until the form is complete. The Sample panel lists what's wrong:
- "End must be after start."
- "Included units must be a number."
- "Add at least one metric to the pool."
- "Tier 2: give its upper limit (only the last tier is open-ended)."
- "Tier limits must be ascending."
- "Rollover cap must be a percentage between 0 and 100."
- "Choose what the rollover cap is a percentage of. It is never assumed."
Saving also checks your plan. If the contract is active today and you're at your plan's limit, the message names the limit and how to free a slot. See plans and billing.
Currency
Each contract has one currency, and every amount on it uses that currency. TrueUpp does no currency conversion.
- Starter prices every contract in USD.
- Growth and Scale offer USD, EUR, GBP, CAD, AUD, INR, JPY and SGD on the form. The form starts on the workspace's default currency, set in Settings › General.
A contract's currency can't be changed after it's saved. See tiers, rounding and currency.
Stripe collection method
When TrueUpp creates a draft invoice in Stripe, the workspace setting Stripe draft invoice collection decides how it will be collected once your team finalizes it. It's set once for the workspace in Settings › General, not per contract, and only admins can change it.
| Option | What the draft invoice gets |
|---|---|
| Stripe's default for the customer (default) | Nothing set by TrueUpp. Stripe uses the customer's own setting. |
| Charge automatically when finalized | Collection method "charge automatically": Stripe charges the customer's payment method when your team finalizes the invoice. |
| Send invoice (30-day terms) | Collection method "send invoice", with 30 days until due. |
TrueUpp itself never finalizes, sends or charges. The setting applies to draft invoices created after you change it. NetSuite invoices don't use it.
After saving
The terms you saved become segment 1. Next:
- Map the billing customer. On the contract page, link it to a Stripe customer or, with NetSuite, enter the NetSuite customer's internal ID.
- Import usage, then start a run.
Saved terms aren't edited in place. When the customer's terms change, use Amend contract on the contract page: it closes the current segment on the effective date and opens a new one, and earlier periods are never recalculated. See amendments.
The contract page also has Sample-month clause, which turns the terms into a worked-example paragraph for the order form. See audit statements.
Archiving and deleting
Archive a contract you no longer bill. Archiving:
- frees its slot on your plan straight away;
- takes it out of new runs and of commit-pacing alerts;
- keeps its lines, statements and history, which stay available.
Restore brings it back. If the contract is active today, restoring needs a free slot on your plan.
Admins can also Delete a contract, but only if none of its lines were ever pushed to your billing system. A deleted contract is archived at once, and its usage is removed after 30 days. A contract with pushed lines can only be archived.