Docs
Sign in

Tracking events

Updated May 29, 20262 min read

Tracking events let your systems and Carriyo's customer-facing apps know what is happening to a shipment in real time.

The single most important thing to understand: Carriyo normalizes. Carriers each have their own status vocabularies ("Onfoot", "Out for delivery", "Delivery in progress"). Carriyo maps every carrier's vocabulary to one canonical Carriyo status set. Your systems work against the canonical vocabulary; carrier quirks stay invisible.

The canonical status set

The full vocabulary lives at Reference → shipment status flow. The most-acted-on subset:

  • BOOKED: carrier accepted the booking, waiting for pickup.
  • READY_TO_SHIP: warehouse-ready handoff, often used as the customer-facing "your order is being prepared" trigger.
  • PICKED_UP: carrier has the parcel.
  • IN_TRANSIT: moving through the carrier network.
  • OUT_FOR_DELIVERY: final-mile, on the truck for delivery today.
  • DELIVERED: confirmed delivery.
  • FAILED_DELIVERY: attempt failed; carrier will typically retry.
  • RETURNED: never delivered, en route back to the merchant.
  • CANCELLED: booking voided before delivery.
  • ERROR: booking or carrier-side error; needs intervention.

Most integrations subscribe to all of these. Some only act on a few: DELIVERED to fire a notification or trigger revenue recognition, FAILED_DELIVERY to open a support ticket, the rest to update an OMS field.

Where events come from

Two sources produce tracking events:

  • Carrier callbacks. As carriers process the parcel, they report status to Carriyo (via webhook from their side). Carriyo receives the carrier's vocabulary and translates to the canonical set.
  • Workflow actions. Operations performed in the Carriyo system (booking, cancellation, mark-ready-to-ship, reprocess) drive their own status transitions, also as canonical events.

Both reach subscribers the same way: a shipment-status webhook fired per transition (the Notify on status trigger; see Webhook configurations). From the consumer's perspective, there's no difference between a status that came from the carrier and one that came from a Carriyo workflow action.

Carrier-status mappings

When you need to know exactly what carrier status produced a given Carriyo status (for diagnosis, reconciliation, or carrier-specific reporting), the carrier's raw status is preserved on the shipment record alongside the canonical one.

The full per-carrier crosswalk lives at Reference → shipment status mappings (forthcoming as part of the Reference expansion).

Order of events isn't guaranteed

A shipment's events can arrive out of sequence. Carriers batch updates, retries reorder things, and webhook delivery itself can be non-strict. Don't rely on arrival order; use the occurred_at timestamp inside each event.

And don't regress in your downstream system: if you're tracking the current status as DELIVERED, an IN_TRANSIT event that arrives late shouldn't roll back. Compare timestamps and take the latest.

How it fits with other modules

  • Webhooks. The delivery mechanism for tracking events.
  • Post-purchase CX. Branded tracking pages, notifications, and the Customer Feedback Loop all consume tracking events.
  • Shipping. Events are tied to shipments; the lifecycle is what produces them.