Knowing when a carrier invoice is processed

After you submit a carrier invoice, Upwell works on it asynchronously. This page explains how to learn when that work is done.

There’s no single “processed” flag. You read the existing fields on the invoice — its status, its exceptions, and the matched shipmentId — plus the type on each attached document. You can read them by polling the GET endpoints or by receiving webhooks. Most production integrations use webhooks for timeliness and polling as a reconciliation backstop.

Two phases of processing

It helps to separate two things:

Ingestion (automatic, seconds after create). Upwell stamps provenance (source_system = "API"), matches the invoice to a shipment/carrier/bill from your references, and runs the exception audit. The status usually stays RECEIVED through this phase — ingestion populates shipmentId/billId/carrierId and updates exceptions, it doesn’t move the status.
Review & approval (later; may involve your rules or a human). The invoice moves toward APPROVED or an exception state. This is where status changes.

So “is it done?” has two answers depending on what you’re waiting for. Both are observable from the same endpoints.

The signals

Signal	Where	Meaning
`shipmentId` populated	`GET /carrier_invoices/{id}`	Ingestion matched the invoice to a shipment.
`updatedAt` > `createdAt`	`GET /carrier_invoices/{id}`	Ingestion has run (Upwell touched the row after you created it).
`exceptions` (string)	`GET /carrier_invoices/{id}`	Comma-joined open audit findings, e.g. `"INVOICE AMOUNT MISMATCH"`. Empty = clean.
`status`	`GET /carrier_invoices/{id}`	The review/approval lifecycle (see table below).
document `type`	`GET /carrier_invoices/{id}/documents`	A document is parsed once `type` is no longer `"UNKNOWN"`.

Status values

The generated Vocabulary page lists every enum value the API can produce, including the ones not defined below.

Phase	Statuses	Meaning
In-flight	`RECEIVED`, `PROCESSING`, `UNDER_REVIEW`, `AWAITING_INVOICE`, `AWAITING_CARRIER_RESPONSE`, `CARRIER_RESPONDED`	Submitted / under review.
Done — clear	`APPROVED`, `PART_PAID`, `PAID`	Approved and progressing to / through payment.
Needs attention	`EXCEPTION`, `CARRIER_EXCEPTION`, `DISPUTED`, `REJECTED`	A carrier/audit issue needs resolving.

exceptions is a comma-joined string, not an array. Treat a non-empty string as “needs attention” even while status is still RECEIVED. And don’t judge exceptions until ingestion has run — a brand-new row always lists “no carrier / no matching shipment” findings that disappear once matching completes.

When a linked bill moves the status

Once a carrier invoice is linked to a bill, the bill’s status can move the invoice. The mapping depends on the bill’s source_system. Strings are exact, including case. Fully paid and partially paid bill statuses apply for every source:

Bill `status`	Carrier invoice `status`
`PAID`, `Fully Paid`, `Paid`	`PAID`
`Partial Paid`, `Paid Partial`	`PART_PAID`

These bill statuses are removed for every source, and the carrier invoice goes to AWAITING_BILL: DELETED, VOID, Canceled. Approval that is not itself a payment is per source. A bill synced by one of Upwell’s TMS integrations moves the invoice to APPROVED only on that TMS’s own approval statuses. For example:

Bill `source_system`	Bill `status` values that approve
`TAI`	`Unpaid` (`Fully Paid` and `Partial Paid` are the payment rows above)
`REVENOVA`	`APPROVED`
`Turvo`, `TURVO_TMS`	`Approved` (`Paid` is the paid row above)
`THREE_GTMS`	`Billed` (`Paid` and `Paid Partial` are the payment rows above)
`MCLEOD`, `mcleod`	`Transferred to Settlement`, `Unpaid` (settled in McLeod but not paid, for example after a voided payment)
`TRANSPORT_PRO`, `transport-pro`	`APPROVED`

TRANSPORT_PRO and transport-pro use the literal APPROVED on purpose. That is the same text Revenova stores; it is listed for Transport Pro rather than borrowed from Revenova. A status that only another TMS uses for approval does not approve: a Turvo bill whose status is APPROVED, or a Revenova bill whose status is Approved, leaves the invoice where it is (an invoice in AWAITING_BILL moves to RECEIVED, because it now has a bill). Bills you submit through the API (source_system = "API") use the combined list, because partner-authored bills keep bill status as the source of truth. So does a bill with no source_system, or one whose source_system has no list of its own. The combined list approves on AGING, SELECTED, Unpaid, APPROVED, Approved, Billed, and Transferred to Settlement; the paid and partially paid rows above apply as usual. A carrier invoice in AWAITING_INVOICE does not move because of the bill. The invoice document has to arrive first.

Approach 1 — Polling

Read the invoice and its documents on an interval. Wait for ingestion (the row’s updatedAt advances past createdAt), then read the outcome.

curl https://api.upwell.com/api/rest/carrier_invoices/cari_a1b2c3d4e5 \
  -H "Authorization: YOUR_API_KEY"
# -> { "carrierInvoice": { "id": "cari_a1b2c3d4e5", "status": "RECEIVED",
#       "shipmentId": "shi_...", "billId": "bil_...", "carrierId": "car_...",
#       "exceptions": "INVOICE AMOUNT MISMATCH", "createdAt": "...", "updatedAt": "...", ... } }

curl https://api.upwell.com/api/rest/carrier_invoices/cari_a1b2c3d4e5/documents \
  -H "Authorization: YOUR_API_KEY"
