> ## 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.

# Choose your integration path

> Start from what you want to accomplish, pick the right integration path, and know the prerequisites, first successful call, and production checklist for each.

export const Term = ({t, children}) => {
  const defs = {
    'invoice': {
      h: 'Invoice',
      tip: 'What YOU bill your customer — accounts receivable, money in. An unqualified "invoice" always means this.'
    },
    'carrier invoice': {
      h: 'Carrier invoice',
      tip: 'What a carrier actually billed you (AP) — the received payable, audited against the bill.'
    },
    'bill': {
      h: 'Bill',
      tip: 'What your TMS says you expect to owe a carrier for a shipment — the expected payable.'
    },
    'customer': {
      h: 'Customer',
      tip: 'The shipper — the party you bill and collect from (AR).'
    },
    'carrier': {
      h: 'Carrier',
      tip: 'Who hauls the freight and gets paid (AP).'
    },
    'shipment': {
      h: 'Shipment',
      tip: 'The freight movement (load) — the hub everything hangs off. Carries one customer and one carrier.'
    },
    'exception': {
      h: 'Exception',
      tip: 'A flagged audit finding on an invoice — a mismatch, missing document, or failed match. Open exceptions gate approval.'
    },
    'approval request': {
      h: 'Approval request',
      tip: 'A pending carrier-invoice decision handed to your integration to resolve (SUCCEEDED or FAILED).'
    },
    'vendor': {
      h: 'Vendor',
      tip: 'A payable party that is not a hauling carrier — a lumper service, a factor, a non-freight supplier.'
    },
    'company': {
      h: 'Company',
      tip: 'YOUR legal entity or brand — the name on the invoices you issue, not an external business.'
    },
    'customer payment': {
      h: 'Customer payment',
      tip: 'Money received from a customer (a remittance); its line items apply it to invoices.'
    },
    'bill payment': {
      h: 'Bill payment',
      tip: 'A payment settling what you owe a carrier; its line items apply to bills.'
    }
  };
  const key = (t || (typeof children === 'string' ? children : '')).toLowerCase();
  const d = defs[key];
  if (!d) return children ?? t;
  return <Tooltip headline={d.h} tip={d.tip} cta="Full glossary" href="/concepts/glossary#objects">
      {children ?? t}
    </Tooltip>;
};

# Choose your integration path

This page routes you from **goal** to **integration path**. Each path lists its prerequisites in
order, the shortest route to a first successful call, and the checklist that separates a demo
from a production integration. It links into the deeper guides rather than repeating them.

<Note>
  Statements marked **\[GAP]** are places the documentation cannot answer yet — they are kept
  visible deliberately so you don't discover them in production. If one blocks you, ask
  [support@upwell.com](mailto:support@upwell.com) and we'll answer it directly (and then document it).
</Note>

## Orient yourself first (10 minutes)

Whatever your path, read these two pages first — everything else assumes them:

<CardGroup cols={2}>
  <Card title="Core concepts & data model" icon="diagram-project" href="/concepts/data-model">
    The dozen objects and the two sides: AR (invoice your customers) and AP (audit what carriers bill you). Five minutes that prevents the classic mis-mappings.
  </Card>

  <Card title="Integration patterns" icon="wrench" href="/integration-patterns">
    The cross-cutting mechanics: integer-cents money, the `input` wrapper, `sourceSystem`/`sourceSystemId` upserts, per-resource retry semantics, addresses, deletes.
  </Card>
</CardGroup>

Three facts to carry into every path:

1. **Auth** — send your API key in the `Authorization` header; bare or `Bearer`-prefixed both
   work. Keys are self-serve in the dashboard and **scoped to one organization** — an
   integration serving several Upwell customers holds one key per customer, and keys are
   environment-specific. See [Authentication](/authentication).
2. **Money is integer cents.** `$2,847.50` → `284750`. Floats are rejected at runtime
   ([Money & payloads](/conventions/money-and-payloads)).
3. **Writes are not uniformly retry-safe.** `POST` duplicate handling differs per resource —
   customers hard-fail, carriers silently no-op, carrier invoices dedupe asynchronously. See
   [What happens if I retry a POST?](/developer-guide/what-happens-if) before writing retry code.

## Which developer are you?

