Glossary
Upwell sits at the intersection of freight, accounts payable, and accounts receivable, so the vocabulary comes from all three. This page defines the terms and objects that come up across the product and the API — in plain language. For the money-flow objects and how they connect, start with the data model; this page is the wider dictionary.Terms are grouped by where they come from — the objects, then freight & logistics, accounts payable / receivable, Upwell product concepts, and developer conventions. Within each group they’re roughly ordered by how often you’ll meet them.
Objects
The core money-flow objects — shipment, customer, carrier, invoice, bill, carrier invoice, document, customer payment, bill payment — are defined on the data model page. A few more objects show up in the API and the app that the data model doesn’t cover:| Object | What it is |
|---|---|
| Vendor | A party you owe money that isn’t necessarily a hauling carrier — a lumper service, a factor, a utility, a non-freight supplier. A bill is owed to either a carrier or a vendor: the API exposes both carrierId and vendorId, and only one is set. Where a carrier carries freight identifiers (SCAC, DOT#, MC#), a vendor is a lighter record — mostly a name and where it came from. |
| Company | A shared organization record that other objects — addresses and shipments — can reference, carrying business identifiers such as a DUNS number and MC number. |
| Stop | A single point on a shipment’s route — a pickup, delivery, terminal, cross-dock, fuel stop, and so on. A shipment has an ordered list of stops (each with a sequence number, an address, and often an appointment). See appointment type below. |
| Line item | One priced row on an invoice, bill, or payment — e.g. a line haul charge, a fuel surcharge, or an accessorial. On invoices and bills the line items sum to the total; on a customer payment they need not — a remittance can be partially applied, so the applied line items may total less than the amount received. Invoices, bills, shipments, and payments each have their own line-item type. |
| Payment line item | How a single customer payment splits across the invoices it pays — one line item per invoice the money is applied to. This is what makes cash application work when one check covers many invoices. |
| Rule | A configurable if-this-then-that instruction Upwell evaluates during processing — to require a document, raise an exception, route by SCAC, or set the customer. Rules are how each account tailors the audit and matching to its own policies. |
| Address | A physical address attached to a customer, carrier, company, or stop. Addresses are typed (billing, pickup, delivery, remit-to, and so on) so the same party can hold several. |
| Approval request | A pending decision on a carrier invoice that Upwell hands to an external system to resolve. See how approvals work. |
Freight & logistics
| Term | Plain-language meaning |
|---|---|
| Shipment (load) | One freight movement from origin to destination. In Upwell, the hub that invoices, bills, and documents hang off. “Load” is the same thing. |
| Shipper | The party whose freight is being moved — in Upwell this is your customer (the one you bill). “Customer” and “shipper” are used interchangeably. |
| Mode | How the freight moves. Common values: LTL (less-than-truckload — you share a trailer and pay for part of it), TL / FTL (truckload / full truckload — you take the whole trailer), and INTERMODAL (rail + truck). |
| Line haul | The base charge for moving the freight from A to B, before any extras. |
| Accessorial | Any charge on top of the line haul — detention, lumper, liftgate, fuel surcharge, layover, and the like. |
| Lumper | A third party paid to load or unload a trailer (common at warehouses/grocery DCs). A lumper receipt proves the charge; a carrier invoice with a lumper line item but no receipt raises an exception. |
| Detention | A charge for a truck kept waiting beyond the free time allowed to load or unload. |
| TONU | ”Truck Ordered, Not Used” — a fee when a carrier is booked and shows up but the load is cancelled. |
| Layover | A charge when a driver has to wait overnight (or longer) between pickup and delivery. |
| Appointment type | How a stop’s timing works: APT (a scheduled appointment window) or FCFS (“first come, first served” — no appointment, handled in arrival order). |
| Freight charge terms | Who owes the freight charge and when — e.g. prepaid (shipper pays), collect (consignee pays), or third-party billing. |
| Owner-operator | A carrier that is a single driver who owns their truck, rather than a larger fleet. |
| BOL (bill of lading) | The contract/receipt for a shipment, issued when freight is picked up. Lists what’s being shipped, from and to whom. |
| POD (proof of delivery) | A signed document confirming the freight was delivered. Over the API its document type code is PROOF_OF_DELIVERY (POD is only the display label). |
| Rate confirmation | The document that confirms the agreed rate for a load. Upwell distinguishes a carrier rate confirmation (what you owe the carrier — payables) from a customer rate confirmation (what you charge the customer — receivables). |
| SCAC | Standard Carrier Alpha Code — a short code identifying a carrier. Upwell uses it to match carrier invoices that reference a SCAC instead of a name. |
| DOT number | The carrier’s U.S. Department of Transportation registration number. |
| MC number | Motor Carrier number — a carrier’s FMCSA operating-authority number. |
| DUNS number | A Dun & Bradstreet business identifier, used to identify a company. |
| PRO number | The carrier’s tracking number for a shipment (from the carrier’s own system). Upwell treats it as one of the strongest keys for matching a carrier invoice to a shipment. |
| Lane | An origin–destination pair a carrier runs (e.g. Chicago → Dallas). Used in reporting to compare cost and volume by route. |
Accounts payable & receivable
| Term | Plain-language meaning |
|---|---|
| AR (accounts receivable) | Money in — getting your customers (shippers) to pay you. |
| AP (accounts payable) | Money out — paying your carriers and vendors accurately. |
| Receivable | An amount a customer owes you (a customer invoice). |
| Payable | An amount you owe a carrier or vendor (a bill). |
| Aging | How long a receivable has been outstanding, bucketed by age (e.g. 0–30, 31–60, 61–90 days). Drives collections priority and reminder timing. |
| Dunning | The sequence of increasingly firm reminders sent to collect an overdue invoice. See payment reminders. |
| Cash application | Matching an incoming payment to the open invoices it pays, then marking those invoices paid. See recording customer payments. |
| Remittance | A notification of payment — the record of what a customer sent and which invoices it’s meant to cover. In everyday use it’s spoken of interchangeably with a customer payment (pym_). If you build against the API, note that webhooks also expose a distinct lower-level remittance resource (with its own line items) that can arrive separately — e.g. over EDI — from the applied customer payment; treat them as related but separate streams. |
| Short pay | When a customer pays less than the invoiced amount, leaving a balance to resolve. |
| Write-off | Formally giving up on collecting a balance and closing it off the books (invoice status WRITE_OFF). |
| Reconciliation | Confirming that recorded payments and balances agree with the money that actually moved (e.g. against a bank feed). |
| Credit limit | The maximum outstanding balance an account will extend to a customer; exceeding it can block new invoices (INSUFFICIENT_CREDIT_LIMIT). |
| Payment terms | How long a customer has to pay, e.g. Net 30 (due 30 days after issue). Drives aging and reminder scheduling. |
| ACH | Automated Clearing House — an electronic bank-to-bank transfer, a common way customers pay and carriers get paid. |
| Quick Pay | An arrangement where a carrier is paid faster than standard terms, usually for a small fee or discount. Carriers can be flagged as Quick Pay, and auto-approval can be set to exclude them. |
| Factoring | When a carrier sells its receivables to a third party (a factor) who then gets paid instead of the carrier. Signaled by a Notice of Assignment (NOTICE_OF_ASSIGNMENT) document and reflected in the invoice’s remit-to. |
| Remit-to | Where a payment should actually be sent — which can differ from the carrier when a factor is involved. A remit-to mismatch is a common audit exception. |
Upwell product concepts
| Term | Plain-language meaning |
|---|---|
| Tenant | One customer organization’s isolated space in Upwell. Data never crosses tenant boundaries; “per-tenant” means a setting or behavior applies to just that organization. |
| Foundation entities | The prerequisite records a TMS integration syncs first — customers, carriers, shipments, and bills — before invoices and documents can be matched to them. See syncing foundation entities. |
| Exception | An audit finding that flags something needing attention before an invoice can be approved. See exceptions. |
| Matching | Linking an incoming carrier invoice to the right shipment, carrier, and bill so it can be audited. Until matching runs, a new invoice shows “no matching” findings that clear on their own. |
| Ingestion | The first processing phase — a document/invoice arrives, is classified, matched, and audited — as distinct from the later review-and-approval phase. See the carrier-invoice lifecycle. |
| Auto-approval | Rules that approve clean, in-guardrail carrier invoices with no human clicking. See approvals. |
| Needs Review | The work queue in the app for carrier invoices that aren’t cleared yet — where reviewers work exceptions and approve. |
| Portal | Two different things share this word: (1) the customer portal — the self-service page where your customers view and pay their invoices (AR); and (2) audit-and-payment portals — third-party systems like Cass, CTSI, or MercuryGate that some shippers require carrier invoices to be submitted through and that send status back (AP). |
| CASS (Cass Information Systems) | A large third-party freight-bill audit-and-payment provider. Some shippers pay through Cass, so Upwell can submit to and read invoice status from the Cass portal, and can match a customer by their Cass ID. |
| Breakthrough Fuel | A third-party fuel-price/fuel-recovery provider. Upwell ingests fuel data batches from Breakthrough Fuel; over webhooks these appear as btf_batch events. |
| EDI | Electronic Data Interchange — a standardized format for exchanging business documents (invoices, remittances, status) between systems, used by many shippers and portals. |
| Integration / source system | An external system connected to Upwell (a TMS, a portal, an API client). Every synced record is stamped with the sourceSystem it came from. See developer conventions. |
| Feature flag | A per-organization switch that turns a section or capability on or off, so what one account sees can differ from another. |
| Roles | Who can do what in the app: Member (ORGMEMBER, day-to-day work), Admin (ORGADMIN, user and workflow configuration), Owner (ORGOWNER, full control including billing), and SYSADMIN (Upwell staff, cross-tenant). See user roles. |
| Trevor | The embedded third-party business-intelligence tool behind the analytics dashboard — deeper reporting inside the app, no separate login. |
Developer conventions
These come up throughout the API. Each is covered in depth on the linked page — they’re here so the vocabulary is in one place.| Term | Plain-language meaning |
|---|---|
| Integer cents | All money is sent and returned as whole cents — $2,847.50 is 284750. No decimals, no currency symbols. See the quickstart. |
sourceSystem / sourceSystemId | Your external identity / uniqueness key — a constant string naming your system plus your own primary key for the record, unique per tenant, tying an Upwell record back to yours. It is not a general upsert: POST a record once, then PUT to update it; re-POSTing the same pair is rejected as a 400 Uniqueness violation (carrier invoices are the async exception — the duplicate is discarded, not errored). See integration patterns for the per-endpoint retry/update semantics. |
| ID prefixes | Every Upwell ID is prefixed by its type — e.g. shi_ shipment, cus_ customer, car_ carrier, inv_ invoice, bil_ bill, cari_ carrier invoice, doc_ document, pym_ customer payment, pli_ payment line item, blp_ bill payment. See the data model. |
| Presigned URL | The two-step way to upload a large file: ask Upwell for a short-lived upload URL, then PUT the bytes to it. See integration patterns. |
| Standardized code sets | Currency codes (ISO 4217), country codes (ISO 3166), and the EDI accessorial, handling-unit, and weight-unit code lists are large industry-standard sets — the exact allowed values are in the API Reference rather than enumerated here. |
Something missing that you had to look up? That’s a gap worth closing — the goal is that no one has to ask what a term means. For the objects and how money moves between them, the data model is the place to start.