Organize a journey with segments

A segment represents a part of the logistics journey. An individual segment spans from one location to another, or to the same location if the segment is a dwelling segment.

The segments of a shipment must form a continuous chain of locations, wherein the origin of one segment must match the destination of the previous segment.

The trackingId refers to a claimed device that's assigned to a specified segment of the shipment. However, each segment of the shipment can be assigned to a different tracking device, so the trackingId can alter between segments. This is common when a shipment is tracked indirectly, as with certain carriers or a marine tracking integration.

For information on claiming a device, see the Getting started section of this guide.

A segment's state transitions are automatically updated if the segment has an assigned trackingId and the locations of the segment have been assigned with geofences. Otherwise, the segment's state can be updated manually by using the update segment details endpoint.

Automated state transitions only work if the location geofences do not overlap with each other, and if the shipment passes through all the locations in the order specified for that shipment.

When automated state transitions are used, a moving segment is automatically started when the device leaves the origin location, and completed when the device enters the destination location. Dwelling segments start upon entering the origin location, and are complete upon exiting the destination.

If automated state transitions are in use and the first segment of the shipment is a dwelling segment, the shipment and the first segment begin when device enters the origin location of the dwelling segment. Correspondingly, if the last segment is a dwelling segment, the shipment and the last segment are complete when device exits the final destination location.