Exceptions

An exception is something a person should look at before a number goes out. Close runs raise most of them. Usage imports, pushes to your billing system, webhooks and alerts raise the rest. Each one names the contract and period it's about, and many point at a single line.

The inbox

Open Exceptions in the sidebar. The badge next to it counts open Review and Data exceptions.

• Tabs filter by Open, Review, Data, Info and Resolved. Review comes first, then Data, then Info.
• Select an exception to see its full message, a plain-language explanation for common codes, the line it's attached to (with a link to its trace) and the contract.
• Assign an exception to someone in the workspace.
• Export CSV downloads every exception, open and resolved, with its resolution note.

There is only ever one open exception for the same code, contract, period and line. A later run updates it rather than adding a second.

Severities

An open Review or Data exception blocks approval of the line it's attached to. One raised for a contract and period, without a specific line, blocks that contract's lines for that period. A few exceptions describe a contract's usage or history as a whole, with no period; they're listed for review but don't block a line.

Resolving

Approvers and admins can resolve exceptions. Analysts can read them.

1. Select the exception.
2. Write a resolution note saying what you checked and decided. The note is required, and it goes into the audit log.
3. Click the button. It reads Resolve for most codes, Acknowledge for no_usage_for_month and Accept adjustment for late_usage.

For a line voided in your billing system, Resolve and re-push also puts the line back to approved, as a new version, so the next push sends it to a new draft invoice.

Some exceptions close on their own:

• A later run that no longer produces an exception closes it, with the note "No longer produced by run #N".
• A successful push closes that period's customer_unmapped and push_failed exceptions.

When a resolved exception comes back

If a later run raises the same code for the same contract and period with the same numbers, it stays resolved. If the numbers have changed, it reopens, and the inbox shows how many times it has been reopened.

Suppressing

An Info exception can be switched off for one contract. Select it and click Don't raise <code> for this contract again. That resolves it, and later close runs don't raise that code for that contract. There's no undo button in the app today.

Suppression applies to exceptions raised by close runs. The two alert codes, discrepancy_alert and commit_pacing, are raised outside runs; turn alerts on or off in Settings › General. See alerts.

Review and Data exceptions can't be suppressed.

Exception codes

Usage data

no_usage_for_month

Data. A period has a month with no usage rows at all. TrueUpp treats the month as zero, and blocks approval of that period's line until someone confirms it.

Fix: if zero is right (the account was paused, say), click Acknowledge with a note. If usage is missing, import it and rerun.

overlapping_usage

Data. Two imported monthly files both cover the same account, metric and month. Raised when the second file is imported. Both are counted until you act.

Fix: in Usage imports, void the file that shouldn't count, then resolve the exception with a note and rerun.

duplicate_events

Data. Line-level rows with the same metric and event_id were found. Only the first was kept; the message says how many were dropped.

Fix: usually nothing to change, since retries from your side are safe. If different events share an ID upstream, fix the IDs at the source and reimport.

negative_usage

Data. A usage row has a quantity below zero. It's counted as it is, but it never draws credits.

Fix: check the source. If it's a mistake, correct the file, import it and void the old one. If it's a genuine reversal, resolve with a note.

usage_spans_months

Data. A monthly aggregate row runs across more than one month. It was assigned to the month it starts in.

Fix: split the row into one row per month, import the corrected file and void the old one.

usage_outside_segments

Data. Usage is dated outside every segment of the contract, so it was left out.

Fix: check the contract's start and end dates and its account ID. If the dates are wrong, correct the contract. If the usage belongs to another account, fix the account ID at the source.

imported_after_cutoff

Info. Some usage was imported after the run's usage cutoff, so this run didn't count it.

Fix: none needed. Rerun to include it. See the usage cutoff.

aggregate_usage_month_granularity

Info. Monthly aggregate usage is dated to the first of its month, so rollover expiry works by month, not by day. Statements say so.

Fix: none needed. For day-level expiry, send line-level usage.

failed_requests_excluded

Info. The contract says failed requests don't count, so rows with status failed were left out. The message gives the count.

Fix: none if that's what the contract says. Otherwise change the contract's usage-counting setting and rerun.

retries_excluded

Info. The contract says retries don't count, so rows with a retry_of value were left out.

Fix: as for failed_requests_excluded.

Contract terms

missing_clause_reference

Info. A segment uses a term (included credits, rollover, overage and so on) with no clause reference. Statements print a reference next to every term.

Fix: add the references on the contract page. See modeling a contract.

segment_gap

Data. Two of the contract's segments don't meet: there's a gap or an overlap between one's end and the next one's start.

