Enums & Lifecycle

Shipment Statuses & Stages

ClearTrack normalizes disparate carrier statuses into standardized status enums and high-level pipeline stages.

Top-Level Status Enum (`status`)

The top-level status field reflects the overall delivery state of the shipment.

Status Value	Meaning & Description
`pending`	Shipment has been created or manifested, but initial scan has not yet occurred.
`order_placed`	Carrier order record created in shipping partner system.
`awaiting_pickup`	Manifest submitted to courier network; awaiting physical pickup.
`picked_up`	Package physically collected from warehouse or merchant location.
`shipped`	Consignment handed over and registered at origin gateway hub.
`in_transit`	Package actively moving through hub sorting facilities and line-haul legs.
`out_for_delivery`	Package loaded onto delivery vehicle for final-mile delivery attempt.
`delivered`	Package successfully handed over to the recipient (terminal state).
`exception`	Delivery delayed due to operational constraint, address issue, or external hold.
`returned`	Shipment in return transit or delivered back to origin shipper (RTO).
`cancelled`	Booking or order cancelled prior to handover or processing.

The insights.current_stage field categorizes the active phase of the fulfillment lifecycle, designed for automated customer messaging triggers.

Stage Value	Meaning & Description
`booked`	Shipment manifested or booked with courier partner.
`in_transit`	Consignment in transit between sorting hubs or transport terminals.
`out_for_delivery`	Consignment dispatched from destination branch for final delivery.
`delivery_attempted`	Delivery attempted at least once without successful handover.
`delivered`	Consignment delivered to recipient.
`rto_in_progress`	Return to Origin initiated and shipment in reverse transit.
`rto_delivered`	Shipment successfully returned to origin merchant warehouse.
`exception`	Shipment held at terminal or sorting facility with an active delay flag.
`cancelled`	Shipment or booking cancelled prior to transit or physical handover (terminal state).
`unknown`	Current stage cannot be determined from available scan activities.