--- title: Recommended Callback Mapping for Ocean slug: fourkites-api-reference/recommended-callback-mapping-for-ocean createdAt: 2024-01-05T06:16:10.000Z --- 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 :::hint{type="danger"} 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 2. STOP\_ARRIVAL 3. 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) | :::hint{type="info"} **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 ::: :::hint{type="info"} **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. :::