# -> { "carrierInvoiceDocumentsByCarrierInvoiceId":
#      [ { "id": "...", "documentId": "doc_...", "type": "CARRIER_INVOICE", "url": "https://...", ... } ] }

A minimal poller with backoff:

async function waitForIngestion(id, { timeoutMs = 60_000 } = {}) {
  let delay = 1_500;
  const deadline = Date.now() + timeoutMs;

  while (true) {
    const { carrierInvoice: inv } =
      await get(`/api/rest/carrier_invoices/${id}`);
    const { carrierInvoiceDocumentsByCarrierInvoiceId: docs = [] } =
      await get(`/api/rest/carrier_invoices/${id}/documents`);

    const ingested = inv.updatedAt !== inv.createdAt;   // Upwell has processed it
    const hasExceptions = !!(inv.exceptions || '').trim();
    const unclassified = docs.filter((d) => !d.type || d.type === 'UNKNOWN');

    if (ingested) {
      if (hasExceptions) return { outcome: 'NEEDS_ATTENTION', inv, docs };
      if (unclassified.length === 0) return { outcome: 'PROCESSED', inv, docs };
    }
    if (Date.now() + delay >= deadline)
      // Give up gracefully. A doc still UNKNOWN here is in manual review, not "failed".
      return { outcome: 'TIMEOUT', inv, docs, unclassified };

    await new Promise((r) => setTimeout(r, delay));
    delay = Math.min(delay * 2, 12_000); // exponential backoff
  }
}

Start around a 1–2 s interval and back off exponentially. Ingestion usually settles within seconds; document classification can take longer for large multi-page PDFs.

The documents endpoint exposes the document’s type, not its internal classification status. A document still UNKNOWN past your timeout is ambiguous between “still classifying” and “couldn’t be classified” — treat it as needs manual review rather than a hard failure, and don’t block your pipeline on it.

Approach 2 — Webhooks

Subscribe once and let Upwell push the changes to you. Configure subscriptions in the Upwell dashboard (see Outbound webhooks for the model, payload shape, and auth).

Trigger	Fires when
`create.carrier_invoice`	The invoice is created.
`update.carrier_invoice`	A change that is neither a tracked status transition nor a named sub-event — fires when ingestion enriches the row.
`create.carrier_invoice.shipment_updated` / `update.carrier_invoice.shipment_updated`	Creation with a shipment_id column, or a change to its value. Check the shipment ID before treating it as a match.
`update.carrier_invoice.status.APPROVED`	Read the invoice at dispatch from `payload.carrierInvoice`. A first payment can also record approval. When an outbound approval request completes, its follow-through status write suppresses this notification. Also not sent when Upwell records an approval Turvo already has.
`update.carrier_invoice.status.EXCEPTION`	The invoice entered `EXCEPTION`. Compare `payload.old` with `payload.new`.
`create.carrier_document` / `update.carrier_document`	A document was attached or (re)classified. Support-enabled only — not self-service in the dashboard; contact support.

The webhook event catalog is the source of truth for trigger strings and dispatch rules (each change fires at most one trigger — the most specific that applies).

The only per-status webhooks are APPROVED and EXCEPTION — and those reflect the review lifecycle, not ingestion. To know that ingestion completed (matched + audited), listen to update.carrier_invoice / update.carrier_invoice.shipment_updated, or poll. Other status transitions (UNDER_REVIEW, PAID, …) don’t each get their own trigger.

// Express-style receiver — see /api-guides/webhooks for auth + the full envelope.
app.post('/webhooks/upwell', (req, res) => {
  const event = req.body; // { trigger, resourceId, payload, ... }
  switch (event.trigger) {
    case 'update.carrier_invoice.shipment_updated':
      if (event.payload.new?.shipment_id || event.payload.carrierInvoice?.shipment)
        onMatched(event.resourceId, event.payload);
      break;
    case 'update.carrier_invoice.status.APPROVED':
      onApproved(event.resourceId, event.payload.carrierInvoice);
      break;
    case 'update.carrier_invoice.status.EXCEPTION':
      onException(event.resourceId, event.payload.new, event.payload.old);
      break;
  }
  res.json({ ok: true });
});

Which should I use?

Webhooks

Best when you can host an HTTPS endpoint. Near-real-time, no polling load.

Polling

Best when you can’t receive inbound requests, or as a backstop. Read GET /carrier_invoices/{id} (+ /documents) with backoff.

Webhook delivery retries on 5xx and can be delayed under load. A robust integration uses webhooks for timeliness and reconciles with a periodic poll so a missed delivery never leaves an invoice stuck in your system. Both approaches are shown above, and Outbound webhooks covers the delivery and retry behavior in full.

Foundation Data

Accounts Payable

Accounts Receivable

Documents

Webhooks

Using the App

Knowing when a carrier invoice is processed

Knowing when a carrier invoice is processed

Two phases of processing

The signals

Status values

When a linked bill moves the status

Approach 1 — Polling

Approach 2 — Webhooks

Which should I use?

Webhooks

Polling

Foundation Data

Accounts Payable

Accounts Receivable

Documents

Webhooks

Using the App

​Knowing when a carrier invoice is processed

​Two phases of processing

​The signals

​Status values

​When a linked bill moves the status

​Approach 1 — Polling

​Approach 2 — Webhooks

​Which should I use?

Webhooks

Polling

Knowing when a carrier invoice is processed

Two phases of processing

The signals

Status values

When a linked bill moves the status

Approach 1 — Polling

Approach 2 — Webhooks

Which should I use?