Skip to main content

​
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.
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 and we’ll answer it directly (and then document it).

​
Orient yourself first (10 minutes)

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

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

Integration patterns

The cross-cutting mechanics: integer-cents money, the input wrapper, sourceSystem/sourceSystemId upserts, per-resource retry semantics, addresses, deletes.
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.
  2. Money is integer cents. $2,847.50 → 284750. Floats are rejected at runtime (Money & 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? before writing retry code.

​
Which developer are you?

Read the two orientation pages, then Syncing foundation entities to size the sync engine, and the webhook event catalog 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 (or your Upwell contact) to coordinate a multi-customer rollout. See 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.
  • Operational guarantees. No SLA or status page is published, and the 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.
Your path is almost always: get an API key → push foundation data → pick the AP or AR flow below. Follow the developer 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).
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, then the event catalog — and read the reliability notes in Path D below, especially the 4xx behavior.
Go straight to Can I…? — a feasibility table for the questions integrators actually ask, each row with its evidence or an explicit gap.

​
Path A — AP: submit and track carrier invoices

You have (your own, or your carriers’) and want Upwell to audit, approve, and track them.
1

Prerequisites, in dependency order

  1. API key (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.
  3. — 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).
2

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 literally — including its warning that only the presigned upload path runs AI classification.
3

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

Production checklist

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

You bill and want Upwell to deliver and manage receivables.
1

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.
  3. Shipments referencing those customers.
2

First successful call

POST /api/rest/invoices — include balance (equal to totalAmount for a new invoice), line items, and shipment links. Follow Customer invoices.
3

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 instructs.
4

Production checklist

  • Record remittances with customer payments; enforce your own balance/status updates (above).
  • Subscribe to update.invoice.status.SENT and payment/remittance triggers (event catalog); 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…? for what has API surface today.

​
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. Two things to plan around: parsing completion has no webhook trigger — polling is the only mechanism (the event catalog 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).
  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):
    • 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).

​
Before you write retry code, read these two

What happens if…?

The consequence reference: retries, duplicates, deletes, pagination, webhooks misbehaving — what actually happens down each branch.

Can I…?

The feasibility reference: supported, supported-with-caveats, not supported, or undocumented — with evidence for every row.