Vocabulary

The core integration enums — statuses, exceptions, approvals, address types, stop types, payment statuses, and document types. Values are generated from the API schema, not hand-maintained, so each list below is the complete set as of the release that published it. Handle unrecognized values defensively — a value added to the API since then will not appear here until this page is regenerated. Every value below carries a definition. Field-level enums not listed here (e.g. country and currency codes) are documented on their endpoints in the API reference.

Carrier invoice statuses

The status field on carrier invoices (AP). Lifecycle guidance: Knowing when a carrier invoice is processed.

Value	Meaning
`APPROVED`	Approved — cleared to pay (review lifecycle).
`AWAITING_BILL`	A shipment is matched but no bill is linked yet; auto-promotes to `RECEIVED` once one is. Also set if a linked bill is later cancelled or voided, freeing the invoice to re-match.
`AWAITING_CARRIER_RESPONSE`	Waiting on the carrier.
`AWAITING_INVOICE`	Created ahead of the invoice document; auto-promotes to `RECEIVED` when that document arrives and parses.
`CANCELLED`	Terminal. The invoice was nullified, either by request or because it was issued in error — it drops out of the actionable queues.
`CARRIER_EXCEPTION`	A carrier-side issue needs resolving.
`CARRIER_RESPONDED`	The carrier has responded.
`DISPUTED`	Disputed.
`EXCEPTION`	An audit exception needs resolving.
`PAID`	Fully paid.
`PART_PAID`	Partially paid.
`PROCESSING`	In-flight processing.
`RECEIVED`	Submitted / in review. Ingestion (matching + audit) usually runs while status stays here.
`REFUNDED`	Terminal. A previously paid invoice was reversed and the payment returned.
`REJECTED`	Rejected.
`UNDER_REVIEW`	In manual review.

Customer invoice statuses

The status field on customer invoices (AR). Lifecycle guidance: Managing customer invoices.

Value	Meaning
`APPROVED`	Invoice has been approved for sending.
`CANCELLED`	Invoice was cancelled.
`CREATED`	Invoice record exists but hasn’t been finalized.
`DELIVERED`	Invoice delivery has been confirmed.
`DISPUTED`	Customer has raised a dispute.
`DRAFT`	A pre-`CREATED` stage for invoices synced from a TMS before the TMS posts the bill. Excluded from portal delivery, manual send, and receivables — sending one returns `409` — until it promotes to `CREATED` (or to `CANCELLED` if the TMS voids it).
`OPEN`	Invoice is finalized and ready for delivery.
`OVERDUE`	Past due date with an outstanding balance.
`PAID`	Fully paid — balance is `0`.
`PART_PAID`	Partially paid — balance is between `0` and `totalAmount`.
`PORTAL_EXCEPTION`	The invoice hit an exception during portal delivery.
`PORTAL_RESOLVED`	A portal exception has been resolved.
`PROCESSING`	Invoice is being processed for delivery.
`REFUNDED`	A refund was issued.
`REJECTED`	Invoice was rejected.
`SEND_ERROR`	Invoice delivery failed.
`SENT`	Invoice has been delivered to the customer.
`VIEWED`	Customer has viewed the invoice (online portal).
`WRITE_OFF`	Written off as uncollectible.

Exception statuses

The lifecycle of an exception. OPEN and IN_PROGRESS are the two “still needs attention” states that hold an invoice back.

Value	Meaning
`CLOSED`	Closed; no further action needed.
`IN_PROGRESS`	Someone is actively working it.
`OPEN`	Raised but not yet addressed — needs attention.
`RESOLVED`	Worked and resolved.
`RULE_DISABLED`	Suppressed because the audit rule that generated it was turned off.

Approval request statuses

The status on carrier-invoice approval requests. Your integration resolves a request by PATCHing SUCCEEDED or FAILED.

Value	Meaning
`ABANDONED`	Upwell gave up waiting: the request was still unresolved 10 minutes after dispatch. The carrier invoice is not approved, and resolving the request afterwards will not approve it.
`FAILED`	Resolved rejected. The carrier invoice is left where it is — Upwell does not move it to a rejected status for you.
`INITIATED`	The request record has been created and validated; Upwell has not dispatched it to you yet. This is the state every request starts in.
`IN_PROGRESS`	Upwell has dispatched the request to your webhook endpoint and is waiting for you to resolve it. Dispatch also starts the 10-minute abandonment clock.
`RETRYING`	Reserved. No Upwell code path currently sets this; if you do encounter it, treat it like `IN_PROGRESS` — still in flight, not yet resolved.
`SUCCEEDED`	Resolved approved — moves the carrier invoice to `APPROVED`.

Address types

type is required on every address and several product surfaces query it exactly — see Working with addresses for which types are load-bearing.

Value	Meaning
`ADDRESS_BOOK`	Inert — nothing reads it. Not a safe generic default; always use the specific role type.
`CARRIER`	A carrier’s primary address (descriptive).
`CARRIER_BILLING`	Where a carrier wants payment sent (descriptive; remit-to logic is driven by factoring documents).
`COMPANY_ADDRESS`	Load-bearing. The only type the company pages render.
`CONTACT`	An address on a contact record (descriptive).
`CUSTOMER_BILLING`	Load-bearing. A customer’s billing address — the invoice bill-to block and delivery routing read this exact value. At most one per customer.
`DELIVERY_RECEIPT`	Written by Upwell’s document-parsing pipelines — read-only for integrations.
`LUMPER_RECEIPT`	Written by Upwell’s document-parsing pipelines — read-only for integrations.
`SHIPMENT_CONSIGNEE`	A shipment’s destination slot.
`SHIPMENT_PICKUP`	A shipment’s origin slot.
`STOP`	An address used by a route stop (descriptive).
`SUPPORTING_DOC_PARTY`	Written by Upwell’s document-parsing pipelines — you’ll see it on reads; don’t create it.

Stop types

The constrained vocabulary for a stop’s type field. A stop carries two type fields — the enum-constrained type below and a separate free-text stopType — and different surfaces read each, so populate both where you can. The legacy POST /api/rest/shipments endpoint can only set stopType; see Syncing foundation entities. Today only PICKUP and DELIVERY are branched on in logic; the rest are recorded and passed through (for example to outbound EDI) but nothing keys off them.

Value	Meaning
`CONSOLIDATION`	A stop to combine multiple smaller shipments into a larger load.
`CROSS_DOCK`	A facility where goods move directly from inbound to outbound trailer with minimal storage.
`CUSTOMS`	A checkpoint or border crossing for regulatory inspection.
`DECONSOLIDATION`	A stop to break down a larger load into multiple smaller shipments.
`DELIVERY`	The final or primary destination where freight is delivered. Load-bearing — a `DELIVERY` stop that has an address is what lets proof-of-delivery exceptions evaluate per stop; without one, evaluation falls back to the shipment’s consignee address.
`DROP_OFF`	A location where a partial shipment is unloaded (for example, on a multi-stop route).
`FUEL_STOP`	A planned stop for refueling or vehicle service.
`LAYOVER`	A stop for driver rest or waiting (for example, required by hours-of-service rules).
`ORIGIN`	The initial starting point for the shipment.
`OTHER`	Catch-all for unclassified or special-case stops — integrations map unrecognized external codes here.
`PICKUP`	A location where freight is physically picked up. Load-bearing — the carrier-invoice shipments view treats the first `PICKUP` stop as the shipment origin.
`RETURN`	Returning freight to an origin or warehouse (for example, refused shipments or product returns).
`STORAGE`	A temporary storage or holding location for freight.
`TERMINAL`	A main hub for consolidation, deconsolidation, or staging.
`TRANSFER`	A location where freight changes carriers, modes, or vehicles.

Payment statuses

The status field on payment records. Two things to know before you branch on it. The field is nullable, and a null status means a legacy or externally-recorded payment — Upwell treats those as SUCCEEDED, so read it as status ?? SUCCEEDED rather than assuming a value is present. And only PENDING is not yet money: FAILED and PAYMENT_REVERSED both mean funds did not stay with you, but they differ in whether the money ever landed at all.

Value	Meaning
`DISPUTED`	The payer opened a chargeback against a settled card payment. Applied amounts are deliberately left in place because the dispute may be won, but funds may be withheld meanwhile.
`FAILED`	Declined or errored before capture — no money ever moved and the invoice balance is unchanged.
`PAYMENT_REVERSED`	The bank involuntarily reversed an already-settled payment (an ACH return or NSF). The invoice reopens with its balance restored — the payer still owes you. Distinct from `REFUNDED`, which is deliberate.
`PENDING`	Submitted to the payment processor and not yet confirmed. No funds have landed.
`REFUNDED`	The payment was fully refunded to the payer. A partial refund does not land here — it adjusts the applied amounts and leaves the payment `SUCCEEDED`.
`SUCCEEDED`	The processor confirmed the payment and captured funds, recorded at the amount the bank actually received.

Document types

The canonical documentType codes (send the code, not a display label — PROOF_OF_DELIVERY, not “POD”). The full generated list follows the table; the table covers the types integrations set most, per the guides.

Type	Meaning
`BILL_OF_LADING`	Bill of lading.
`CARRIER_INVOICE`	The carrier’s invoice document — parsing it populates blank header fields and line items on the carrier invoice.
`CARRIER_RATE_CONFIRMATION`	The rate you agreed to pay the carrier — carrier cost; used by the carrier-invoice audit. Never type a customer rate con as this (or vice versa) — see Document conventions.
`CUSTOMER_INVOICE`	The customer-invoice PDF (AR).
`CUSTOMER_RATE_CONFIRMATION`	The rate your customer agreed to pay you — revenue; used to validate customer invoices.
`LUMPER_RECEIPT`	A lumper service receipt.
`NOTICE_OF_ASSIGNMENT`	A factoring notice — parsing it populates a carrier invoice’s remit-to / factor.
`PROOF_OF_DELIVERY`	Proof of delivery (“POD” is the display label).
`PURCHASE_ORDER`	A standalone purchase order — uploaded via the presigned flow and parsed into a purchase-order record.
`VENDOR_INVOICE`	A standalone non-freight vendor invoice — parsed into a vendor-invoice record.

