Accounts payable API - Upwell Developer Docs

Accounts payable is money out: making sure what you pay your carriers is accurate. Upwell’s job is to audit what a carrier actually billed you against what your TMS expected to owe — and to flag the difference. The endpoint reference is alphabetical, which is deliberately neutral but doesn’t tell you what belongs together. This page does. For the receivables side, see Accounts receivable API.

The lifecycle

Your TMS syncs the expected payable

You push a bill — what your TMS says you owe a carrier for a shipment.

The carrier bills you

A carrier invoice arrives, usually by email, or you submit it via API. It starts in RECEIVED.

Upwell matches and audits

Matching links the carrier invoice to its shipment, carrier, and bill. The audit compares them and raises exceptions for any mismatch — a wrong amount, a missing POD, an unexpected accessorial.

Someone approves it

A clean invoice can auto-approve; otherwise a reviewer clears the exceptions. If your system owns the decision, Upwell sends you an approval request and waits.

Payment settles it

A bill payment records the money going out, with carrier payment line items recording which bills it covered. The invoice reaches PAID.

The objects

Object	What it does
Bills	The expected payable from your TMS — the baseline the audit compares against. Owed to either a carrier or a vendor, never both.
Bill Line Items	Priced rows on a bill. No list endpoint — read them through the parent bill.
Carrier Invoices	The received payable — what the carrier actually sent. The AP entry point.
Carrier Invoice Documents	The invoice scan, BOL, POD, and notice of assignment attached to that invoice.
Carrier Invoice Approval Requests	A pending decision Upwell hands to your system to approve or reject.
Bill Payments	The money going out. Links to bills only through its line items, never directly.
Carrier Payment Line Items	Which bills a payment covered, and for how much.
Vendors	A payable party that isn’t a hauling carrier — a lumper service, a factor, a supplier.
Vendor Invoices	Non-freight AP invoices, parsed from a standalone PDF upload.
Purchase Orders	Inbound customer POs, parsed the same way and matched to vendor invoices.

Bill vs. carrier invoice is the distinction people get wrong most often. A bill is what your TMS says you should owe; a carrier invoice is what the carrier actually sent. Auditing one against the other is the whole point of AP. See Core concepts.

Before any of this works

Payables reference records that have to exist first. These aren’t AP-specific, so they live in their own guide:

Carriers — who gets paid. Sync before bills.
Shipments — the load a bill and invoice both point at.
Documents — the upload mechanism the invoice scan and POD travel through.

See Syncing foundation entities for all three.

Guides for this side

Submit a carrier invoice

Create the invoice, attach documents, record payment.

Know when it's processed

Poll or subscribe to learn when matching and the audit finish.

Respond to an approval request

Approve or reject from your own system.

Purchase orders & vendor invoices

Upload standalone PDFs and read the parsed records.

Carrier invoice audit

What the audit checks and how exceptions are raised.

Exceptions

Why an invoice is held and what clears it.

​The lifecycle

​The objects

​Before any of this works

​Guides for this side

Submit a carrier invoice

Know when it's processed

Respond to an approval request

Purchase orders & vendor invoices

Carrier invoice audit

Exceptions

The lifecycle

The objects

Before any of this works

Guides for this side