Working with shipment documents

Documents — PODs, bills of lading, rate confirmations, and so on — attach to a shipment (the load), not only to a carrier invoice. This page covers listing, adding, and removing a shipment’s documents.

There are two document surfaces — pick the endpoint by what you’re keyed on:

By shipment (load): GET /api/rest/shipments/{shipmentId}/documents — this page.
By carrier invoice (AP): GET /api/rest/carrier_invoices/{id}/documents — see Knowing when a carrier invoice is processed.

List a shipment’s documents

GET /api/rest/shipments/{shipmentId}/documents returns the shipment’s documents, keyed by shipmentDocumentsByShipmentId:

curl https://api.upwell.com/api/rest/shipments/shi_abc123/documents \
  -H "Authorization: YOUR_API_KEY"
# -> { "shipmentDocumentsByShipmentId": [
#      { "id": "...", "documentId": "doc_...", "createdAt": "...", "updatedAt": "...",
#        "documents": [ { "id": "doc_...", "type": "PROOF_OF_DELIVERY",
#                         "sourceSystem": "...", "sourceSystemId": "...",
#                         "visibleToCarrier": true, "visibleToCustomer": false } ] } ] }

Field	Meaning
`id`	The shipment-document link ID — use this to delete the association.
`documentId`	The underlying document’s ID.
`documents`	Array of the underlying document record(s).
`documents[].type`	The document’s classification — one of your account’s available document types (e.g. `PROOF_OF_DELIVERY`; `POD` is that type’s display label, not a write value).
`documents[].visibleToCarrier` / `visibleToCustomer`	Sharing flags.
`documents[].sourceSystem` / `sourceSystemId`	Provenance from your system, when set.
`createdAt` / `updatedAt`	Timestamps.

Testing against staging? Use the staging base URL https://staging.api.upwell.com with your staging API key — the paths are identical, and keys are environment-specific. See Environments for how staging access is provisioned.

Add a document to a shipment

POST /api/rest/shipments/{shipmentId}/documents attaches a document from base64-encoded bytes:

curl -X POST https://api.upwell.com/api/rest/shipments/shi_abc123/documents \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "shipmentId": "shi_abc123",
        "input": {
          "base64": "JVBERi0xLjQ...",
          "mimeType": "application/pdf",
          "type": "PROOF_OF_DELIVERY",
          "filename": "pod.pdf",
          "visibleToCarrier": true
        }
      }'
# -> { "createShipmentDocument": { "id": "...", "documentId": "doc_..." } }

Required: base64, mimeType, and type (one of your available document types). Optional: filename, visibleToCarrier, visibleToCustomer, and a sourceSystem + sourceSystemId pair.

The base64 path is convenient for smaller files. For large documents, prefer the two-step presigned-URL upload — see Document conventions.

sourceSystem and sourceSystemId are all-or-nothing — provide both or neither. See Integration patterns.

Remove a document from a shipment

DELETE /api/rest/shipments/{shipmentId}/documents/{id} removes the document’s association with the shipment. Use the shipment-document id from the list response (not the underlying documentId):

curl -X DELETE https://api.upwell.com/api/rest/shipments/shi_abc123/documents/SHIPMENT_DOCUMENT_ID \
  -H "Authorization: YOUR_API_KEY"
# -> { "deleteFileAssociations": { "affectedRows": 1,
#      "returning": [ { "id": "...", "fileId": "...", "associationId": "..." } ] } }

For the complete request and response schemas, see the shipments/{shipmentId}/documents entries in the API Reference. To attach documents to a carrier invoice instead, see Submitting carrier invoices via API.

​Working with shipment documents

​List a shipment’s documents

​Add a document to a shipment

​Remove a document from a shipment

Working with shipment documents

List a shipment’s documents

Add a document to a shipment

Remove a document from a shipment