Skip to main content

​
Core concepts & data model

Upwell sits between your TMS and your money. It has two jobs:
  • Accounts receivable (AR) — money in. Getting your customers (shippers) to pay you, quickly.
  • Accounts payable (AP) — money out. Making sure what you pay your carriers is accurate.
Almost everything in the product is one of a small set of objects. Learn these once and the rest of the docs read easily.

​
The objects

ObjectID prefixSideWhat it is
Shipment (load)shi_—A freight movement from your TMS. The hub everything else hangs off — it carries a customer and a carrier.
Customer (shipper)cus_ARWho you bill and collect from.
Carriercar_APWho hauls the freight and gets paid.
Invoiceinv_ARWhat you bill your customer. “Invoice” on its own always means this — the customer/AR invoice.
Billbil_APWhat your TMS says you expect to owe a carrier for a shipment. The expected payable.
Carrier invoicecari_APWhat a carrier actually billed you — the document they send. The received payable.
Documentdoc_bothA file — BOL, POD, rate confirmation, etc. — attached to a shipment, invoice, or carrier invoice.
Customer payment (remittance)pym_ARMoney received from a customer, split into line items that apply to invoices.
Bill paymentblp_APA payment that settles what you owe a carrier.
Two more terms come up constantly but aren’t objects you create directly — they’re records Upwell derives on the payables side:
  • Exception — a flagged mismatch found when auditing a carrier invoice against its bill (e.g. an amount mismatch). Exceptions live on the carrier invoice; see Carrier invoice audit.
  • Approval request — a pending decision on a carrier invoice, awaiting sign-off before Upwell proceeds. See Responding to an approval request.

​
How they connect

A shipment ties the two sides together: the same load you invoice a customer for (AR) is the load a carrier bills you for (AP).

​
Three pairs people mix up

Both are on the payables side, and this is the one that trips people up most.
  • A bill (bil_) is what your TMS says you should owe a carrier — the expected amount.
  • A carrier invoice (cari_) is what the carrier actually sent you — the received amount.
Upwell’s core AP job is auditing the carrier invoice against the bill. When they don’t agree, that difference becomes an exception.
Same word, opposite directions of money:
  • An invoice (inv_) is you billing your customer — accounts receivable, money in.
  • A carrier invoice (cari_) is a carrier billing you — accounts payable, money out.
Throughout the docs and API, an unqualified “invoice” always means the customer/AR invoice.
  • Your customer (cus_) is the shipper — they pay you (AR).
  • Your carrier (car_) is who you hire to move the freight — you pay them (AP).

​
How money moves

1

Receivables — collecting from customers (money in)

A shipment produces an invoice to the customer. When they pay, that arrives as a customer payment whose line items apply to the invoices it covers. See Recording customer payments and Accounts receivable management.
2

Payables — paying carriers accurately (money out)

Your TMS provides a bill — what you expect to owe the carrier. The carrier sends a carrier invoice; Upwell audits it against the bill and flags exceptions for any mismatch. Once it’s approved, a bill payment settles it. See Carrier invoice audit and Submitting carrier invoices via API.
This page defines the objects; the guides go deeper on each. For the exact fields and endpoints, the API Reference is generated directly from the live API.