Skip to main content

Exceptions

An exception is an audit finding — Upwell’s way of flagging that something about an invoice doesn’t line up and a person should look at it. Exceptions are what stand between an invoice and approval: a clean invoice sails through, one with an open exception waits.

What raises an exception

Every invoice is audited as it’s ingested and matched. On the payables side that means checking a carrier invoice against its bill; on the receivables side it means checking a customer invoice against what’s required to send it. Anything that doesn’t reconcile — a mismatch, a missing document, a failed match — becomes an exception.
Exceptions exist on both sides. Carrier-invoice (AP) exceptions like a total-amount mismatch or a missing POD, and customer-invoice (AR) exceptions like a missing invoice copy or BOL, are both surfaced the same way. The audit rules that generate them are configurable per account, so the exact set an account sees varies.

The lifecycle

(The Vocabulary page carries this list in its generated form.) An exception moves through a small set of statuses: OPEN and IN_PROGRESS are the two “still needs attention” states — they’re what hold an invoice back. The rest mean the finding is no longer standing in the way.

Common exceptions

A representative sample of what Upwell flags (not exhaustive — the active set depends on your account’s audit rules):

Customer-required documents

Some customers require specific documents, such as a scale ticket, before a carrier invoice for their loads is approved. The list of required document types is configurable per customer. When a carrier invoice for that customer lacks one of those types, Upwell raises a Missing required document exception (CARRIER_INVOICE_MISSING_REQUIRED_DOCUMENT) that names each missing type. A required document counts as present when it’s attached to the carrier invoice itself or to its load (shipment). A scale ticket and a weight ticket satisfy each other. When you add, remove, or reclassify a document on the load, Upwell re-evaluates the carrier invoices on that load that aren’t yet approved or paid, so attaching the missing document through shipment documents clears the exception without a change to the invoice.

Container mismatch

When the Verify container number rule is on for your workspace, Upwell compares the container numbers on a carrier invoice with the load’s container number. If the invoice names any container that isn’t the load’s, Upwell opens a Container mismatch exception (CARRIER_INVOICE_CONTAINER_NUMBER_MISMATCH). The exception has one detail per extra container, and each detail names both the invoice’s container and the load’s. Upwell ignores spaces, dashes and letter case when it compares the numbers. An invoice container counts only when it has a valid ISO 6346 check digit, so a misread number that fails the check digit doesn’t raise the exception. Invoice references labelled as pickup, return or empty containers are skipped. Loads with no container number, such as non-drayage loads, and invoices that name no container aren’t checked.

How exceptions affect approval

Open and in-progress exceptions are the gate on approval — but the exact rules differ by side: Carrier invoices (AP):
  • Auto-approval skips any carrier invoice with an open or in-progress exception entirely — no override.
  • Manual approval can override open exceptions to approve anyway — with one exception: Carrier Pay Frozen can never be overridden and must be cleared first.
Customer invoices (AR):
  • Approval can likewise proceed over open exceptions with an explicit override, but there’s no Carrier Pay Frozen carve-out (that’s a payables hold). There’s no carrier-invoice-style auto-approval on the AR side.
  • Critical exceptions can’t be overridden. While a customer invoice has an open or in-progress exception with CRITICAL severity, Upwell refuses to approve, send, or schedule it, even with overrideExceptions=true. Approving it returns the CRITICAL_EXCEPTIONS error code with the message Invoice cannot be approved until critical exceptions are resolved. Resolve the critical exception first. The refused approval changes nothing, so the invoice’s other open exceptions stay open too. Delivery exceptions, which record a failed send that Upwell is still retrying, don’t block approval even when marked critical.
  • Warnings from a warn-only shipper rule (CUSTOMER_INVOICE_WARNING) never block approval or sending, and need no override. Approval leaves them open; they resolve when the rule passes or someone closes them.
For the approval paths in full — manual, auto-approval, and the external request-for-approval — see How carrier invoices get approved; for the lifecycle and API signals, see Knowing when a carrier invoice is processed. Over the API, a carrier invoice exposes its open findings as the exceptions field — a comma-joined string (e.g. "INVOICE AMOUNT MISMATCH"), empty when clean.
Don’t judge exceptions until ingestion has run. A brand-new invoice always shows matching findings (“no matching shipment / bill”) that clear on their own once matching completes — see the lifecycle guide.
For how exceptions are surfaced and worked in the app, see Carrier invoice audit. For the objects referenced here, see the data model.