Create and manage shipments

A shipment describes a structure of a multimodal logistics journey. Shipments are useful when the lifetime of an asset you are tracking spans across multiple tracker devices.
A shipment consists of segments.
Devices assigned to a shipment generate traces and events for the entire shipment.
The shipmentId of a shipment can be used in similar fashion as a trackingId in Tracking APIs (where applicable). For example, one can query shipment traces and events and associate aliases and metadata to a shipment.

A new shipment should be instantiated for each separate logistical journey.
A new shipment should be instantiated for each separate logistical journey.

A shipment segment can have a subshipment assigned to it in place of the trackingId, that is if the trackingId of a segment contains a shipmentId the segment has a subshipment. Subshipments have the following limitations:

• Subshipments must have the subShipment property set to true.
• Subshipments must be created before they can be used as subshipment in another shipment (parent shipment).
• Subshipments can not be deleted if used in a parent shipment.
• Only one level of subshipments is supported, as a subshipment can not contain other subshipments.
• The parent segment origin must be the same as the origin of the first subshipment segment, and the parent segment destination must be the same as the destination of the last subshipment segment.

When creating shipments, it is highly recommended to set autoStart property to true.

If the shipment has autoStart property enabled, a shipment is started when the HERE Tracking API receives a telemetry ping from within the origin location and then one outside of the origin location. The shipment is marked complete once the ping is received within the destination location.

Shipment states can also be affected by external location events.

Estimated Time of Arrival (ETA) prediction for a shipment is initially calculated when a shipment is created, in case an estimated time of departure is provided. Once the shipment is started, the ETA prediction is updated each time when a device associated with the shipment sends a new telemetry ingestion.

The latest ETA prediction can be obtained from the shipment details.

Shipments are managed via the shipments endpoint.