Importing contract terms

The YAML used in a TrueUpp leakage audit is the import format, so an audit converts into contracts without retyping. JSON with the same shape works too. Import files under Contracts › Import terms: choose the file, click Preview to check what will be created, then confirm.

Audit YAML or JSON

account_id: "2077"
label: Customer B
currency: USD
contract_start: 2026-01-01
contract_end: 2027-01-01      # exclusive
true_up: quarterly            # monthly | quarterly | annual
included_units: 30000
pool: { api_requests: 1, exports: 5 }
monthly_free_units: { api_requests: 2000 }
rollover: { cap_pct: 0.25, cap_basis: commit, expires_after_days: 60 }
overage:
  tier_reset: true_up_period
  tiers: [ { up_to: 5000, rate: 1.00 }, { up_to: null, rate: 0.75 } ]
amendments:
  - effective: 2026-07-01
    reference: Amendment 1 §2
    note: Upgrade to 40,000 credits per quarter
    included_units: 40000
references: { included_units: MSA Schedule B §1, overage: MSA Schedule B §6 }

The top-level terms become segment 1. Each amendment opens a new segment from its effective date.
cap_basis is required whenever rollover is on. If the file doesn't say, the importer asks; it never assumes.
opening_balance becomes an opening rollover lot, capped if it exceeds what the cap allows (and flagged).

For a complete file you can import and check against known results, download the Customer B example from the getting started walkthrough.

Bulk: contract segments CSV

contract_id,segment_id,start,end,period_months,included_units,overage_rate,rollover_cap_pct,rollover_cap_basis,rollover_periods,prorate_partial,carry_forward,amendment_id

One row per segment, many contracts per file, with one flat overage rate per segment. Add tiers, pool weights and clause references afterwards if a contract has them.

An optional metric_name column names the metric each segment counts; without it, the metric is units. prorate_partial and carry_forward are on unless set to 0, false, no or n.

Validation errors

Nothing is created until a file passes every check. If one fails, the preview shows the reason and nothing is imported. The messages you may see:

Message	What to fix
Missing required field: `account_id` (or `contract_start`, `contract_end`, `true_up`)	Add the field to the YAML or JSON.
true_up must be monthly, quarterly or annual	Use one of those three words.
Segment 2: …	The terms in force from the first amendment fail a check; the reason follows. Segment 1 is the top-level terms.
Line 4 (C-1001): …	In a segments CSV, the row on that line of the file fails a check.
Start must be a date (YYYY-MM-DD)	Write dates as `2026-01-01`.
End must be after start	Check the dates, remembering the end date is exclusive.
Rollover cap is a fraction between 0 and 1 (20% = 0.2)	Write 25% as `0.25`.
Choose what the rollover cap is a percentage of	Set `cap_basis` (or `rollover_cap_basis` in the CSV) to `commit` or `unused`.
Give rollover expiry as days after period end or as a number of periods, not both	Keep one of the two.
The last tier must be open-ended (no upper limit)	Set the last tier's `up_to` to `null`.
Only the last tier can be open-ended	Give every other tier an `up_to`.
Tier limits must be ascending	Order tiers from the lowest `up_to` to the highest.
Included units can't be negative (or another field)	Amounts, units and rates must be zero or more.
Add at least one metric to the pool	List at least one metric under `pool`.

A file larger than 5 MB isn't accepted. Importing also counts towards your plan's active contracts; if the new contracts would take you over, the message says how many you have and what to do. See plans and billing.