<AccordionGroup>
  <Accordion title="I'm at a TMS / platform vendor, evaluating a native integration" icon="building">
    Read the two orientation pages, then [Syncing foundation entities](/api-guides/syncing-foundation-entities)
    to size the sync engine, and the [webhook event catalog](/api-guides/webhook-events) to see
    exactly which events Upwell will and won't push to you (foundation entities: none — your TMS
    stays the system of record).

    The operational facts to plan around:

    * **Credential model at scale.** One API key per customer organization, created inside each
      customer's own dashboard — there is no partner-level or cross-tenant credential, and no
      published partner/certification program today. Engage
      [support@upwell.com](mailto:support@upwell.com) (or your Upwell contact) to coordinate a
      multi-customer rollout. See [Key scope](/authentication#key-scope).
    * **Pre-production access.** A staging environment exists at
      `https://staging.api.upwell.com`; access is provisioned by Upwell rather than self-serve —
      see [Environments](/authentication#environments).
    * **Operational guarantees.** No SLA or status page is published, and the
      [changelog](/changelog) is where API and platform changes will be announced. If your
      evaluation needs commitments beyond that, that's a conversation with Upwell, not a docs
      page.
  </Accordion>

  <Accordion title="I'm at a broker/carrier that uses Upwell — 'get us connected'" icon="truck-fast">
    Your path is almost always: get an API key → push foundation data → pick the AP or AR flow
    below. Follow the [developer quickstart](/quickstart) top to bottom. API keys are generated
    in the Upwell dashboard (**Account → API keys**) by any org member — if you don't see the
    page, ask your Upwell admin to have it enabled ([Authentication](/authentication)).
  </Accordion>

  <Accordion title="I only need to consume events (ship data into my system)" icon="bell">
    You can be read-only: subscribe to webhooks in the Upwell dashboard (there is no
    subscription API) and correlate deliveries back via `GET` calls. Start with
    [Outbound webhooks](/api-guides/webhooks), then the [event catalog](/api-guides/webhook-events)
    — and read the reliability notes in Path D below, especially the 4xx behavior.
  </Accordion>

  <Accordion title="I need to know if something is even possible" icon="circle-question">
    Go straight to [Can I…?](/developer-guide/can-i) — a feasibility table for the questions
    integrators actually ask, each row with its evidence or an explicit gap.
  </Accordion>
</AccordionGroup>

## Path A — AP: submit and track carrier invoices

*You have <Term t="carrier invoice">carrier invoices</Term> (your own, or your carriers') and want Upwell to audit, approve, and
track them.*

<Steps>
  <Step title="Prerequisites, in dependency order">
    1. API key ([Authentication](/authentication)).
    2. Carriers, then shipments — a shipment needs `customerId`/`carrierId`, a **required**
       `shipmentId` string of your own, and `carrierProNumber` (the strongest invoice-match key).
       See [Syncing foundation entities](/api-guides/syncing-foundation-entities).
    3. <Term t="bill">Bills</Term> — optional but strongly recommended: without a bill there is no expected amount, so
       no amount-mismatch audit. Note `bills.proNumber` must equal the shipment's `shipmentId`
       (it is *not* the carrier's PRO — that goes on the shipment as `carrierProNumber`).
  </Step>

  <Step title="First successful call">
    `POST /api/rest/carrier_invoices` with the `input` wrapper, then attach the invoice PDF via
    the presigned flow. Follow [Submitting carrier invoices](/api-guides/carrier-invoice-submission)
    literally — including its warning that only the **presigned** upload path runs AI
    classification.
  </Step>

  <Step title="Observe the result">
    Ingestion is asynchronous. Poll `GET /api/rest/carrier_invoices/{id}` for
    `updatedAt > createdAt`, then read `exceptions` (a comma-joined string, empty = clean) and
    `shipmentId`. Don't judge `exceptions` before ingestion — matching findings clear on their
    own. Full signal table: [Knowing when a carrier invoice is processed](/api-guides/carrier-invoice-status).
  </Step>

  <Step title="Production checklist">
    * Webhooks **and** a reconciliation poll — a missed delivery must not strand an invoice
      ([carrier-invoice status guide](/api-guides/carrier-invoice-status)).
    * Retry handling for submits: a retried `POST` can hand you the id of the row async-dedup
      will soft-delete — reconcile per
      [Re-submitting](/api-guides/carrier-invoice-submission#re-submitting).
    * Error handling against **flat string errors** (`{"error": "Not-NULL violation…"}`), not a
      structured envelope — see [Error handling](/api-reference/error-codes).
    * Decide your approval model now: manual / auto-approval / external request — they gate
      differently on <Term t="exception">exceptions</Term> ([How approvals work](/concepts/approvals)). If your system owns
      the decision, build [the approval-request responder](/api-guides/carrier-invoice-approval).
    * Record settlements with carrier payment line items
      ([submission guide, payments section](/api-guides/carrier-invoice-submission)).
  </Step>
</Steps>

## Path B — AR: create customer invoices and record payments

*You bill <Term t="customer">shippers</Term> and want Upwell to deliver <Term t="invoice">invoices</Term> and manage receivables.*

<Steps>
  <Step title="Prerequisites, in dependency order">
    1. API key.
    2. Customers — each with a `CUSTOMER_BILLING` address (a separate, typed address record; at
       most one per customer; it drives the invoice bill-to block). See
       [Working with addresses](/conventions/addresses).
    3. Shipments referencing those customers.
  </Step>

  <Step title="First successful call">
    `POST /api/rest/invoices` — include `balance` (equal to `totalAmount` for a new invoice),
    line items, and shipment links. Follow [Customer invoices](/api-guides/customer-invoices).
  </Step>

  <Step title="Know the two AR ownership questions">
    * **Who triggers delivery?** Upwell delivers invoices by email/EDI/portal per customer
      configuration, but the API action that *causes* delivery (writing `status: "SENT"`? an
      approval flag? a queue?) is not documented. **\[GAP]** Confirm the delivery contract for
      your tenant with Upwell before assuming a `PUT` sends anything.
    * **Who updates the invoice after a payment?** Applying payment line items via the API does
      **not** recalculate the invoice's `balance`/`status` — your integration updates the
      invoice afterward, as the [customer invoices guide](/api-guides/customer-invoices)
      instructs.
  </Step>

  <Step title="Production checklist">
    * Record remittances with [customer payments](/api-guides/customer-payments); enforce your
      own balance/status updates (above).
    * Subscribe to `update.invoice.status.SENT` and payment/remittance triggers
      ([event catalog](/api-guides/webhook-events)); note payload shapes for
      non-carrier-invoice events are not yet documented. **\[GAP]**
    * The AR feature pages (reminders, online payments) describe product capabilities — check
      [Can I…?](/developer-guide/can-i) for what has API surface today.
  </Step>
</Steps>

## Path C — Documents only: purchase orders & vendor invoices

*You have PDFs (POs, vendor invoices, combined stacks) and want Upwell to parse them.*

No foundation entities required — these upload standalone: presign → PUT bytes → poll the
document status (`GET /api/rest/documents/{id}`), then read the parsed record via the search
endpoints. Follow [Purchase orders & vendor invoices](/api-guides/purchase-orders-and-vendor-invoices).
Two things to plan around: parsing completion has **no webhook trigger** — polling is the only
mechanism (the [event catalog](/api-guides/webhook-events) has no purchase-order or
vendor-invoice triggers) — and re-using a `sourceSystem`/`sourceSystemId` pair at presign fails
fast with `DOCUMENT_ALREADY_UPLOADED` (unlike carrier invoices' async dedup).

## Path D — Events-only consumer

*Upwell is the system of action; you mirror its events.*

1. Host an HTTPS receiver; subscribe in the dashboard with a custom auth header
   ([Outbound webhooks](/api-guides/webhooks)).
2. Branch on the envelope's `trigger`, correlate on `resourceId`, and **refetch the resource via
   GET** rather than trusting payload shapes — they vary by trigger.
3. Reliability facts for your on-call runbook (full detail in the
   [webhooks guide](/api-guides/webhooks)):
   * Timeout 15 s per delivery; `5xx`, timeouts, and network failures retry with exponential
     backoff (1, 2, 4, … minutes); `retryAttempts: N` means N retries *beyond* the first
     attempt (default 3).
   * **A `4xx` from your receiver is recorded as delivered and is never retried.** If your auth
     middleware breaks, events are silently lost — alert on your own 4xx rate.
   * There is no delivery-inspection or replay surface; recover by polling the resource
     endpoints.
   * There is no payload signing (HMAC) — treat your configured header secret like a password.
4. Know what never fires: foundation entities (customers, carriers, shipments, addresses,
   companies) have no triggers — poll if you need to read them back
   ([event catalog](/api-guides/webhook-events)).

## Before you write retry code, read these two

<CardGroup cols={2}>
  <Card title="What happens if…?" icon="arrows-split-up-and-left" href="/developer-guide/what-happens-if">
    The consequence reference: retries, duplicates, deletes, pagination, webhooks misbehaving — what actually happens down each branch.
  </Card>

  <Card title="Can I…?" icon="circle-check" href="/developer-guide/can-i">
    The feasibility reference: supported, supported-with-caveats, not supported, or undocumented — with evidence for every row.
  </Card>
</CardGroup>