Skip to main content
Accounts receivable is money in: getting your customers paid up, quickly. Upwell’s job is to get an accurate invoice out the door and then apply the cash that comes back to the right invoices. Statements, reminders, aging, collections, and hosted payment pages all depend on each invoice’s current balance and status. Syncing invoices without a way to represent payments or an authoritative outstanding balance leaves those features with no reliable way to know what a customer still owes. This page defines the required AR data contract. For the payables side, see Accounts payable API.

​
The lifecycle

1

A shipment becomes an invoice

You create an invoice for a customer and link the shipments it bills. New invoices start in CREATED.
2

Charges go on it

Invoice line items carry the priced rows — line haul, fuel, accessorials — and sum to the invoice total.
3

It clears review

Rules and exceptions can hold an invoice back. Once it’s clean it’s approved for sending — either automatically or through the invoice approval queue.
4

It goes out

Delivery happens by email, customer portal, EDI, or print — or the invoice is rolled into a statement or list bill instead of being sent alone.
5

Cash comes back and gets applied

A customer payment records what arrived. Its line items say which invoices the money applies to. Upwell recalculates each invoice’s balance and moves it to PART_PAID or PAID.

​
Keep outstanding balances accurate

Use one of the following balance models. Do not mix a partial payment history with invoice balance snapshots: both systems would be trying to explain the same balance from incomplete data. This is the standard model for API integrations and gives Upwell a complete audit trail:
  1. Create each new invoice with balance equal to totalAmount.
  2. Create a customer payment when money is received.
  3. Create one customer payment line item for every invoice the payment applies to. A payment header without line items does not affect any invoice.
  4. Correct or delete the original payment line item when an application is changed, voided, returned, or removed. Changing only a payment or line-item status does not unapply its amount.
  5. Backfill open invoices and all payment applications that contribute to their current balances before enabling statements or reminders. Continue syncing both invoices and applications after cutover.
For an API-managed invoice, Upwell derives:
Upwell then sets the payment state from that result:
The amount used for a payment application is totalAmountWithFees when that field is present; otherwise it is totalAmount. Only send totalAmountWithFees when it is the principal applied to the invoice. Do not put processing fees or an unapplied gross payment in that field.
Payment and payment-line-item statuses are useful integration metadata, but a line item’s amount is what applies cash in the standard model. Create the linked line item only when the application should reduce the invoice balance.

​
Authoritative-balance model

If your source system cannot provide a complete payment-application ledger, it must provide the current outstanding balance and matching paid state for every invoice instead. Coordinate this model with Upwell before implementation; externally owned balances require integration-specific handling so local payment events and source-system snapshots cannot overwrite one another. At minimum, the source must:
  • send balance in integer cents whenever the amount owed changes;
  • send a matching status (PART_PAID, PAID, or the appropriate open lifecycle status);
  • backfill current balances and statuses before statements are enabled;
  • publish corrections and reversals, not only forward-moving payments; and
  • provide stable sourceSystem and sourceSystemId values so updates target the original invoice.
Do not implement the authoritative-balance model by sending occasional invoice snapshots alongside an incomplete set of payment line items. Contact Upwell to agree on ownership and cutover behavior first.

​
What statements use

Statement generation reads each stored invoice balance; it does not independently reconstruct what is owed from the source system. The invoice must also be linked to the correct customerId and have the dates and status required by the selected statement filter. The default All outstanding filter includes OPEN, APPROVED, OVERDUE, DISPUTED, PART_PAID, SENT, VIEWED, and DELIVERED. It excludes PAID, CANCELLED, and draft CREATED invoices. Use the All outstanding including created preset only when drafts are intentionally statement-ready. Before turning on statements, reconcile at least one full customer account and then the cutover population:
  • the sum of invoice balances in Upwell equals the source system’s customer balance;
  • every fully paid invoice has a zero balance and PAID status;
  • every partially paid invoice has the expected remaining balance and PART_PAID status;
  • voided or returned applications reopen the invoice when money is owed again; and
  • invoice issueDate and dueDate values produce the expected aging buckets.

​
The objects

Invoice vs. carrier invoice — same word, opposite directions of money. An invoice (inv_) is you billing your customer. A carrier invoice (cari_) is a carrier billing you. Throughout these docs an unqualified “invoice” is always the customer one. See Core concepts.
Payment line-item amounts need not sum to the payment total. A remittance can be partially applied and reconciled later, so don’t treat a shortfall as an error. Only the amount actually linked to an invoice reduces that invoice’s balance.

​
Before any of this works

Receivables reference records that have to exist first:
  • Customers — who you bill. Sync before invoices. Note that deleting a customer also deletes their invoices, so deactivate instead.
  • Shipments — the load being billed.
  • Documents — how supporting paperwork gets attached.
  • Rules — optional, but this is how you hold invoices that shouldn’t go out yet.
See Syncing foundation entities.

​
Guides for this side

Manage customer invoices

Create invoices, add line items, attach documents, link shipments.

Record customer payments

Create a remittance with its line items and reconcile it.

Receivables management

The AR dashboard, aging, and collections workflow.

Remittances

How remittance data arrives and gets matched.

Payment reminders

Automated follow-up on overdue invoices.

Online payments

Let customers pay from the portal.