Shipment Itinerary Updates

Updating shipment itineraries requires careful handling to ensure data consistency and avoid conflicts. The PUT /shipments/{id}/itinerary endpoint allows you to modify moves, events, and driver assignments for an existing shipment.

After reading this article you will understand:

The recommended GET-modify-PUT workflow for updating shipment itineraries
Common update scenarios and their specific validation requirements
Why validation errors occur and how to prevent them
How automatic updates are applied by the TMS when you submit changes
Best practices for preserving data integrity and avoiding conflicts

Overview

Itinerary updates modify the planned route, driver assignments, scheduled times, and event ordering for a shipment. Since itineraries can be complex structures with multiple moves and events, following the proper update workflow is essential to maintain data integrity.

Best Practice

ℹ️ Always retrieve the current state before making updates. Itineraries may have been modified by other users or processes, and working with stale data can lead to conflicts or lost changes.

Step 1: Retrieve Current Itinerary

Request the current itinerary using GET /shipments/{id}/itinerary to ensure you're working with the latest data. The response includes all moves, events, driver assignments, and other supported properties.

Step 2: Modify the Payload

Common modifications include:

Add, remove, or reorder moves
Add, remove, or reorder events within moves
Update event fields (scheduled times, appointments, arrivals, departures, sites, notes)
Change driver or carrier assigned to a move (modifies driver's planned route)

Important Considerations:

Maintain logical event ordering (see Move Event Types for ordering rules)
Ensure moves are ordered from origin to destination
Preserve required fields when modifying existing events
Follow equipment state transition rules between events
When assigning a driver to a move, ensure the planned date and scheduled time make sense in the context of the current driver plan

Step 3: Submit the Update

Send the modified itinerary back using PUT /shipments/{id}/itinerary and process the response.

Best Practice

⚠️ A successful PUT does not guarantee that only your submitted changes were applied. Some fields may be automatically updated by the TMS based on business rules and some may be ignored. An application should verify the changes from the response to confirm the update was applied as intended.

The TMS may automatically update related fields based on business rules:

Setting departed on an event may automatically set completed: true
Completing all events in a move may change move status to completed
Starting work on an event may change move status to progress
Assigning or changing a driver or carrier on a move may impact the affected drivers' plans

Common Update Scenarios and Validation

This section describes common scenarios where itinerary updates are needed and the validation errors you may encounter. Understanding these scenarios helps prevent validation failures and ensures updates are processed correctly.

The API validates itinerary updates using multiple rules that check business logic, data integrity, and workflow constraints. When validation fails, it returns a 400 Bad Request or 422 Unprocessable Entity with detailed error messages.

Example Validation Error Response:

{
  "data": {
    "failure_messages": [
      "The event sequence specified is invalid.",
      "A hook, pickup, or mount at the origin of the shipment does not exist prior to a drop, deliver, or dismount at the destination of the shipment."
    ]
  },
  "description": "Bad Request",
  "message": "There were 2 validation errors.",
  "status": 400
}

Driver Arrives at Location

Scenario: Driver uses mobile application to mark arrival at a site (customer location, yard, cross-dock, etc.)

What Gets Updated:

Event arrived field set to current timestamp
Event status may change to progress
Move status may change if this is first event being worked

Common Validation Errors:

Events In Progress Rule: "Events that are completed cannot be changed."

Rationale: A shipment's itinerary reflects actual work performed. Once an event has a departure timestamp, the work at that location is complete. Allowing changes to completed events could create data inconsistencies and misrepresent the shipment's history, impacting reporting, billing, driver/vendor pay, and compliance.

An application should not modify event type, site, or timestamps after departure
An application should not attempt to change history

Shipment Status Rule: "Shipment {id} has a status of {status} and does not allow updates."

Rationale: Certain shipment statuses prevent modifications. Cancelled shipments should not be modified. Template shipments serve as blueprints and should not have specific dates and times set since they are not active shipments.

An application should not attempt to update the itinerary if shipment is cancelled, declined, or template
Always check shipment status before attempting updates

Driver Departs from Location

Scenario: Driver uses mobile application to mark departure from a site after completing required activities

What Gets Updated:

Event departed field set to current timestamp
Event completed automatically set to true
Move status may change to completed if all events are done

Common Validation Errors:

Events In Progress Rule: "Events that are completed cannot be changed."

Rationale: Maintaining accurate timelines is essential for logistics operations.

An application should not set departure without arrival timestamp
An application should not set departure earlier than arrival

Insert Yard Moves

Scenario: Application adds yard moves to stage equipment for optimized logistics flow

What Gets Updated:

An existing move becomes two moves by splitting the existing events into separate moves by inserting a drop-yard event at the end of the first move and hook-yard event at the start of the second move

Common Validation Errors:

Event Sequence Rule: "The event sequence specified is invalid. {next_event_type} cannot come after {current_event_type}."

Rationale: Yard moves must follow logical sequencing without breaking equipment continuity.

Yard drops should be followed by yard hooks: drop-yard → hook-yard
Equipment states must transition logically throughout sequence
First event should be valid starting type (e.g., hook-origin, mount-origin, hook-yard, pickup-crossdock)
Last event should be valid ending type (e.g., drop-destination, dismount-destination, drop-yard, deliver-crossdock)

Event Sites Rule: "Site id {id} is not a valid yard location."

Rationale: Yard events must reference valid yard locations to ensure accurate equipment tracking. Customer sites and cross-dock locations are distinct location types and cannot be used for yard events.

An application should use yard locations for yard events

Origin/Destination Rule: "A hook, pickup, or mount at the origin of the shipment does not exist prior to a drop, deliver, or dismount at the destination of the shipment."

Rationale: The origin and destination events define the start and end points of the shipment. Inserting yard moves should not alter these critical points in the itinerary.

Origin event must come before destination event in sequence
Cannot change origin or destination site IDs when inserting yard moves
An application should maintain complete origin → destination flow

Insert Chassis Events

Scenario: Application adds chassis pickup and return events for container operations

What Gets Updated:

New events added at the beginning of a move for chassis pickup from pool (hook-chassis), followed by container mount
New events added at the end of a move for chassis return to pool (drop-chassis), preceded by container dismount

Common Validation Errors:

Event Sequence Rule: Equipment state transitions must be valid

Rationale: Chassis events should maintain logical equipment states throughout the itinerary.

After hook-chassis, driver is pulling bare chassis (can proceed to mount-empty, mount-loaded, mount-origin, or drop-chassis if no container needed)
After drop-chassis, the next should begin with an event ensuring the driver of that move will acquire or is bringing along a chassis from their prior move (e.g., hook-chassis, mount-origin, mount-empty)

Driver Planning / Move Assignment

Scenario: Dispatcher assigns driver to move(s) to plan daily route with scheduled event times

What Gets Updated:

Move driver is populated with driver or carrier information
Driver's plan updated with new assignment
Move planned date and scheduled times adjusted

Common Validation Errors:

Driver Assignment Rule: "The new drivers being assigned are required to meet license, medical, and hazmat requirements of the shipment."

Rationale: Drivers and carriers should meet regulatory and safety requirements to ensure compliance and safe operation.

For Drivers:

License should not be expired
Medical certification should not be expired
Hazmat shipments require valid, non-expired hazmat certification

For Carriers: "The new carriers being assigned are required to have a signed contract, federal id, valid certifications, and no expired insurance documents."

Cargo insurance, liability insurance, workers comp should not be expired
Should have federal ID on file
Should have signed contract
Should be certified as broker, common carrier, and contract carrier
Hazmat shipments require valid hazmat certification

Equipment Assignment Rule: "Cannot assign driver to the move because there are invalid itinerary states as the result."

Rationale: Driver assignments should create logistically feasible plans without equipment conflicts.

Assignment cannot alter equipment history
Driver timeline must be logistically feasible
Same equipment cannot be in multiple locations simultaneously
Equipment continuity should be maintained throughout itinerary

Move Accept/Reject Rule: "A driver must be specified to set the move status to accepted or rejected."

Cannot set move status to accepted or rejected without driver assignment
not-routed driver type cannot have accepted/rejected status

Driver Planning / Driver Reassignment

Scenario: Change driver assignment mid-route or transfer work between drivers

What Gets Updated:

Move driver updated to new driver or carrier
Both drivers' plans updated
Equipment assignments validated for both drivers

Common Validation Errors:

Events In Progress Rule: "Events that are completed cannot be changed."

Rationale: Reassigning moves with completed work could disrupt operations and affect driver/carrier pay, reporting, and compliance.

An application should not reassign moves with departed events

Driver Assignment Rule: New driver must meet same requirements

License, medical, hazmat validations apply to new driver
Carrier validations apply if reassigning to carrier

Equipment Assignment Rule: Both driver plans must remain valid

Reassignment cannot create equipment conflicts for either driver
Timeline must work for both original and new driver
Equipment continuity must be maintained

Appointment Scheduling

Scenario: Application updates scheduled appointment times for customer sites

What Gets Updated:

Event appointment object may include an appointment number and appointment window
Event scheduled field may be updated with new appointment time
Driver plan adjusted for new timing if driver is assigned

Common Validation Errors:

Appointment Chronology Rule: "Appointment dates/times should be in order for all events that are being scheduled for a driver."

Rationale: Appointment times must be logically ordered to ensure drivers can meet scheduled commitments without conflicts.

Appointment times should be chronologically ordered across all events
New appointment cannot be earlier than last departed/arrived event
Each appointment should be later than previous appointment

Events In Progress Rule: "Events that are completed cannot be changed."

Rationale: Changing appointments for completed events creates inconsistencies in driver plans and historical records.

An application should not update appointment times for events with departure timestamps

Understanding Error Responses

400 Bad Request - Validation failed (see scenarios above for specific errors)

404 Not Found - "Shipment not found." - Verify shipment ID is correct - Shipment may have been deleted

422 Unprocessable Entity - Similar to Shipment Status Rule - Request well-formed but cannot be processed due to business logic

Best Practices for Avoiding Validation Errors

Always GET before PUT - Retrieve current state to work with latest data
Check shipment status - Verify status allows updates (not cancelled, declined, or template)
Validate event sequences - Use Move Event Types to ensure valid transitions
Respect departed events - Don't modify or remove events with departure timestamps
Match sites to event types - Use yard sites for yard events, cross-docks for cross-dock events
Validate driver credentials - Check license, medical, hazmat expirations before assignment
Maintain origin/destination - Don't change site IDs on origin/destination events
Keep appointments chronological - Ensure appointment times are ordered and after in-progress work
Check equipment continuity - Verify equipment states transition logically throughout itinerary

Best Practices

Do:

Always GET before PUT - Retrieve current state to avoid conflicts with concurrent changes
Validate event sequences - Ensure logical flow from origin to destination
Preserve completed work - Don't remove or modify events with departure timestamps
Maintain chronological order - Ensure arrival precedes departure, and appointments are sequential
Check response for automatic changes - Review returned itinerary for TMS-applied updates
Validate driver credentials - Check license, medical, and hazmat certifications before assignment
Match site types to events - Use yard sites for yard events, cross-docks for cross-dock events
Handle validation errors gracefully - Provide clear feedback based on error messages

Don't:

Assume stale data is current - Always retrieve fresh data before updates
Modify departed events - Preserve historical data for completed work
Change origin/destination sites - These define the shipment and cannot be altered
Ignore shipment status - Verify shipment is not cancelled, declined, or template
Create equipment conflicts - Ensure driver assignments don't violate equipment timelines

Additional Resources

For detailed information about specific types of updates, see:

Shipment Itinerary Structure - Field definitions and structure
Move Event Types - Valid event types and ordering rules
API Reference - Complete endpoint specifications and examples

Conclusion

Successful itinerary updates require following the GET-modify-PUT workflow to work with current data. Understanding common update scenarios—such as driver arrivals/departures, yard move insertions, chassis repositioning, driver assignments, and appointment scheduling—helps you anticipate and prevent validation errors. The TMS automatically updates related fields based on business rules, so always verify the response to confirm your changes were applied as intended. By respecting completed work, maintaining logical event sequences, and validating driver credentials, you can ensure data integrity and avoid conflicts during itinerary modifications.