Stop ETD Update
When the ETD for a port (Ocean Load) changes by more than 15 minutes, the following notification will be POSTed to the callback URL.
Note: The stop ETD callbacks pertain to the ETD’s displayed at the individual stop level. In other words, separate callbacks are triggered for the ETD applied to each stop within a load
Note: Following the initial ETD for a stop, subsequent callbacks are triggered only if the ETD changes beyond a predefined threshold. This threshold can range between 5 to 720 minutes, indicating the minimum and maximum allowable changes triggering a callback. The default threshold is 15 minutes. The threshold can be configured from “ETD Change Frequency” field of the Webhooks configuration
- By default, this callback furnishes the FourKites calculated ETD for a specified stop
- If you desire to receive both the Carrier ETD and the FourKites calculated ETD for a specific stop within this callback, this can be enabled via the callback configurations in the Company Settings, as well as through the FK Connect Webhook Configuration
- The "CarrierETD" parameter will be shown in the callback message as given in the sample payload below.
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. Refer to Recommended Callback Mapping for more context.
Vessel and Voyage Data in Callbacks
The vessel and voyage details shown in callbacks represent the current active vessel/voyage on the load at the time of the callback, not necessarily the vessel for the specific leg being updated.
Why This Matters
When we send ETA/ETD updates, we do not include vessel and voyage details because they may be inaccurate for the specific leg being updated.
Example Scenario:
- Route: Port of Loading (PoL) → Transshipment Port (TSP) → Port of Discharge (PoD)
- If Leg 1 (PoL → TSP) is currently active and we send an ETA update for the PoD
- The callback would show Leg 1's vessel details, even though the ETA update is for Leg 2 (TSP → PoD)
Recommended Approach
Update vessel names in your TMS based on actual vessel events such as:
- Loaded on vessel
- Vessel departure
- Avoid updating based on ETA/ETD callbacks (vessel rollovers may occur)
This ensures your system maintains accurate vessel information aligned with actual operational events rather than potentially outdated callback data.
{
"BillofLading": "bill_of_lading",
"BookingNumber": "booking_number",
"CarrierETD": "2022-08-15T07:08:44+08:00",
"ContainerNumber":"BEAU5912889",
"ContainerType": "40FT",
"FourKitesLoadId": 1234,
"IMO": "9945837",
"LoadNumber": "BOL12345",
"MessageType": "STOP_ETD_UPDATED",
"ProNumber": "",
"ReferenceNumbers": ["ref1", "ref2"],
"Scac": "ONEY",
"Shipper": "test-shipper",
"StopName": "ABC Stop",
"StopReferenceId": "1",
"StopSequence": 2,
"StopStatus": "on_track",
"StopType": "delivery",
"StopUnlocode": "NLRTM",
"Tags": ["tag1", "tag2"],
"TerminalName": "ECT DELTA TERMINAL",
"Timestamp": "2015-10-01T16:00:00-05:00",
"Timezone": "America/New_York",
"TimezoneShortName": "EST",
"TimezoneOffset" : -1800,
"VesselName": "ONE ORPHEUS",
"VoyageNumber": "069W"
}Field Definitions
Field Name | Data Type | Description | Expected Values | Conditions for this to be available | Nullable Field? |
|---|---|---|---|---|---|
BillofLading | String | It indicates the bill of lading associated with the load | Bill of lading reference | Load should have a Bill Of Lading populated This typically is provided by the shipper | Yes |
BookingNumber | String | It indicates the shipping line's booking number | Booking Number reference | Load should have a Booking Number populated This typically is provided by the shipper | Yes |
CarrierETD | String | It indicates the last updated Carrier ETD for the load | - Timestamp format will be the following: "2006-01-02T15:04:05-07:00" | Default ISO8601 format |
- If there is no Carrier ETD received for that stop, the value would be blank | Timestamp will be in stop's local time Carrier ETD will be applicable for the below StopTypes - place_of_receipt
- port_of_loading
- transhipment_port
- port_of_discharge (not common) | Yes | | ContainerNumber | String | Container Number of the Ocean load | Container Number | Load should have a Container Number populated | Yes | | ContainerType | String | It indicates whether the container is a general, high cube, Reefer, etc. | 20 20 Reefer 40 40HC 40HC Reefer 45 45HC 48 53 55 60 | 1. Load should have a Container Number populated
- Container type info provided by the carrier source data | Yes | | FourKitesLoadId | String | Unique load identifier from the FourKites system | | | No | | IMO | String | International Maritime Organization number specific the the vessel assigned to the shipment | 9845679 | Whenever there is a Vessel data available. Populated for all four vessel related status codes: AE, VD, VA, & UV | No | | LoadNumber | String | Unique shipment identifier from shipper's system | | - Provided by shipper (or)
- Container number is used as the load number When utilising the Easy Load Create option, the container number is used as the load number by default, unless a specific load number is explicitly provided by the shipper When utilising the Automatically Create Load using EDI 315 option, the container number is used as the load number | No | | MessageType | String | Indicates the type of the message | STOP_ETD_UPDATED | | No | | ProNumber | String | PRO# found on the ocean load | PRO number provided by the customer for a given load | As provided by customer, else “null” | Yes | | ReferenceNumbers | Array | List of additional reference numbers associated with the load (empty list when no reference numbers are associated with the load) | Reference numbers provided by the customer for a given load | As provided by customer, else will be an empty array | Yes | | Scac | String | SCAC of the carrier assigned to the shipment/load | * SCAC code of the carrier on the load (or)
- If there are managing/operating carrier setup, this would be the SCAC code of the managing carrier on the load | | No | | Shipper | String | Unique shipper ID from FourKites | | | No | | StopName | String | Name of the stop as provided by the customer (or) carrier | The Stop Name will be sourced from the customer; if no specific stop name is provided, the carrier-provided location name will be used. In the absence of a location name within the carrier data, the UNLOCODE of the stop will be utilized | | No | | StopReferenceId | String | It is the unique identifier of the stop from the customer's system. This populates the "Reference #" field on the stop and is used to indicate which stop an update is applied to. | Customer provided ID for a given stop | | No | | StopSequence | Integer | The sequence of the stop on the load, for which the ETA update callback is being triggered | 1, 2, 3 etc. | Avoid using StopSequence field as an identifier for a stop, as it may change with carrier data updates | No | | StopStatus | String | Status of the stop | - on_track
- delayed
- not_tracking
- at_facility
- completed | | No | | StopType | String | Indicator for the type of the stop | * place_of_receipt
- port_of_loading
- transhipment_port
- port_of_discharge | | No | | StopUnlocode | String | It indicates the UNLOCODE of the stop | UNLOCODE (United Nations Code for Trade and Transport Locations) follows a specific format consisting of a two-letter country code and a three-character location code, eg: BEANR | If the location is not available in FourKites' address master in specific instances, the payload will lack the UNLOCODE key | Yes | | Tags | Array | List of tags associated with the load (empty list when tags are not present) | Tags provided by the customer for a given load | As provided by customer, else will be an empty array | Yes | | TerminalName | String | It indicates the terminal inside a port where the vessel is berthing (terminal name tied to a stop) | Name of the terminal | Applicable for messages tied to following stoptypes * port_of_loading
- transhipment_port
- port_of_discharge | Yes | | Timestamp | String | This is the Estimated Time of Departure (ETD) for the given stop This is the FourKites calculated ETD | Timestamp format will be the following: "2006-01-02T15:04:05-07:00" | Default ISO8601 format. | Timestamp will be in stop's local time | No | | Timezone | String | Timezone of the stop | Example: “America/New_York”, “Etc/UTC” Refer to this article for the list of timezones. | The timezone of the stop's location | No | | TimezoneShortName | String | Short name of Timezone of the stop in which "Timestamp" is specified | Example: “CET”, “KST” If the short name is unavailable, the value will represent the timezone offset in hours, such as “+03” “+08” etc. | | No | | TimezoneOffset | Integer | It indicates the difference between local time and UTC in seconds | Example: “-18000”, “0” | | No | | VesselName | String | It indicates the name of the vessel carrying the load. | Free Text | - The VesselName field pertains to the currently active vessel assigned to the load. If there is no vessel assigned on the load, this field will be “null”
- If transshipment stops are part of the routing, this value will vary based on the active voyage leg
- Info provided by carrier | Yes | | VoyageNumber | String | It indicates the unique identifier given for the voyage. | Free Text | * The VoyageNumber field pertains to the currently active vessel assigned to the load. If there is no vessel assigned on the load, this field will be “null”
- If transshipment stops are part of the routing, this value will vary based on the active voyage leg
- Info provided by carrier | Yes |
ETD Change Frequency
By default, FourKites sends the ETD Update callback each time the ETD changes by 15 minutes or more. If you wish to change this (ETD Change Frequency), contact your CSM/SC. The minimum and maximum values that can be set are 5 minutes and 720 minutes respectively.
The callback will be sent only if both the following conditions are satisfied:
- The change in ETD is more than the ETD Change Frequency.
- The time between the last sent Stop ETD Update callback and the current time when the ETD changes is equal to or more than the set ETD Update Frequency.
Note: Please get in touch with your CSM at FourKites to customize the ETD Update and Change Frequencies for your company