Fix: check the contract's segment dates on its contract page. Contracts and amendments made in the app always meet end to start, so if you see this, contact hello@trueupp.com.

metric_not_in_pool

Review. Usage arrived for a metric the segment doesn't price. It was left out of the drawdown.

Fix: if it's rightly excluded, resolve with a note. If the metric should count from a date inside the term, amend the contract to add it and rerun; earlier periods aren't recalculated.

opening_exceeds_cap

Review. An opening rollover balance is larger than the contract's rollover cap allows. Only the capped amount was applied.

Fix: check how the cap was calculated in the system you came from, then resolve with a note recording what you found.

negative_balance_implies_mishandled_amendment

Review. An opening balance is negative. A balance can't go below zero, so it was treated as 0. This usually means a plan change reset the allowance instead of carrying it.

Fix: check the contract's history in the source system, then resolve with a note recording what you found.

cpq_segment_changed

Review. Salesforce CPQ shows different included units or a different rate for a segment TrueUpp already has. TrueUpp changed nothing.

Fix: if CPQ is right, amend the contract in TrueUpp. If TrueUpp is right, resolve with a note. See Salesforce CPQ sync.

Calculation

late_usage

Review. A period whose line was already approved or pushed would come out differently now, usually because usage arrived late. The locked line stays as it was. The difference is drafted as an adjustment on the next open period.

Fix: check the adjustment's trace, then click Accept adjustment with a note and approve the adjustment line. See late usage.

adjustment_unplaced

Review. An adjustment has no open period after the one it relates to, so it has nowhere to land.

Fix: if the contract has a later period, rerun once that period is in scope and the adjustment lands there. Otherwise post it by hand in your billing system and resolve with a note.

lot_expired

Info. Rollover credits in a lot expired unused. The message gives the amount, the lot and the date.

Fix: none needed.

commit_shortfall

Info. A segment drew fewer units than it committed to, and minimum-commit shortfall lines aren't on your plan.

Fix: bill the shortfall by hand if the contract allows it, or move to a plan that drafts shortfall lines. See shortfall lines.

commit_shortfall_pending

Info. A segment is running below its commitment so far. A shortfall line is drafted once the term ends, on the date in the message.

Fix: none needed now.

shortfall_needs_commit_amount

Review. A segment ended below its commitment, but has no commit amount to price the shortfall.

Fix: a past segment's terms can't be edited in the app today. Bill the shortfall by hand if the contract allows it, and resolve with a note.

Invoiced amounts

no_invoiced_amount

Data. No invoiced amount is recorded for the period, so expected is compared against zero.

Fix: upload a billed amounts file, or wait until the invoice is finalized in your billing system and rerun. If nothing was billed for the period, acknowledge with a note.

invoiced_period_unmatched

Data. An invoiced amount's period start doesn't match any true-up period of the contract, so it was ignored.

Fix: correct period_start in the billed amounts file so it matches the period's first day, and import it again.

Billing system

customer_unmapped

Review. The contract has no Stripe customer (or, for NetSuite, no customer internal ID), so its approved lines were skipped. Nothing was sent.

Fix: map the customer on the contract page and push again. A successful push closes this exception. See mapping customers or NetSuite.

push_failed

Review. Your billing system returned an error for this line. The message quotes the error, and for Stripe the request ID. The line stays approved.

Fix: act on the error (often a missing permission or the wrong account), then push again. A successful push closes this exception. See Stripe troubleshooting and troubleshooting.

invoice_voided_externally

Review. The draft invoice or invoice item was voided or deleted in Stripe, or the NetSuite invoice was rejected or deleted. It's also raised when the period's invoice is no longer a draft, so TrueUpp won't add lines to it. The line stays as history.

Fix: decide. Resolve and re-push sends the line to a new draft invoice on the next push. To write it off, resolve with a note.

pushed_line_changed_in_stripe

Review. A weekly check found that a pushed invoice item now bills a different amount in Stripe. TrueUpp's figure didn't change.

Fix: find out who changed it and why. Correct the item in Stripe, or resolve with a note recording the reason.

Alerts

Both alert codes are Info, need the Growth plan and alerts turned on. See alerts.

discrepancy_alert

Info. After a run, a period's expected and invoiced amounts differ by at least your threshold, under-billed or over-billed. Approvers get one email per run listing the new ones.

Fix: open the run and compare the trace with the invoice.

commit_pacing

Info. The daily projection says a contract will use more than your pacing threshold of its available credits this period, or half or less of them.

Fix: nothing to resolve. Use it to start an upgrade conversation, or to warn a customer whose credits may lapse.