Can I…?
Feasibility before code. ✅ Supported (documented and real) · ⚠️ Supported with caveats (read the note) · ❌ Not supported (today, as documented) · ❓ Undocumented (the API surface exists in the OpenAPI spec but no guide covers it — confirm with Upwell before relying on it). [GAP] marks questions the docs cannot answer yet.Accounts payable
| Can I… | Notes | |
|---|---|---|
| submit carrier invoices via API? | ✅ | Submission guide |
| attach documents and get them AI-classified? | ✅ | Presigned flow only — base64 uploads are filed, never classified (Integration patterns) |
| know when an invoice is processed? | ✅ | Poll signals + webhooks (status guide) |
| see every status the lifecycle can produce? | ⚠️ | The spec’s enum has 16 values; 13 are defined in prose — AWAITING_BILL, CANCELLED, REFUNDED [GAP] |
| own approve/reject in my system? | ✅ | Approval requests — PATCH SUCCEEDED/FAILED |
| approve an invoice programmatically on the Upwell side? | ❓ | POST /carrier_invoices/{id}/approve (+overrideExceptions) exists in the spec; no guide covers it |
| list only pending approval requests? | ⚠️ | Documented params are limit/offset; a where filter is pending transport verification — see filtering |
| read the catalog of exception types/tokens? | ❌ | No catalog exists; the exceptions string’s token format is inconsistent across pages [GAP] |
| work exceptions (list/resolve) via API? | ❌ | No exceptions resource; lifecycle is UI-documented only (Exceptions) |
| record carrier payments? | ✅ | Payment line items + bulk (submission guide) |
| read, correct, or delete carrier payments? | ❓ | GET/PUT/DELETE exist in the spec; guides document POST only |
| use bill payments (settlement objects)? | ❓ | Full bill-payments endpoint family in spec; zero prose |
| manage bill line items? | ❓ | Endpoints + nested create exist in spec; the bills guide never mentions line items |
| pay lumpers/factors (non-carrier payables)? | ✅ | Vendors + vendorId on bills (syncing guide) |
| upload & parse POs and vendor invoices? | ✅ | PO & vendor invoices guide |
| get an event when a PO/vendor invoice finishes parsing? | ❌ | No trigger exists in the catalog; poll GET /documents/{id} |
| retract/delete a submitted carrier invoice? | ❓ | DELETE /carrier_invoices/{id} in spec; no guide, no semantics documented |
| configure auto-approval via API? | ❌ | Dashboard settings only (Approvals); cadence unpublished [GAP] |
Accounts receivable
| Can I… | Notes | |
|---|---|---|
| create invoices with line items in one call? | ✅ | Nested invoiceLineItems (guide) |
| link an invoice to shipments? | ✅ | Nested invoiceShipments on create (now in the spec) or POST /invoice_shipments (guide) |
| make Upwell deliver the invoice (email/EDI/portal)? | ⚠️ | The product does; the API action that triggers delivery is undocumented — confirm per tenant [GAP] |
| record customer payments/remittances? | ✅ | Customer payments |
| have payments auto-update invoice balance/status? | ❌ | Your integration updates the invoice (guide Tip) |
| update or unapply a payment line item? | ❓ | PUT/DELETE exist in spec; guide names GET/POST only |
| get events for payments recorded inside Upwell? | ⚠️ | Triggers exist (catalog); payload shapes undocumented [GAP] |
| drive reminders/dunning via API? | ❌ | No reminders API exists — email reminders are configured in the dashboard (Payment Reminders) |
| manage payment plans / disputes / bank feeds via API? | ❌ | No API surface; banking-integration ingestion is Upwell-operated (Remittances) |
| integrate the customer payment portal? | ❓ | Payments land as ordinary customer_payments (Online Payments); portalSlug exists on invoice reads; no portal API is documented |
| track whether a customer opened an invoice? | ❓ | VIEWED exists in the status enum; no page explains who sets it or when |
| send statements / list bills? | ⚠️ | Statements are a product feature (Receivables); no API surface documented |
Foundation data & sync
| Can I… | Notes | |
|---|---|---|
| push customers, carriers, shipments, companies, bills? | ✅ | Syncing foundation entities |
| bulk-load for the initial sync? | ⚠️ | bulk-customers/carriers/bills exist; no bulk-shipments; batch failure semantics differ per endpoint |
| upsert everything by my own IDs? | ⚠️ | Works everywhere except addresses (no external key — store addr_ ids); POST duplicate semantics differ per resource |
| get called back when foundation data changes in Upwell? | ❌ | By design — no foundation-entity triggers (catalog) |
| search/filter server-side? | ⚠️ | POST /search on 12 resources; addresses/companies have none; GET ?where= pending verification (details) |
| page safely through big collections? | ✅ | limit/offset; default limit is 10 — always pass it explicitly (API conventions) |
| model multi-stop routes? | ⚠️ | stops nested + standalone CRUD; populate free-text stopType (it’s what’s read), draw values from the type enum |
| model bill-to hierarchies? | ✅ | billToCustomerId (syncing guide) |
| merge duplicate customers? | ❌ | Internal operation; treat mergedIntoCustomerId as read-only (syncing guide) |
Events & platform
| Can I… | Notes | |
|---|---|---|
| subscribe to carrier-invoice lifecycle events? | ⚠️ | Per-status triggers only for APPROVED/EXCEPTION; no PAID/UNDER_REVIEW triggers (status guide) |
| subscribe to carrier-document / invoice-APPROVED events? | ⚠️ | Exist but not self-service — marked † in the catalog; contact support |
| manage webhook subscriptions via API? | ❌ | Dashboard only (webhooks guide) |
| verify deliveries cryptographically (HMAC)? | ❌ | Static header/Basic auth only — no signing or replay protection (webhooks guide) |
| inspect or replay past deliveries? | ❌ | No surface exists; recover by polling (webhooks guide, Reliability) |
| trust that 4xx responses will be retried? | ❌ | They are not — and they’re recorded as delivered. Alert on your own 4xx rate (webhooks guide) |
| test against a sandbox? | ⚠️ | staging.api.upwell.com exists; access is provisioned by Upwell, and keys are environment-specific (Environments) |
| plan around published rate limits? | ✅ | None exist today — no 429/X-RateLimit-* (Error handling) |
| serve many Upwell tenants with one credential? | ❌ | One API key = one organization; no partner credential (Key scope) |
| rotate/revoke an API key? | ✅ | Create → switch → revoke, in the dashboard; no key-management API (Authentication) |
| generate a client from the OpenAPI spec? | ✅ | The spec declares auth, required fields, real enums, nested inserts, and 400/401 responses; one caveat — where/orderBy filters pending verification (details) |
| follow API changes over time? | ⚠️ | The changelog is the channel; entries are docs-only so far, and no deprecation policy is published [GAP] |
Rows marked ❓ are opportunities as much as risks: the surface exists and is tenant-scoped like
everything else, but it is undocumented and therefore unwarranted — get written confirmation
from Upwell before building on one. Full evidence trail for every row lives in the review
bundle (
doc/HISTORY/2026-08-external-docs-dev-review/feasibility-matrix.md in the repo).