Define a canonical status enum for your application (e.g. PRE_TRANSIT, IN_TRANSIT, OUT_FOR_DELIVERY, DELIVERED, EXCEPTION, RETURNED)
Build a mapping table from each carrier's raw status codes and descriptions to your canonical enum; consult each carrier's tracking API documentation for exhaustive status lists
Ingest tracking events from carrier APIs or aggregators (EasyPost, Shippo) and apply the mapping at ingestion time, storing both the raw carrier status and the normalized status
Flag events that do not match any mapping rule and route them to a review queue rather than silently dropping them
Expose a single tracking endpoint in your system that returns the normalized status plus the latest carrier-provided description and timestamp
Revisit and update the mapping table when carriers publish status code changes in their release notes
Known gotchas
Carrier status strings are not stable; carriers add, rename, or retire status codes without advance notice, so a mapping that covers 100% of codes today may silently drop events after a carrier update
The same carrier status code can mean different things in different service contexts (e.g. 'In Transit' for ground vs. 'In Transit' after a customs hold); use both the status code and event description for accurate mapping
USPS uses event codes rather than status strings; mapping only on the human-readable description rather than the EventCode will break when the description is localized or reworded
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