Ocean - Update Shipment
For the Update Shipment documentation on load modes other than Ocean -- refer here.
Allows authorized users to update an Ocean load. Please note, you will need to use the FourKites’ Internal Tracking ID, “loadId”, that was returned in the response from the Load Create API request.
Query Parameters
Name | Validation | Description |
|---|---|---|
simpleUpdate | Valid values: true or false. Default to false. | Indicates whether the load object in the request payload is the complete snapshot of the load to be updated. Default to false. |
SimpleUpdateGlobalAddress | Valid values: true or false. Default to false. | To perform a simple update of port stops (PortOfLoading and PortOfDischarge) on Ocean loads. |
Creating Ocean Loads
Required Data Points
The following fields are required to create/update a port-to-port load in FourKites:
- loadNumber: Unique load identifier from shipper's system. The load Number is an important piece of information used to link the load with truck information received from the Carrier's TMS
- carrier: SCAC or Service Provider ID of the carrier or shipping line assigned to the load
- externalAddressId: POL and POD’s 5-character UNLOCODE. FourKites uses this code to geocode the exact location of the port
- Note: While POL/POD UNLOCODES are preferred, City/Country or Lat/Long will be sufficient if the load creator does not have the port UNLOCODEs
- containerNumber: The 11-digit container number which holds the load. Typically, this is composed of a 4-character alpha prefix and a 7-digit numeric sequence. e.g. ABCD1234567, where the 7th digit is known as the container check digit. *Field is Mandatory for shippers who intend to track FCL shipments. For some shippers that intend to track LCL, we can substitute the container requirement for an alternative reference, such as booking or bill of lading.
- stopType: Denotes the type of stop. Depending upon the legs of the journey being tracked, this can be a mix of the following: pickup, portOfLoading, portOfDischarge, delivery. The stop type is how FourKites will be able to convert the mode in FourKites as an ocean load.
Request Format
The first JSON sample is for a Load Update that contains the query parameter simpleUpdate=true. When this query parameter is included and set to true, FourKites expects a complete snapshot of the shipment. In other words, the load details in the JSON will completely replace the existing load details. Similarly, you can if you use simpleUpdateGlobalAddress=true, the port stops will be updated.
Note that tags associated with address records that are applied to the load as a result of the address being used for a stop on the load will not be replaced; instead, tags in the JSON will simply be added to these existing tags.
curl --location --request PATCH 'https://api.fourkites.com/api/v1/tracking/' \
--header 'Content-Type: application/json' \
--header 'apikey: REPLACE_KEY_VALUE' \
--data-raw '{
"load": {
"loadNumber": "0083889134",
"carrier": "MAEU",
"shipper": "equipmentType"
},
"trackingInfo": {
"truckNumber": "3",
"containerNumber": "ABCD1234567"
},
"stops": [
{
"addressLine1": "500 West Madison Street",
"addressLine2": "Floor 33",
"city": "Chicago",
"country": "US",
"customer": {
"id": "789789",
"poNumbers": [
"00210123OF-203503"
],
"pointOfContact": {
"alert": false,
"email": "[email protected]",
"name": "John Doe",
"phone": "+19999999999"
}
},
"earliestAppointmentTime": "2021-11-11T01:00:00",
"earliestWantTime": "2021-11-11T01:00:00",
"externalAddressId": "100",
"stopType": "PortOfLoading"
}
],
"simpleUpdate": "true",
"simpleUpdateGlobalAddress": "true"
}'{
"load": {
"loadNumber": "0083889134",
"carrier": "MAEU",
"shipper": "equipmentType"
},
"trackingInfo": {
"truckNumber": "3",
"containerNumber": "ABCD1234567"
},
"stops": [
{
"addressLine1": "500 West Madison Street",
"addressLine2": "Floor 33",
"city": "Chicago",
"country": "US",
"customer": {
"id": "789789",
"poNumbers": [
"00210123OF-203503"
],
"pointOfContact": {
"alert": false,
"email": "[email protected]",
"name": "John Doe",
"phone": "+19999999999"
}
},
"earliestAppointmentTime": "2021-11-11T01:00:00",
"earliestWantTime": "2021-11-11T01:00:00",
"externalAddressId": "100",
"stopType": "PortOfLoading"
}
],
"simpleUpdate": "true",
"simpleUpdateGlobalAddress": "true"
}The second JSON sample is for a Load Update that does not contain the query parameter simpleUpdate=false. In this case, only the load details passed in the JSON will replace those load details in the existing load and the rest will remain as is. Similarly, you can if you use simpleUpdateGlobalAddress=false, the port stops will remain as is.
{
"load": {
"loadNumber": "0083889134",
"carrier": "MAEU",
"shipper": "equipmentType"
},
"trackingInfo": {
"truckNumber": "3",
"containerNumber": "ABCD1234567"
},
"stops": [
{
"addressLine1": "500 West Madison Street",
"addressLine2": "Floor 33",
"city": "Chicago",
"country": "US",
"customer": {
"id": "789789",
"poNumbers": [
"00210123OF-203503"
],
"pointOfContact": {
"alert": false,
"email": "[email protected]",
"name": "John Doe",
"phone": "+19999999999"
}
},
"earliestAppointmentTime": "2021-11-11T01:00:00",
"earliestWantTime": "2021-11-11T01:00:00",
"externalAddressId": "100",
"stopType": "PortOfLoading"
}
],
"simpleUpdate": "false",
"simpleUpdateGlobalAddress": "false"
}