Recommended Callback Mapping for Ocean

27 min

This document offers guidance and recommendations on mapping callbacks for ocean loads

Stop Addition Logic on Ocean Loads based on Carrier Data:

FourKites creates the following stops dynamically (refer table below), as and when they become available on the carrier data

With the inclusion of each of the stops listed below, the sequence of all stops in the load is updated. In other words, the stop sequence dynamically changes within the load

Avoid using StopSequence field as an identifier for a stop, as it may change with carrier data updates. Instead, utilize StopType values for more consistent mapping

StopType	Description of the stop	When are these stops added to the load?
empty_pickup_location	Location from where the empty equipment is made available to the shipper for stuffing	On receipt of the “Empty Equipment Dispatched” milestone
place_of_receipt	Location where the carrier’s responsibility for the container commences.	On receipt of tracking data from the carrier
transhipment_port	Intermediate port where container is transferred from one vessel to another during a journey between its Port of Loading and Port of Discharge	Mainly upon receiving tracking data from the carrier, although in certain instances, transshipment stops are added in response to events occurring at those specific locations
place_of_delivery	Location where the carrier’s responsibility for the container concludes.	On receipt of tracking data from the carrier
empty_return_location	Location from where the empty container is returned to the carrier after de-stuffing	On receipt of the “Return Container” milestone

Recommended Callback Mapping for Ocean

The following are the recommended callbacks based on the customer’s use case for Ocean loads.

Use Case	Recommended Callbacks	Recommended Mapping
Stop Creation/Updation/Deletion	Stop Amend callbacks include CREATE, UPDATE and DELETE action messages * Note: StopUnlocode will NOT be populated for the following stop types --> pickup, delivery	- Associate the following StopType field’s to retrieve the respective stop's updates

List of all possible StopTypes

port_of_loading

port_of_discharge

transhipment_port (depends on the routing)

place_of_receipt (depends on the routing)

place_of_delivery (depends on the routing)

empty_pickup_location

empty_return_location

pickup (if provided by shipper)

delivery (if provided by shipper) | | Event updates | 1. OCEAN_UPDATE

STOP_ARRIVAL

STOP_DEPARTURE | - Empty Equipment Dispatched → OCEAN_UPDATE callback AND StatusCode “EE”

Place of Receipt Gate-In

Priority 1 → STOP_ARRIVAL callback AND StopType “place_of_receipt” (or)

Priority 2 → OCEAN_UPDATE callback AND StatusCode “CO” (or) “II” AND StopType “place_of_receipt”

Place of Receipt Departure

Priority 1 → STOP_DEPARTURE callback AND StopType “place_of_receipt”

STOP_DEPARTURE callback can have updates upon receipt of higher priority milestone from the carrier

Priority 2 → OCEAN_UPDATE callback AND StatusCode “RL” > “AL” (or) “BD” > “AO” (or) “FD” > “AP” (or) “P” AND StopType “place_of_receipt”

Port of Loading Gate-In

Priority 1 → STOP_ARRIVAL callback AND StopType “port_of_loading” (or)

Priority 2 → OCEAN_UPDATE callback AND StatusCode “I” AND StopType “port_of_loading”

Loading at Port of Loading → OCEAN_UPDATE callback AND StatusCode “AE” AND StopType “port_of_loading”

Port of Loading Departure

Priority 1 → STOP_DEPARTURE callback AND StopType “port_of_loading”

STOP_DEPARTURE callback can have updates upon receipt of higher priority milestone from the carrier

Priority 2 → OCEAN_UPDATE callback AND StatusCode “VD” AND StopType “port_of_loading”

Port of Discharge Arrival

Priority 1 → STOP_ARRIVAL callback AND StopType “port_of_discharge”

**STOP_ARRIVAL callback can have updates upon receipt of higher priority milestone from the carrier

Priority 2 → OCEAN_UPDATE callback AND StatusCode “VA” AND StopType “port_of_discharge”

Discharge at Port of Discharge → OCEAN_UPDATE callback AND StatusCode “UV” AND StopType “port_of_discharge”

Port of Discharge Gate-Out → OCEAN_UPDATE callback AND StatusCode “OA” AND StopType “port_of_discharge”

Place of Delivery Arrival

Priority 1 → STOP_ARRIVAL callback AND StopType “place_of_delivery”

STOP_ARRIVAL callback can have updates upon receipt of higher priority milestone from the carrier

Priority 2 → OCEAN_UPDATE callback AND StatusCode “AR” > “UR” (or) “AB” > “UB” (or) “FA” > “UF” (or) “A” AND StopType “place_of_delivery”

Place of Delivery Gate-Out

Priority 1 → STOP_DEPARTURE callback AND StopType “place_of_delivery” (or)

Priority 2 → OCEAN_UPDATE callback AND StatusCode “IOA” AND StopType “place_of_delivery”

Empty Return → OCEAN_UPDATE callback AND StatusCode “RD” | | ETA & ETD | For ETA → STOP_ETA_UPDATED For ETD → STOP_ETD_UPDATED - Note: StopUnlocode will NOT be populated for the following stop types --> pickup, delivery | * Associate the StopType field to retrieve and utilize the respective stop's Estimated Time of Arrival (ETA)

ETA’s are commonly available for the following StopType’s

transhipment_port

port_of_discharge

place_of_delivery

delivery

Associate the StopType field to retrieve and utilize the respective stop's Estimated Time of Departure (ETD)

ETD’s are commonly available for the following StopType’s

place_of_receipt

port_of_loading

transhipment_port

port_of_discharge (Estimated Out-gate) |

Note: Ocean Load specific EncryptedURL will be sent only for the following list of callbacks:

Load Creation

Load Updation

Stop Created

Stop Updated

Stop Deleted

Note: If you want the StopReferenceNumbers & EncryptedURL to be sent in callbacks, you need to have the Stop Reference Numbers & Encrypted URL feature flags enabled.