All 133 values:

ACCESSORIAL_RECEIPT  ADVANCE_REQUEST  AGENT_INVOICE  ARRIVAL_NOTICE
ASBESTOS_DECLARATION  AUSFTA  AUTHORITY  AUTH_RELEASE
B3_CANADIAN_ENTRY  BALANCE_DUE  BILL_OF_LADING  CARRIER_ACH_SETUP_FORM
CARRIER_BOOKING_REQUEST  CARRIER_INSURANCE_CERTIFICATE  CARRIER_INVOICE  CARRIER_INVOICE_SUMMARY
CARRIER_INVOICE_WITH_SUPPORTING_DOCUMENTATION  CARRIER_RATE_CONFIRMATION  CARRIER_W9  CARTAGE_ADVICE_WITH_RECEIPT
CERTIFICATE_OF_ORIGIN  CFDI  CLAIM  CLAIM_NOTICE
COMCHECK  COMMERCIAL_INVOICE  CONSIGNMENT_SECURITY_DECLARATION  CONTRACT
CORRECTION_NOTICE  COVER_SHEET  CREDIT_APPLICATION  CUSTOMER_DOCUMENTS_OTHER
CUSTOMER_INVOICE  CUSTOMER_INVOICE_WITH_SUPPORTING_DOCUMENTATION  CUSTOMER_RATE_CONFIRMATION  CUSTOMER_RELEASE
CUSTOMS_AUTHORITY  CUSTOMS_CLEARANCE_REQUEST  CUSTOMS_DOCUMENT  CUSTOMS_ENTRY_SUMMARY
CUSTOMS_POWER_OF_ATTORNEY  DANGEROUS_GOODS_DECLARATION  DELIVERY_ORDER  DELIVERY_PHOTO
DELIVERY_RECEIPT  DEMURRAGE_RECEIPT  DETENTION_APPROVAL  DOCUMENT_BUNDLE
DOCUMENT_PACKET  DRIVER_FORM  ELECTRONIC_INTERCHANGE_RECEIPT  EMAIL_APPROVAL
EMAIL_SIGNATURE_IMAGE  ESCORT_RECEIPT  EXIT_PASS  EXPORT_AUTHORITY
EXPORT_DECLARATION  FACTOR_INVOICE  FERRY_RECEIPT  FINE
FORM_1113_PUBLIC_VOUCHER  FREETIME_NOTIFICATION  FREIGHT_LABEL  FUEL_RECEIPT
FUMIGATION_CERTIFICATE  FUNDING_REQUEST_FORM  GATE_PASS  GOVERNMENT_BOL
HIDDEN_BOL  HOUSE_AIRWAY_BILL  HOUSE_BOL  HOUSE_OCEAN_BOL
INSPECTION_CERTIFICATE  INSTRUCTION_PAGE  INTERMODAL_IN_TRANSIT_NOTICE  INTERNAL_DOCUMENTS_OTHER
INTERNAL_PROOF_OF_DELIVERY  INTERNATIONAL_BOL  INVOICE_STATEMENT  ISF_FILING_INSTRUCTION
LAYOVER_APPROVAL  LETTER_OF_ASSIGNMENT  LETTER_OF_CREDIT  LUMPER_APPROVAL
LUMPER_RECEIPT  MANIFEST  MASTER_AIRWAY_BILL  MASTER_BOL
MASTER_OCEAN_BOL  MOTOR_VEHICLE_CERT  MSDS  NAFTA_CERT
NMFC_W_I_CERT  NOTICE_OF_ASSIGNMENT  NOTICE_OF_RELEASE  OTHER
PACKING_DECLARATION  PACKING_SLIP  PALLET_RECEIPT  PERMIT_TO_TRANSFER
PER_DIEM_RECEIPT  PICKUP_NUMBER  PRE_ALERT  PROFORMA_INVOICE
PROOF_OF_DELIVERY  PURCHASE_ORDER  REMITTANCE  RUN_TICKET
SANITARY_CERTIFICATE  SCALE_TICKET  SHIPPERS_LETTER  SHIPPER_SECURITY_DECLARATION
SOLAS_FORM  SPOT_QUOTE_APPROVAL  STEAMING_RECEIPT  SUPPORTING_DOCUMENTATION
TELEX_RELEASE  TOLL_RECEIPT  TONU_APPROVAL  TRACKING_STATUS
TRAILER_INTERCHANGE_REPORT  TRUCK_BOL  UNKNOWN  US_CUSTOMS_DOC
VENDOR_INVOICE  VETERINARY_CERTIFICATE  VGM_CONTAINER_INFO  VOIDED_CHECK
WASH_RECEIPT  WAYBILL  WEIGHT_MEASUREMENT_REPORT  WEIGHT_TICKET
WEIGHT_UNLOADED

​Vocabulary

​Carrier invoice statuses

​Customer invoice statuses

​Exception statuses

​Approval request statuses

​Address types

​Stop types

​Payment statuses

​Document types