status-ontology · v3
TrackJet Status Ontology
Eight canonical states every carrier wording maps into — the same taxonomy the website timeline, REST/GraphQL API, webhooks and MCP tools emit. Machine-readable: status-ontology.json.
| State | Meaning | Example carrier wordings |
|---|---|---|
pending |
Shipment known, no movement recorded yet. | Label created · Auftragsdaten übermittelt · Pre-advice |
in_transit |
Moving between facilities. | Processed at parcel center · Departed hub · In Zustellbasis angekommen |
out_for_delivery |
On the final delivery vehicle. | Out for delivery · In Zustellung · With delivery courier |
delivered |
Handed over at destination. | Delivered · Zugestellt · Entregado |
exception |
Something blocks normal progress. | Held by customs · Address insufficient · Damaged |
returned |
Going or gone back to sender. | Return to sender · Retoure eingeleitet |
cancelled |
Called off before delivery — neither a failure nor a return. | Order cancelled · Storniert · Envío anulado |
unknown |
Carrier wording could not be classified — shown as-is, never guessed. | (anything unclassifiable) |
Design rules
- Normalization is additive: the carrier's ORIGINAL wording is always preserved next to the canonical state — we classify, we never rewrite history.
- Unclassifiable wordings map to
unknown, never to a guess. exceptionis a flag, not a terminal state — shipments routinely recover from it.- States are deliberately few: eight states cover cross-carrier comparison; finer distinctions stay in the original wording.
Changelog
- v3 (2026-07-27) —
cancelledadded: a called-off shipment is neither an exception nor a return. Additive — existing consumers do not break. - v2 (2026-06-10) — published as an open spec; JSON download; consumed by timeline, API, webhooks, MCP.
- v1 (2026) — internal normalization introduced with the REST API.
See also: Verifiable Timeline spec · REST API docs · MCP server.