Obtain an OAuth 2.0 client-credentials token from the UPS auth endpoint using your client_id and client_secret before calling any Claims API endpoint.
Determine claim type: for loss/non-delivery, the filing window is nine months from the shipment date; for damage, file within 60 days of the delivery date — missing either window results in automatic rejection.
Submit a POST to the UPS Claims API with the tracking number, claim type, declared value, and a description of the damage or loss; attach supporting documentation (photos, packing slips) as base64-encoded content.
Poll the returned claim number via GET on the Claims API or monitor the UPS Claims Dashboard to track status transitions (Submitted → In Review → Approved/Denied).
If additional documentation is requested, upload it within the timeframe specified in the status response to avoid claim closure.
Reconcile approved payment against the declared shipment value; UPS pays the lesser of declared value or repair/replacement cost.
Known gotchas
The damage claim window (approximately 60 days from delivery) is significantly shorter than the loss window (nine months from shipment date) — conflating the two is a common cause of rejected claims.
As of late 2025 UPS requires all claim submissions through its electronic system; paper forms are no longer accepted.
The Claims API is a separate product from the standard Shipping API and requires its own API key scope — a shipping-only credential will return authorization errors.
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