Purchase orders and vendor invoices via API

Purchase orders and vendor invoices are standalone supporting documents — inbound POs from your customers and generic (non-freight) vendor AP invoices. You upload a PDF through the same presigned-URL flow as other documents; Upwell parses it asynchronously and creates the structured record you can then list, search, and patch. This page covers the end-to-end workflow. For the always-current request and response schemas, see the API Reference entries under Purchase Orders and Vendor Invoices.

These are not freight carrier invoices (carrier_invoices) and not customer AR invoices (invoices). For those flows see Submitting carrier invoices via API and Managing customer invoices (AR).

Prerequisites

An API key on every request (Authorization: YOUR_API_KEY, no Bearer prefix). See Authentication.
A PDF of the purchase order or vendor invoice (standalone supporting-doc uploads are PDF-only, one document per upload).

The flow

Request a presigned upload URL

POST /api/rest/generate-upload-presigned-url with associationType of PURCHASE_ORDER or VENDOR_INVOICE. Omit associationId — the parsed record is created from the upload, not attached to an existing entity.

PUT the PDF bytes

Upload the raw file to uploadUrl. Content-Type must match the mimeType you declared (application/pdf).

Poll until the parsed record appears

GET /api/rest/documents/{documentId}/purchase-orders or .../vendor-invoices returns an empty list until parsing finishes (typically within a couple of minutes). Bound the poll — see Step 3.

Read, search, or update

Use the list / get / search / patch endpoints below once the record exists.

Step 1 — Request a presigned URL

Standalone supporting-doc ingestion uses a dedicated associationType and no associationId:

Document	`associationType`	`documentType`
Purchase order	`PURCHASE_ORDER`	`PURCHASE_ORDER`
Vendor invoice	`VENDOR_INVOICE`	`VENDOR_INVOICE`

Pass sourceSystem + sourceSystemId so retries are safe: re-requesting an already-uploaded document returns 400 DOCUMENT_ALREADY_UPLOADED; re-requesting one whose upload never completed returns a fresh uploadUrl for the same document.

curl -X POST https://api.upwell.com/api/rest/generate-upload-presigned-url \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "input": {
          "associationType": "PURCHASE_ORDER",
          "documentType": "PURCHASE_ORDER",
          "fileName": "po-88123.pdf",
          "mimeType": "application/pdf",
          "sourceSystem": "YOUR_TMS",
          "sourceSystemId": "PO-DOC-88123"
        }
      }'
# -> { "generateUploadPresignedUrl": {
#      "documentId": "doc_...", "uploadUrl": "https://..." } }

For a vendor invoice, swap both types inside input to VENDOR_INVOICE. Read uploadUrl and documentId from generateUploadPresignedUrl — not from the response root.

See Integration patterns for the presigned-upload header gotcha (pass an ArrayBuffer, not a typed Blob, from Node fetch).

Step 2 — Upload the PDF

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @po-88123.pdf

Uploaded bytes are verified server-side. Non-PDF content parks the document with status UPLOAD_CONTENT_REJECTED and is never parsed — check GET /api/rest/documents/{documentId}. Rejection is terminal for that sourceSystem + sourceSystemId; re-upload with a new sourceSystemId.

Step 3 — Poll for the parsed record

# Purchase orders created from this document
curl https://api.upwell.com/api/rest/documents/doc_abc123/purchase-orders \
  -H "Authorization: YOUR_API_KEY"

# Vendor invoices created from this document
curl https://api.upwell.com/api/rest/documents/doc_abc123/vendor-invoices \
  -H "Authorization: YOUR_API_KEY"

An empty list usually means parsing is still in progress — unless GET /api/rest/documents/{documentId} shows status: "UPLOAD_CONTENT_REJECTED" (invalid PDF; terminal for that sourceSystem + sourceSystemId).

Bound your poll. If the list is still empty after a few minutes and the document is not UPLOAD_CONTENT_REJECTED, stop and treat the upload as a failed parse. A valid PDF that is not recognized as a purchase order / vendor invoice can finish without creating a supporting record and without setting a rejection status — there is no separate mismatch flag on the document today. Re-upload with the correct document (or a new sourceSystemId) rather than polling forever.

Find by your source ids

If you stored sourceSystem + sourceSystemId at presign time, you can look up the parsed record without the document id:

curl -X POST https://api.upwell.com/api/rest/purchase-orders/search \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sourceSystem": "YOUR_TMS", "sourceSystemId": "PO-DOC-88123" }'

Use POST /api/rest/vendor-invoices/search for vendor invoices — same body shape.

Step 4 — List, get, and update

Action	Purchase orders	Vendor invoices
List recent	`GET /api/rest/purchase-orders`	`GET /api/rest/vendor-invoices`
Get one	`GET /api/rest/purchase-orders/{id}`	`GET /api/rest/vendor-invoices/{id}`
Update header	`PATCH /api/rest/purchase-orders/{id}`	`PATCH /api/rest/vendor-invoices/{id}`
Update line item	`PATCH /api/rest/purchase-order-line-items/{id}`	`PATCH /api/rest/vendor-invoice-line-items/{id}`

List endpoints accept an optional limit query parameter. Get-one responses include line items and party addresses; vendor invoices also include the matched purchase order when one exists.

Patch body shape

Updates use { "input": { ...fields to set... } } with the record’s camelCase field names. Amounts are integer cents. System-managed columns (ids, tenant/document linkage, party references, match state) are not updatable and are rejected.

curl -X PATCH https://api.upwell.com/api/rest/purchase-orders/po_abc123 \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "poNumber": "PO-88123-R1" } }'

Money is integer cents. $1,250.00 → 125000. See Integration patterns.

Integration patterns — presigned upload, integer cents, sourceSystem pairs
How documents flow through Upwell
API Reference: Purchase Orders, Vendor Invoices

​Purchase orders and vendor invoices via API

​Prerequisites

​The flow

​Step 1 — Request a presigned URL

​Step 2 — Upload the PDF

​Step 3 — Poll for the parsed record

​Find by your source ids

​Step 4 — List, get, and update

​Patch body shape

​Related

Purchase orders and vendor invoices via API

Prerequisites

The flow

Step 1 — Request a presigned URL

Step 2 — Upload the PDF

Step 3 — Poll for the parsed record

Find by your source ids

Step 4 — List, get, and update

Patch body shape

Related