> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upwell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Core concepts & data model

> The handful of objects Upwell is built around — shipments, invoices, bills, carrier invoices, payments — what each means, how they connect, and the terms people mix up.

# 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

| Object                            | ID prefix | Side | What 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_`    | AR   | Who you bill and collect from.                                                                             |
| **Carrier**                       | `car_`    | AP   | Who hauls the freight and gets paid.                                                                       |
| **Invoice**                       | `inv_`    | AR   | What **you bill your customer**. "Invoice" on its own always means this — the customer/AR invoice.         |
| **Bill**                          | `bil_`    | AP   | What your TMS says you **expect to owe a carrier** for a shipment. The *expected* payable.                 |
| **Carrier invoice**               | `cari_`   | AP   | What a **carrier actually billed you** — the document they send. The *received* payable.                   |
| **Document**                      | `doc_`    | both | A file — BOL, POD, rate confirmation, etc. — attached to a shipment, invoice, or carrier invoice.          |
| **Customer payment** (remittance) | `pym_`    | AR   | Money received from a customer, split into line items that apply to invoices.                              |
| **Bill payment**                  | `blp_`    | AP   | A 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](/accounts-payable/carrier-invoice-audit).
* **Approval request** — a pending decision on a carrier invoice, awaiting sign-off before Upwell proceeds. See [Responding to an approval request](/api-guides/carrier-invoice-approval).

## How they connect

```mermaid theme={null}
flowchart LR
  subgraph AR["Accounts receivable — money in"]
    Customer["Customer (shipper)<br/>cus_"]
    Invoice["Invoice<br/>inv_"]
    Payment["Customer payment<br/>pym_"]
    Customer -->|is billed on an| Invoice
    Payment -->|applies to| Invoice
  end

  subgraph AP["Accounts payable — money out"]
    Carrier["Carrier<br/>car_"]
    Bill["Bill — expected<br/>bil_"]
    CarrierInvoice["Carrier invoice — actual<br/>cari_"]
    BillPayment["Bill payment"]
    Carrier -->|is owed on a| Bill
    Carrier -->|sends a| CarrierInvoice
    Bill -.->|audited against| CarrierInvoice
    BillPayment -->|settles the| Bill
  end

  Shipment["Shipment / load<br/>shi_"]
  Shipment --> Customer
  Shipment --> Carrier
```

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

<AccordionGroup>
  <Accordion title="Bill vs. carrier invoice">
    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**](/accounts-payable/carrier-invoice-audit).
  </Accordion>

  <Accordion title="Invoice vs. carrier invoice">
    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.
  </Accordion>

  <Accordion title="Customer vs. carrier">
    * 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).
  </Accordion>
</AccordionGroup>

## How money moves

<Steps>
  <Step title="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](/api-guides/customer-payments) and [Accounts receivable management](/accounts-receivable/receivables).
  </Step>

  <Step title="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](/accounts-payable/carrier-invoice-audit) and [Submitting carrier invoices via API](/api-guides/carrier-invoice-submission).
  </Step>
</Steps>

<Note>
  This page defines the objects; the guides go deeper on each. For the exact fields and endpoints, the [API Reference](/api-reference/introduction) is generated directly from the live API.
</Note>