Shipment Itinerary
The shipment itinerary is a representation of all the moves that must be executed in order to complete the work for a shipment. A shipment move is composed of a list of events that should occur at the event site locations in the order specified within the move. A shipment move also contains a reference to a driver, carrier, or possibly no driver if the move is not yet assigned. As an assigned driver arrives and departs at the move events, events become completed, and the move status will become completed when all the events are completed. When all the moves have a status of completed, the work on the shipment is done.
Prerequisites
Before working with shipment itineraries, you should be familiar with:
- Basic REST API concepts (GET, PUT, POST requests)
- JSON data format and structure
- Transportation Management System (TMS) fundamentals
- The Shipment Resource API endpoints
Learning Objectives
After reading this documentation, you will be able to:
Foundation Knowledge: - Understand the structure and components of shipment itineraries - Identify the relationship between moves, drivers, events, and sites - Interpret itinerary status values and their business meanings
Practical Operations: - Retrieve shipment itineraries using the REST API - Create and modify move sequences for different shipment scenarios - Assign and reassign drivers or carriers to specific moves - Update event arrivals, departures, and appointment information - Validate itinerary changes against business rules
Advanced Scenarios: - Handle complex multi-move shipments (import/export, cross-dock, yard operations) - Implement proper event sequencing for different equipment types - Troubleshoot common validation errors and API failures - Design itineraries for street-turn and equipment reuse scenarios
Error Handling: - Identify and resolve common itinerary validation failures - Understand business rule constraints and their purposes - Handle equipment assignment conflicts and scheduling issues
Common Use Cases
This documentation covers real-world scenarios including:
- Simple Point-to-Point Delivery: Single move from origin to destination
- Import Container Operations: Multi-move sequences with empty returns
- Cross-dock and Consolidation: Multiple pickups and deliveries with intermediate stops
- Yard Storage Operations: Temporary equipment drops and later pickups
- Street-turn Scenarios: Equipment reuse between different shipments
- Driver Reassignment: Handling driver unavailability and route optimization
- Emergency Routing Changes: Modifying itineraries for operational disruptions
Itinerary Moves, Drivers, Events, and Sites
To retrieve a shipment itinerary:
The response will return information about the shipment itinerary with the following structure:
{
"moves":[
{
"driver":{
"id":"100",
"href":"/carriers/100",
"type":"carrier"
},
"events":[
{
"appointment": {
"end": "2020-02-27T13:00:00",
"number": "event-1-appt-number",
"start": "2020-02-27T12:30:00"
},
"scheduled":"2020-02-27T13:00:00.571307-05:00",
"arrived":"2020-02-27T13:00:00.571307-05:00",
"completed":true,
"departed":"2020-02-27T13:30:00.571307-05:00",
"note":"Event site matches the origin site of the shipment",
"site":{
"id":"111",
"href":"/locations/sites/111"
},
"type":"hook-origin"
},
{
"appointment": {
"end": "2020-02-27T14:30:00",
"number": "event-2-appt-number",
"start": "2020-02-27T14:00:00"
},
"scheduled":"2020-02-27T14:30:00.571307-05:00",
"arrived":"2020-02-27T14:30:00.571307-05:00",
"completed":true,
"departed":"2020-02-27T14:45:00.571307-05:00",
"note":"Site id matches destination site on shipment",
"site":{
"id":"222",
"href":"/locations/sites/222"
},
"type":"drop-destination"
}
],
"status":"completed"
},
{
"driver":{
"id":"200",
"href":"/drivers/200",
"type":"driver"
},
"events":[
{
"appointment": {
"end": "2020-02-28T13:00:00",
"number": "event-3-appt-number",
"start": "2020-02-28T12:30:00"
},
"scheduled":"2020-02-28T13:00:00.571307-05:00",
"arrived":"2020-02-28T13:00:00.571307-05:00",
"completed":true,
"departed":"2020-02-28T13:30:00.571307-05:00",
"note":"",
"site":{
"id":"222",
"href":"/locations/sites/222"
},
"type":"hook-empty"
},
{
"appointment": {
"end": "2020-02-28T14:30:00",
"number": "event-4-appt-number",
"start": "2020-02-28T14:00:00"
},
"scheduled":"2020-02-28T14:30:00.571307-05:00",
"arrived":"2020-02-28T14:30:00.571307-05:00",
"completed":true,
"departed":"2020-02-28T14:45:00.571307-05:00",
"note":"",
"site":{
"id":"111",
"href":"/locations/sites/111"
},
"type":"drop-empty"
}
],
"status":"completed"
}
],
"id":"12345",
"self":"/shipments/12345/itinerary",
"shipment":{
"id":"12345",
"href":"/shipments/12345"
}
}
Above is a representation of an import shipment itinerary "12345" with two moves. The first move is the loaded move that was assigned and completed by carrier id "100". A hired carrier performed a hook at the origin site "111" of the shipment and dropped the loaded shipment at the destination site "222". The next day a company driver "200" hooked the empty at site "222" and returned the empty to site "111". Information about when the carrier and driver arrived and departed the various locations can be seen in the event objects, along with any appointment information for when they should have been there. Other resource reference information for the carrier, company driver, event site locations, and the shipment is available in the payload, and can be queried by following the "href" location on the API.
Export Shipment Example with pickupBy:
For export shipments, the pickupBy field can be included on hook-origin or mount-origin events to specify the deadline by which the loaded container must be picked up from the origin site. This ensures the driver knows when the container needs to be collected to allow sufficient time for delivery to the port before the port cutoff deadline.
{
"moves":[
{
"driver":{
"id":"300",
"href":"/drivers/300",
"type":"driver"
},
"events":[
{
"scheduled":"2020-03-01T08:00:00",
"appointment": {
"start": "2020-03-01T08:00:00",
"end": "2020-03-01T10:00:00",
"number": "EXPORT-001"
},
"arrived":"2020-03-01T08:15:00",
"completed":true,
"departed":"2020-03-01T08:45:00",
"pickupBy":"2020-03-01T10:00:00",
"note":"Container must be picked up by 10AM to reach port in time",
"site":{
"id":"555",
"href":"/locations/sites/555"
},
"type":"hook-origin"
},
{
"scheduled":"2020-03-01T14:00:00",
"appointment": {
"start": "2020-03-01T13:00:00",
"end": "2020-03-01T15:00:00",
"number": "PORT-GATE-789"
},
"arrived":"2020-03-01T13:30:00",
"completed":true,
"departed":"2020-03-01T14:15:00",
"note":"Delivered to port terminal",
"site":{
"id":"999",
"href":"/locations/sites/999"
},
"type":"drop-destination"
}
],
"status":"completed"
}
],
"id":"67890",
"self":"/shipments/67890/itinerary",
"shipment":{
"id":"67890",
"href":"/shipments/67890"
}
}
The pickupBy field in the example above indicates that the container must be picked up from the origin site by 10:00 AM on March 1st, 2020. This pickup deadline ensures the driver has enough time to transport the container to the port before the port's cutoff time for vessel loading. Dispatch systems can use this field to prioritize moves and schedule drivers accordingly to avoid late pickups that could result in missed vessel departures.
- Itinerary Data Properties:
| Property | Description |
|---|---|
| moves | Ordered list of moves in the shipment |
| id | Itinerary id (matches the shipment id it belongs to) |
| self | The itinerary resource location for querying or updating |
| shipment | The shipment resource location the itinerary goes with |
Itinerary Moves
A shipment itinerary may contain one or more moves. They are listed in the order that they should be worked on by a combination of drivers or carriers to complete the work for a shipment. At least one move is required on a shipment itinerary, and they must be completed in the order that they are specified. In other words, if a shipment has two moves, the second cannot be completed before the first move is completed.
The total work for the shipment may vary depending on various factors such as the container being loaded for import or export vs. a trailer being loaded for a pickup and delivery. Sometimes a chassis will need to be hooked before a container can be mounted, and other times a container may already be on a chassis. There may also be a need for a driver to make intermediate stops along the way to the final destination. There are other times when it may be necessary or more efficient for one driver to drop a container at a yard or deliver to a cross-dock location so that another driver can hook the container or consolidate freight on their trailer to complete the delivery. All of this is represented by a sequence of moves.
A Single Move
Example: A loaded hook at the origin followed by a drop at the final destination.
{
"driver":{
"id":"",
"href":"",
"type":"not routed"
},
"events":[
{
"appointment": {
"end": "",
"number": "",
"start": ""
},
"scheduled":"",
"arrived":"",
"completed":false,
"departed":"",
"note":"Event site matches the origin site of the shipment",
"site":{
"id":"111",
"href":"/locations/sites/111"
},
"type":"hook-origin"
},
{
"appointment": {
"end": "",
"number": "",
"start": ""
},
"scheduled":"",
"arrived":"",
"completed":false,
"departed":"",
"note":"Site id matches destination site on shipment",
"site":{
"id":"222",
"href":"/locations/sites/222"
},
"type":"drop-destination"
}
],
"status":"pending"
}
A valid move is a unit of work a single driver or carrier can complete and consists of at least two events that make sense for a driver to perform in sequence. Initially a move may not be assigned to a driver or carrier and has a status of pending as seen in the payload below. The “status” value of “pending” is a derived value as none of the events have been assigned to a driver. See further down for an explanation of the move properties and possible values.
- Move Data Properties:
| Property | Description |
|---|---|
| driver | A reference to the driver or carrier assigned to the move |
| events | Ordered list of events that should occur at specific locations |
| status | Derived status of the move |
| shipment | The shipment resource location the itinerary goes with |
| * Move Driver: |
Example:
A reference to the driver or carrier who will be accepting, rejecting, and possibly completing the move. When the move is not assigned, the driver type will be “not routed”.
- Driver Data Properties:
| Property | Description |
|---|---|
| id | The id of the driver |
| href | Resource location where the driver or carrier information exists |
| type | carrier, driver, or not routed |
| * Driver Types: |
| Type | Description |
|---|---|
| not routed | A driver has not been assigned to the move |
| carrier |
A business entity who will handle the move (not a specific driver) on behalf of the trucking company |
| driver | A human entity who will handle the move |
| * Derived Move Status Values: |
| Value | Description |
|---|---|
| pending | Driver not assigned or has not yet accepted or rejected the move |
| accepted | Driver has accepted the move and has not yet arrived at events[1] |
| rejected | Driver has rejected the move and will not arrive at any events |
| progress | Driver has arrived, departed, or completed some of the events |
| completed | Driver has arrived, departed, and completed all of the events |
- Move Events:
A move contains an ordered list of events that must be completed sequentially at specific location sites. Each event has standard properties (scheduled, arrived, departed, completed, appointment, site, type, note) and may include optional specialized properties that apply only to specific event types and shipment scenarios.
Standard Event Properties:
| Property | Type | Description |
|---|---|---|
| scheduled | datetime/date | The scheduled date/time for the event |
| appointment | object | Optional appointment window with start, end, and number fields |
| arrived | datetime | Actual arrival time at the event site |
| departed | datetime | Actual departure time from the event site |
| completed | boolean | Whether the event has been completed |
| site | object | Reference to the location where the event occurs |
| type | string | The event type (hook-origin, drop-destination, etc.) |
| note | string | Optional notes about the event |
Specialized Event Properties:
Some event types support additional optional properties that apply only to specific business scenarios. These properties provide specialized information relevant to particular shipment types, event types, or operational requirements.
| Property | Type | Event Types | Shipment Types | Description |
|---|---|---|---|---|
| pickupBy | datetime | hook-origin, mount-origin | Export | ISO 8601 datetime indicating the deadline by which a loaded container must be picked up from the origin site for export shipments. This ensures sufficient transit time to deliver the container to the port before the port cutoff deadline. |
Future Specialized Properties:
The API is designed to support additional specialized properties as business needs evolve. Future enhancements may include properties for other event types (e.g., customs clearance timestamps for import shipments, detention-free time for storage events, temperature requirements for reefer events). When using the API, applications should be prepared to handle optional properties they may not recognize and should only set specialized properties when the documented conditions (event type, shipment type, etc.) are met.
-
A Single Move Event:
-
An Event Site:
Use Cases
-
Adding and Removing Moves in a Shipment:
-
Assigning and Removing a Driver or Carrier in a Move:
-
Updating Arrivals and Departures:
Itinerary Validation Rules
When sending an update to an itinerary with invalid itinerary information, the API will return an http 400 status BAD REQUEST.
See the following request with a problematic payload.
Payload:
{
"id": "5587",
"moves": [
{
"driver": {
"href": "",
"id": "",
"type": "not routed"
},
"events": [
{
"appointment": {
"end": "",
"number": "",
"start": ""
},
"scheduled": "",
"arrived": "",
"completed": false,
"departed": "",
"note": "",
"site": {
"href": "/locations/sites/109",
"id": "109"
},
"type": "hook-origin"
},
{
"appointment": {
"end": "",
"number": "",
"start": ""
},
"scheduled": "",
"arrived": "",
"completed": false,
"departed": "",
"note": "",
"site": {
"href": "/locations/sites/375",
"id": "375"
},
"type": "pickup-stopoff"
},
{
"appointment": {
"end": "",
"number": "",
"start": ""
},
"scheduled": "",
"arrived": "",
"completed": false,
"departed": "",
"note": "",
"site": {
"href": "/locations/sites/109",
"id": "109"
},
"type": "drop-empty"
}
],
"status": "pending"
}
],
"self": "/shipments/5587/itinerary",
"shipment": {
"href": "/shipments/5587",
"id": "5587"
}
}
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
}
The above example shows that there are two business rules that are being violated by the update above.
- 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.
Both of the failures are symptoms of the same problem with the payload event type properties that are expected for a valid shipment itinerary. The event sequence specified is invalid. is because the pickup-stopoff implies some freight was added to the container or trailer and therefore the next event drop-empty does not make any sense. To correct this problem there should be at least one delivery event following the pickup-stopoff such as a deliver-stopoff or deliver-destination inserted before the drop-empty or just converting the drop-empty to a drop-destination.
The second failure 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 can be corrected by changing the drop-empty event to a drop-destination as well. All shipments are required to have some hook, pickup, or mount at the origin site location of the shipment and some drop, deliver, or dismount at the final destination location of the shipment.
Business Rules
To ensure the itinerary is valid and the integrity of the TMSs data is maintained, the following validation rules should be in place, and may vary slightly depending on the underlying TMS.
| Rule | Description |
|---|---|
| Scheduled Appointments |
Scheduled Appointment date/times should be chronological. Example Failure Message: “Appointment dates/times should be in order for all events that are being scheduled for a driver.” |
| Driver Assignment |
A driver id of the specified driver or carrier type should be a valid record in the TMS and valid paperwork should be on file. Example Failure Messages: “The driver {id} does not exist in {drivers}.” “The carrier {id} does not exist in {carriers}.” “The new drivers being assigned are required to meet license, medical, and hazmat requirements of the shipment.” “The new carriers being assigned are required to have a signed contract, federal id, valid certifications and no expired insurance documents.” |
| Equipment Assignment |
Any containers, chassis, trailers, tractors, vans, etc. that a newly assigned driver or carrier will be using to available for use by that driver without overlapping planned or completed usage by other drivers or carriers. Example Failure Messages: “Cannot assign driver to the move because there are invalid itinerary states as a result.” “The assignment of carrier 100 would create an invalid itinerary assignment for chassis 505.” |
| Events in Progress |
Events that have occurred cannot be changed, such as a new driver assignment for an move that is completed. Example Failure Messages: “Events that are in progress cannot be changed.” “Events in progress cannot be removed.” |
| Events Sequence |
Event types in the itinerary must be specified as a logical sequence. For example a pickup-origin move cannot preceed a drop-empty event. Example Failure Messages: “The event sequence specified is invalid.” “A hook-origin cannot come after drop-destination in a “ shipment itinerary.” “A hook-origin cannot come after a drop-yard” |
| Events Sites |
The event site location should exist in the system as a site, yard, or cross-dock location in the system. IE. A hook-yard should be a yard location and a pickup-crossdock should be a cross-dock location. Example Failure Messages “Site id 200 does not exist in yards.” “Site id 500 does not exist in cross-docks.” “Site id 600 does not exist in sites.” |
| Move Accept Reject |
A move that is in progress or completed cannot be accepted or rejected. Only pending rules with an assigned driver or carrier can become accepted or rejected. Example Failure Messages “A driver must be specified to set the move status to accepted or rejected” |
| Shipment Origin / Destination |
A shipment must always have hook, pickup, or mount at its origin site followed by a drop, deliver, or dismount at its final destination. Changing the origin or destination site through the itinerary is not allowed. Example Failure Messages “A hook pickup, or mount at the origin of the shipment does not exist prior to a drop, deliver or dismount at the destination.” “The origin id 109 cannot be changed on the hook-origin.” “The destination id 110 cannot be changed on the drop-destination.” |
| Shipment Status |
Shipment has a status that prevents making changes to the itinerary. As an example a shipment that has not been accepted or has been cancelled should not allow any work to be performed. Example Failure Message: “Shipment 12345 has a status of cancelled and does not allow updates.” |
| Street Turn |
Non-routed events should only occur on the last events of an import shipment or the first events of an export shipment. Example Failure Messages “Non-routed events can only appear in the last move of an import shipment or the first move of an export shipment.” |
Scheduled
Scheduled, refers to the appointment start date and time, when specified should be in chronological order for the shipment.
Why We Validate Scheduled:
An appointment scheduling application using the API should not be able to set appointments for events that are not possible.
Driver Assignment
An assigned driver or carrier should exist in the system and meet all the requirements to complete the shipment.
Why We Validate Driver Assignment
All legal records should be up to date for a driver or carrier to ensure that they can legally perform the work to complete the shipment and as well as for proper planning and accounting purposes.
Equipment Assignment
When assigning a driver to a move all active containers, trailers, or chassis referenced by the shipment are expected to be used by the driver to complete the move. The equipment should be available for use by the time the driver is scheduled to perform the move.
Why We Validate Equipment Assignment:
An application or driver assignment application should not be able to create impossible move sequenses for any drivers, tractors, containers, chassis or trailers where the equipment usage is scheduled to overlap in a conflicting. Appointments and actual arrival and depart times can be used to determine new assignments by cross checking the system.
Events in Progress
Once an event is arrived at or completed by a driver, it cannot be rolled back by an external application. Similarly, once a move has had work performed on it, it cannot be modified by an external application, and prior moves on the same shipment cannot be changed.
Why We Validate Events in Progress
An application cannot make changes to events that have already occurred on a shipment. This includes adding and removing events before or changing event types and site locations that would occur before the work that has already been completed.
Events Sequence
A move has more than one event. A driver or carrier should be able to arrive at the first event of a move and complete the work at the event site as long as they have the required equipment before arriving at the site. When the event is completed, the driver should be leaving with any equipment that is required to complete the work on the next event, and so on until the move is completed. If there are more moves, the last event of the completed move should be leaving the shipment in a state where the next driver working on the future move can start work on the first event as long as they are bringing along any required equipment to complete the move.
Why We Validate Event Sequence
An application cannot make changes to a shipment move sequence by inserting or removing or updating events unless the total work of the shipment can be completed in sequence by one or more drivers and carriers.
An invalid itinerary move event sequence below
{
"id": "5587",
"moves": [
{
"driver": {
"href": "",
"id": "",
"type": "not routed"
},
"events": [
{
"appointment": {
"end": "",
"number": "",
"start": ""
},
"scheduled": "",
"arrived": "",
"completed": false,
"departed": "",
"note": "",
"site": {
"href": "/locations/sites/109",
"id": "109"
},
"type": "hook-origin"
},
{
"appointment": {
"end": "",
"number": "",
"start": ""
},
"scheduled": "",
"arrived": "",
"completed": false,
"departed": "",
"note": "",
"site": {
"href": "/locations/sites/250",
"id": "250"
},
"type": "drop-chassis"
},
{
"appointment": {
"end": "",
"number": "",
"start": ""
},
"scheduled": "",
"arrived": "",
"completed": false,
"departed": "",
"note": "",
"site": {
"href": "/locations/sites/375",
"id": "375"
},
"type": "dismount-destination"
}
],
"status": "pending"
}
],
"self": "/shipments/5587/itinerary",
"shipment": {
"href": "/shipments/5587",
"id": "5587"
}
}
The above shows an itinerary with event types that cannot possibly be performed by a driver in the sequence specified.
The sequence hook-origin, drop-chassis, dismount-destination has problems. Here is what this itinerary is saying should happen for the shipment.
- hook-origin arrival: The driver will arrive with a tractor that can hook a loaded container already mounted on its chassis at site location 109 which is the same as the origin site on the shipment.
- hook-origin depart: The driver will depart with the loaded container and chassis and start towards site location 250.
- drop-chassis arrival: The driver will arrive at site location 250 and leave only the chassis behind. Problem 1: the chassis still has the container on it!!! Its not possible to drop only the chassis.
- drop-chassis depart: The driver will depart site 250 without any equipment.
- dismount-destination arrival The driver will arrive at site location 375 and dismount the container. Problem 2: the container was still on the chassis that was dropped prior. This event should have happened prior to the dropped chassis.
- dismount-destination depart The driver will leave site location 375 with only the chassis, leaving the container behind.
Event Types
| Event Type | Description |
|---|---|
| deliver-crossdock |
A loaded freight carrying piece of equipment is unloaded at a cross-dock location. Before executing the event, the driver is expected to be driving the loaded freight carrying piece of equipment. After executing the event the driver is still driving the same equipment without any freight from the shipment on board. |
| deliver-destination |
A loaded freight carrying piece of equipment is unloaded at the final destination on the shipment. Before executing the event, the driver is expected to be driving a cargo carrying piece of equipment or a tractor pulling the loaded container or trailer. After completing the event, the driver is now driving the same equipment but now it is empty. The driver stays with the load the whole time. |
| deliver-stopoff |
A loaded freight carrying piece of equipment is partially unloaded at a location other than the final-destination of the shipment. Before executing the event the driver is expected to be driving a cargo carrying piece of equipment or a tractor pulling a the loaded container or trailer. After completing the event, the driver is now driving the same equipment with less freight than before. The driver stays at the location while unloading occurs. |
| dismount-destination |
A loaded container is removed from a chassis at an event site that matches the final destination on the shipment. Before executing the event, the driver is in a tractor, pulling a chassis with the loaded container on it. After the event is completed, the driver is expected to be in a tractor pulling a bare chassis. The driver leaves the container behind. |
| dismount-empty |
An empty container is removed from a chassis at an event site other than the final destination on the shipment. Before executing the event, the driver is expected to be driving a tractor while pulling an empty container on a chassis. After completing the event, the driver is still driving the same tractor and chassis, and has left the empty container behind. |
| dismount-loaded |
A container is removed from a chassis at an event site other than the final destination on the shipment. Before executing the event, the driver is in a tractor, pulling a chassis with the loaded container on it. After the event is completed, the driver is expected to be in a tractor pulling a bare chassis. The driver leaves the container behind. |
| drop-bobtail |
The driver arrives at the location with only a tractor. This is only used to signify that the driver drove from a different location with only a tractor. The only valid event type before this event type is a hook-bobtail. These may only be relevant to the shipment if the intent is to charge for the customer for this. After the event is completed the driver is still in the tractor. |
| drop-chassis |
The driver arrives at the location pulling a bare chassis. Before this event the driver will have hooked the bare chassis or dismounted a container. After the event is completed, the driver is no longer pulling the chassis. |
| drop-yard |
The driver arrives at a yard location pulling a mounted-chassis, or trailer and leaves the equipment behind. Before this event, the driver is pulling the empty or loaded equipment. After the event is completed, the driver leaves the mounted chassis or trailer behind. Note: dropping a bare chassis at a yard location should be treated as a drop-chassis event type where the site location is a yard location. |
| drop-destination |
The driver arrives at the location matching the final destination of the shipment with the loaded container or trailer. Before the event, the driver is pulling the loaded equipment. After the event is completed the driver is no longer pulling equipment and it has been left behind to be unloaded. The empty may be hooked again later. |
| drop-empty |
The driver arrives at a location that does not match the final destination of the shipment with an empty container or trailer. Before the event, the driver either hooked the chassis with the empty container already mounted or mounted the empty container, or hooked an empty trailer. After completing the event the driver is not pulling the mounted chassis nor trailer. |
| drop-loaded |
The driver arrives at a location that does not match the final destination of the shipment with a loaded container or trailer. Before the event, the driver either hooked the chassis with the loaded container already mounted or mounted the loaded container, or hooked a loaded trailer. After completing the event the driver is not pulling the mounted chassis nor trailer. |
| drop-non-routed |
A placeholder event on the shipment to represent an event that will not need to be completed by a driver because the equipment is being street-turned. There are two valid scenarios for a move ending with a drop-non-routed event type. These events never really occur and are automatically considered complete. 1. On an inbound/import shipment as the last event of the empty return move, the driver on the move hooks the empty prior to the drop-non-routed and instead of bringing the empty back, the driver brings it to be loaded and reused for a different outbound shipment. In this scenario, the other outbound shipment may start with a hook-non-routed event on its first move at a location where the empty would have been picked up, and the same driver who hooked the empty on the inbound shipment will drop the empty or pickup freight at the origin of the outbound shipment. 2. Another street-turn/reload scenario, except in this case the entire move has no driver and is automatically considered completed because instead returning the empty, the container or trailer will be reloaded onsite as part of another outbound/export shipment. In this case there will be an export shipment in the system that may have a hook-non-routed where the empty would have hooked/mounted followed by a drop-non-routed at the outbound/export shipment origination site. This will occur when the origin site location of the export shipment matches the destination site on the inbound/import shipment. |
| drop-stopoff |
A drop-stopoff is used to indicate a trailer/chassis drop at the stopoff location and is typically the end of that Leg in the itinerary. Stopoff events are used when the Trailer/Container needs to complete multiple stops as part of the Order Itinerary. These events are used to describe any hooks or drops that are not specifically defined in other event types (origin / destination / yard / etc.) These stopoffs do not affect the Loaded/Empty status of the container as freight may be added or removed from the container at this location, but is not indicated as part of the event type. A driver could do multiple drops where they leave the container, different from the destination for drops. |
| hook-bobtail |
The driver leaves the location with only a tractor. This is only used to signify that the driver is leaving the location without any equipment and the following event type is expected to be a drop-bobtail at a different location. The only time this is relevant to the shipment is if the customer is going to be charged. |
| hook-chassis |
The driver hooks a bare chassis on to their tractor. Prior to this event the driver is expected to be driving equipment that can pull the chassis. After the event is completed the driver is pulling a chassis, and may go mount a container or drop the chassis. |
| hook-empty |
The driver hooks a trailer or chassis mounted with an empty container at a location that is not the origination site on the shipment. Before this event the driver is expected to be driving equipment that can pull the empty. After the event is completed, the driver will bring the empty equipment to a location to be loaded or returned. |
| hook-loaded |
The driver hooks a trailer or chassis mounted with a loaded container at a location that is not the origination site on the shipment. Before this event the driver is expected to be driving equipment that can pull the loaded container. After the event is completed, the driver will bring the loaded equipment to the next location. |
| hook-non-routed |
A hook event that no driver will perform because equipment is being street turned from another load. See drop-non-routed. |
| hook-origin |
A driver arrives at a location that matches the origin of the shipment where the loaded trailer or container mounted on a chassis is hooked. Before the event the driver is expected to be driving a tractor that can hook the load. After the event is completed the driver is pulling the loaded equipment to another location to be dismounted, dropped or unloaded. |
| hook-stopoff |
A hook-stopoff is used to indicate a trailer/chassis hook at the stopoff location and is typically the start of that Leg in the itinerary. Stopoff events are used when the Trailer/Container needs to complete multiple stops as part of the Order Itinerary. These events are used to describe any hooks or drops that are not specifically defined in other event types (origin / destination / yard / etc.) These stopoffs do not affect the Loaded/Empty status of the container as freight may be added or removed from the container at this location, but is not indicated as part of the event type. |
| hook-yard |
A driver arrives at a yard location in the system and hooks a trailer or chassis with a mounted container. The trailer or container may be loaded or empty. Before the event the driver is expected to be driving a tractor capable of hooking the equipment. After the event is completed, the driver is pulling the trailer or mounted chassis and should be bringing the equipment to another location to be dropped, loaded, unloaded, or dismount the container. |
| mount-empty |
A driver arrives at a location that isn’t the origin site of the shipment with a bare chassis. An empty container is placed on top of the chassis. Prior to the event, the driver has hooked a chassis. After the event is completed, the driver brings the empty container with chassis to another location to be loaded, unloaded dropped, or dismounted. |
| mount-loaded |
A driver arrives at a location that isn’t the origin site of the shipment with a bare chassis. A loaded container is placed on top of the chassis. Prior to the event, the driver has hooked a chassis. After the event is completed, the driver brings the loaded container with chassis to another location to be unloaded, dropped, or dismounted. |
| mount-origin |
A driver arrives at a location that is the origin site of the shipment with a bare chassis and a loaded container is placed on top of it. Before the event the driver is expected to be pulling a bare chassis that can be mounted with the loaded container. After the event is completed the driver will bring the loaded container to a location where it will be unloaded, dropped, or dismounted. |
| pickup-crossdock |
A driver arrives at a location that is a cross-dock location in the system with a freight carrying piece of equipment that will be loaded at this location. The freight from several different shipments may be consolidated at this location. Before the event the driver is expected to be driving a freight carrying piece of equipment or a tractor pulling a trailer or container that can be loaded. After the event is completed, the driver will deliver the freight to final destinations. |
| pickup-origin |
A driver arrives at a location that matches the origin site on the shipment and has a freight carrying piece of equipment. At this location the driver adds freight and leaves. Before the event the driver has a freight carrying piece of equipment that can be loaded with the contents of the shipment. After the event is completed, the driver brings the equipment and freight to another location to delivered, dropped, or dismounted. |
| pickup-stopoff |
A driver is driving or pulling a freight carrying piece of equipment and picks up additional freight at a location that is not the origin site on the shipment. Before the event the driver has already obtained equipment that can be loaded with additional items. After the event is completed, the driver will continue bringing the load to additional locations. |
| scale-stopoff |
A driver brings the empty or loaded equipment to be weighed at a location that is not the origin nor destination of the shipment. Before the event the driver has obtained the equipment to be weighed. After the event is completed the driver brings the equipment to another location. |
Event Sites
Site locations, yard locations, and cross-dock locations should exist in the system and event types that can only happen at those locations must happen at those locations. IE cross-dock events should happen at cross-dock locations and yard events should happen at yard locations. The only exception to the rule is if a hook-chassis or drop-chassis can happen at a yard location as well as a site location.
Why We Validate Event Sites
Certain event types can only happen at certain location types and equipment needs to be tracked as it falls in and out of possession of the trucker. An application should not be able to set a location that the system does not know about.
Move Accept/Reject
A driver assigned to a pending move can accept or reject the pending move, but cannot accept or reject a move that is already in progress or completed.
Why We Validate Move Accept/Reject
More than one driver cannot work on a move at the same time, and a completed move cannot be worked on again.
Shipment Orgin/Destination
All shipments require moving equipment or freight from the origin site on the shipment to the destination site on the shipment.
Why We Validate Shipment Origin/Destination
An application cannot add, update, or remove events that would prevent the freight or equipment from being moved from the origin to the destination.
Shipment Status
A shipment that has been cancelled or declined will never have work performed by a driver to complete the shipment.
Why We Validate Shipment Status
An application should not be able to assign drivers or update data on a shipment that has been declined or rejected.
Street Turn
A shipment that has non-routed event types is expected to be street-turned, and the non-routed event types are place holders for events that will not be performed.
Why we Validate Street Turns
An application should not be able to mark events that will never be performed unless they are going to street turn equipment for reuse between an inbound and outbound shipment.