Skip to content

Shipment Itinerary Structure

The GET /shipments/{id}/itinerary endpoint provides access to the itinerary information for a specific shipment. The itinerary represents the planned route and stops for the shipment, including locations, dates, and other relevant details.

After reading this article you will understand:

  • The structure of the itinerary resource and its top-level properties.
  • How moves represent segments of a shipment's journey.
  • How events define pickup and delivery actions at specific locations.
  • The relationship between moves, events, and locations.
  • The common and event-specific fields available in the itinerary.

Overview

The itinerary is structured as a collection of moves, where each move represents a segment of the shipment's journey handled by a specific driver or carrier. Each move contains a series of events that define the pickup and delivery actions at various sites.

ℹ️ The ordering of moves and events must follow a logical sequence. Moves should be ordered sequentially from origin to destination, and events within each move should represent a valid sequence of pickup and delivery actions in the context of the shipment.

For complete end-to-end examples of shipment itineraries with multiple moves, see the GET /shipments/{id}/itinerary endpoint in the API specifications.

Top-Level Structure

{
  "id": "12345",
  "self": "/shipments/12345/itinerary",
  "shipment": { ... },
  "moves": [ ... ]
}
  • id: Unique identifier for the shipment.
  • self: URI reference to this itinerary resource.
  • shipment: Reference to the parent shipment.
  • moves: Ordered list of moves that comprise the shipment's route.

Shipment Reference

"shipment": {
  "id": "12345",
  "href": "/shipments/12345",
  "orderNumber": "12345"
}

Links back to the parent shipment with its ID, API endpoint, and order number. The ID and href can be used to retrieve additional shipment details if needed.

Moves

A move represents a distinct leg of the shipment handled by a single driver or carrier. Moves are ordered sequentially to show the complete journey from origin to final destination.

{
  "driver": { ... },
  "events": [ ... ],
  "plannedDate": "2020-02-27",
  "powerUnit": { ... },
  "status": "completed",
  "hint": "987"
}
  • driver: Reference to the driver or carrier responsible for this move.
  • events: Ordered list of pickup/delivery events for this move.
  • plannedDate: The date this move is planned to occur.
  • powerUnit: Reference to the tractor/truck assigned to this move.
  • status: Current status of the move. Possible values: "pending", "accepted", "rejected", "progress", "completed".
  • hint: Additional reference number.

Driver/Carrier Information

The driver or carrier responsible for this move. Additional details can be retrieved using the provided href.

"driver": {
  "id": "100",
  "href": "/drivers/100",
  "type": "driver"
}
  • id: Unique identifier for the driver or carrier.
  • href: API endpoint to retrieve driver/carrier details.
  • type: Type of operator: "driver" (internal) or "carrier" (external).

Power Unit

The tractor or truck used for this move. Additional details can be retrieved using the provided href.

"powerUnit": {
  "id": "10000123",
  "href": "equipment/tractors/10000123"
}
  • id: Unique identifier for the power unit (tractor/truck).
  • href: API endpoint to retrieve full power unit details.

Events

An event represents a specific action at a location, such as picking up or dropping off a container. Events are ordered chronologically within each move.

All events share the following common event structure:

{
  "type": "hook-origin",
  "site": { ... },
  "scheduled": "2020-02-27T13:00:00",
  "appointment": { ... },
  "arrived": "2020-02-27T13:00:00",
  "departed": "2020-02-27T13:30:00",
  "completed": true,
  "note": "Handle with care",
}
  • type: Type of event (e.g., "hook-origin", "drop-destination").
  • site: Location reference where the event occurs.
  • scheduled: When the event is scheduled to occur (internal plan).
  • appointment: Appointment window details (on-site).
  • arrived: Actual arrival time at the site.
  • departed: Actual departure time from the site.
  • completed: Whether the event has been completed.
  • note: Additional notes or instructions for the event.

ℹ️ The scheduled time represents the internal planning time when the company intends the event to occur, while the appointment defines the time window agreed upon with the external site or customer. The scheduled time is used for internal logistics planning, whereas the appointment window is what the driver must adhere to when arriving at the location.

Appointment Window

The driver is expected to arrive within this time window at the site location and may use the number for check-in or confirmation.

"appointment": {
  "start": "2020-02-27T13:00:00",
  "end": "2020-02-27T13:30:00",
  "number": "1234567"
}
  • start: Appointment window start time.
  • end: Appointment window end time.
  • number: Appointment confirmation number.

Site Information

The location where the event takes place. Additional details can be retrieved using the provided href. Depending on the event type, the location may be a site, cross-dock location, or yard location.

"site": {
  "id": "111",
  "href": "/locations/sites/111",
  "name": "SITE 123",
  "address1": "1 WASHINGTON ST.",
  "city": "DOVER",
  "state": "NH",
  "zip": "03878",
  "country": "US",
  "signatureRequired": true
}
  • id: Unique identifier for the location.
  • href: API endpoint to retrieve full location details.
  • name: Location name.
  • address1: Street address.
  • city: City name.
  • state: State/province code.
  • zip: Postal code.
  • country: ISO country code.
  • signatureRequired: Whether a signature is required at this location.

Conclusion

The shipment itinerary structure provides a comprehensive representation of the planned route and actions for a shipment. You now understand the structure of the itinerary resource and its top-level properties, how moves represent segments of a shipment's journey, and how events define pickup and delivery actions at specific locations. You've also learned about the relationship between moves, events, and locations, as well as the common and event-specific fields available in the itinerary. This detailed structure allows for clear visibility into each segment of the journey, enabling you to effectively track and manage shipments throughout their lifecycle.