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.

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`	The invoice was matched/linked to a shipment.
`update.carrier_invoice.status.APPROVED`	The invoice reached `APPROVED` (review lifecycle).
`update.carrier_invoice.status.EXCEPTION`	The invoice hit an exception status (review lifecycle).
`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 exactly 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':
      onMatched(event.resourceId, event.payload);
      break;
    case 'update.carrier_invoice.status.APPROVED':
      onApproved(event.resourceId, event.payload);
      break;
    case 'update.carrier_invoice.status.EXCEPTION':
      onException(event.resourceId, event.payload);
      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.

​Knowing when a carrier invoice is processed

​Two phases of processing

​The signals

​Status values

​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

Approach 1 — Polling

Approach 2 — Webhooks

Which should I use?