Obtain a UPS OAuth 2.0 access token using client credentials.
GET the UPS Tracking REST API endpoint (verify current path and query parameter structure in current UPS docs) supplying the tracking number as a path parameter or query parameter; include 'locale' and 'returnSignature' query params if needed.
Parse 'trackResponse.shipment' array; each shipment contains 'package' array with 'trackingNumber', 'deliveryDate', 'activity' (event history), and 'status' with 'type', 'description', and 'code'.
Map 'status.type' values (e.g., 'D' for delivered, 'I' for in transit; verify current code list in UPS docs) to your internal delivery state.
Iterate 'activity' array for granular scan events; each activity has 'date', 'time', 'location', and 'status' sub-object describing the event.
For high-volume proactive tracking, consider using the UPS Track Alert API (webhook-based push) instead of polling; see the separate task for Track Alert webhook subscription.
Known gotchas
UPS Tracking REST API may require the 'transId' and 'transactionSrc' headers for audit logging; check current docs for required request headers.
Tracking data for UPS shipments may not appear until the package receives its first scan; newly created labels will return minimal data until carrier induction.
UPS tracking responses can include multiple packages under one shipment ID for multi-piece shipments; iterate all 'package' elements rather than assuming a single package.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp