--- title: Ocean - Update Shipment slug: fourkites-api-reference/ocean-update-shipment icon: {"apiMethod":"PATCH"} createdAt: 2024-01-10T16:21:21.000Z --- :::hint{type="info"} For the Update Shipment documentation on load modes other than Ocean -- [refer here](https://docs.fourkites.com/api-reference/update-shipment). ::: 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. :::hint{type="info"} 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. ::: :::ApiMethodV2 ```json { "name": "Update Load", "method": "PATCH", "url": "https://tracking-api.fourkites.com/api/v1/tracking/", "description": "", "tab": "examples", "examples": { "languages": [ { "id": "BcXEwba08NgGuR3A2DTDr", "language": "curl", "code": "curl --location --request PATCH 'https://api.fourkites.com/api/v1/tracking/' \\\n--header 'Content-Type: application/json' \\\n--header 'apikey: REPLACE_KEY_VALUE' \\\n--data-raw '{\n \"load\": {\n \"loadNumber\": \"0083889134\",\n \"carrier\": \"MAEU\",\n \"shipper\": \"equipmentType\"\n },\n \"trackingInfo\": {\n \"truckNumber\": \"3\",\n \"containerNumber\": \"ABCD1234567\"\n },\n \"stops\": [\n {\n \"addressLine1\": \"500 West Madison Street\",\n \"addressLine2\": \"Floor 33\",\n \"city\": \"Chicago\",\n \"country\": \"US\",\n \"customer\": {\n \"id\": \"789789\",\n \"poNumbers\": [\n \"00210123OF-203503\"\n ],\n \"pointOfContact\": {\n \"alert\": false,\n \"email\": \"poc@test.com\",\n \"name\": \"John Doe\",\n \"phone\": \"+19999999999\"\n }\n },\n \"earliestAppointmentTime\": \"2021-11-11T01:00:00\",\n \"earliestWantTime\": \"2021-11-11T01:00:00\",\n \"externalAddressId\": \"100\",\n \"stopType\": \"PortOfLoading\"\n }\n ],\n \"simpleUpdate\": \"true\",\n \"simpleUpdateGlobalAddress\": \"true\"\n}'", "customLabel": "" }, { "id": "C6xZ5AbAm4dpOZk7surgc", "language": "java", "code": "OkHttpClient client = new OkHttpClient().newBuilder()\n .build();\nMediaType mediaType = MediaType.parse(\"application/json\");\nRequestBody body = RequestBody.create(mediaType, \"{\\n \\\"load\\\": {\\n \\\"loadNumber\\\": \\\"0083889134\\\",\\n \\\"carrier\\\": \\\"MAEU\\\",\\n \\\"shipper\\\": \\\"equipmentType\\\"\\n },\\n \\\"trackingInfo\\\": {\\n \\\"truckNumber\\\": \\\"3\\\",\\n \\\"containerNumber\\\": \\\"ABCD1234567\\\"\\n },\\n \\\"stops\\\": [\\n {\\n \\\"addressLine1\\\": \\\"500 West Madison Street\\\",\\n \\\"addressLine2\\\": \\\"Floor 33\\\",\\n \\\"city\\\": \\\"Chicago\\\",\\n \\\"country\\\": \\\"US\\\",\\n \\\"customer\\\": {\\n \\\"id\\\": \\\"789789\\\",\\n \\\"poNumbers\\\": [\\n \\\"00210123OF-203503\\\"\\n ],\\n \\\"pointOfContact\\\": {\\n \\\"alert\\\": false,\\n \\\"email\\\": \\\"poc@test.com\\\",\\n \\\"name\\\": \\\"John Doe\\\",\\n \\\"phone\\\": \\\"+19999999999\\\"\\n }\\n },\\n \\\"earliestAppointmentTime\\\": \\\"2021-11-11T01:00:00\\\",\\n \\\"earliestWantTime\\\": \\\"2021-11-11T01:00:00\\\",\\n \\\"externalAddressId\\\": \\\"100\\\",\\n \\\"stopType\\\": \\\"PortOfLoading\\\"\\n }\\n ],\\n \\\"simpleUpdate\\\": \\\"true\\\",\\n \\\"simpleUpdateGlobalAddress\\\": \\\"true\\\"\\n}\");\nRequest request = new Request.Builder()\n .url(\"\")\n .method(\"PATCH\", body)\n .addHeader(\"Content-Type\", \"application/json\")\n .build();\nResponse response = client.newCall(request).execute();", "customLabel": "" }, { "id": "ScqupUR2b01POzR4z6dVd", "language": "javascript", "code": "var settings = {\n \"url\": \"\",\n \"method\": \"PATCH\",\n \"timeout\": 0,\n \"headers\": {\n \"Content-Type\": \"application/json\"\n },\n \"data\": JSON.stringify({\n \"load\": {\n \"loadNumber\": \"0083889134\",\n \"carrier\": \"MAEU\",\n \"shipper\": \"equipmentType\"\n },\n \"trackingInfo\": {\n \"truckNumber\": \"3\",\n \"containerNumber\": \"ABCD1234567\"\n },\n \"stops\": [\n {\n \"addressLine1\": \"500 West Madison Street\",\n \"addressLine2\": \"Floor 33\",\n \"city\": \"Chicago\",\n \"country\": \"US\",\n \"customer\": {\n \"id\": \"789789\",\n \"poNumbers\": [\n \"00210123OF-203503\"\n ],\n \"pointOfContact\": {\n \"alert\": false,\n \"email\": \"poc@test.com\",\n \"name\": \"John Doe\",\n \"phone\": \"+19999999999\"\n }\n },\n \"earliestAppointmentTime\": \"2021-11-11T01:00:00\",\n \"earliestWantTime\": \"2021-11-11T01:00:00\",\n \"externalAddressId\": \"100\",\n \"stopType\": \"PortOfLoading\"\n }\n ],\n \"simpleUpdate\": \"true\",\n \"simpleUpdateGlobalAddress\": \"true\"\n }),\n};\n\n$.ajax(settings).done(function (response) {\n console.log(response);\n});", "customLabel": "" }, { "id": "EK1sxmEmmoJtvF_W2WOua", "language": "swift", "code": "import Foundation\n#if canImport(FoundationNetworking)\nimport FoundationNetworking\n#endif\n\nvar semaphore = DispatchSemaphore (value: 0)\n\nlet parameters = \"{\\n \\\"load\\\": {\\n \\\"loadNumber\\\": \\\"0083889134\\\",\\n \\\"carrier\\\": \\\"MAEU\\\",\\n \\\"shipper\\\": \\\"equipmentType\\\"\\n },\\n \\\"trackingInfo\\\": {\\n \\\"truckNumber\\\": \\\"3\\\",\\n \\\"containerNumber\\\": \\\"ABCD1234567\\\"\\n },\\n \\\"stops\\\": [\\n {\\n \\\"addressLine1\\\": \\\"500 West Madison Street\\\",\\n \\\"addressLine2\\\": \\\"Floor 33\\\",\\n \\\"city\\\": \\\"Chicago\\\",\\n \\\"country\\\": \\\"US\\\",\\n \\\"customer\\\": {\\n \\\"id\\\": \\\"789789\\\",\\n \\\"poNumbers\\\": [\\n \\\"00210123OF-203503\\\"\\n ],\\n \\\"pointOfContact\\\": {\\n \\\"alert\\\": false,\\n \\\"email\\\": \\\"poc@test.com\\\",\\n \\\"name\\\": \\\"John Doe\\\",\\n \\\"phone\\\": \\\"+19999999999\\\"\\n }\\n },\\n \\\"earliestAppointmentTime\\\": \\\"2021-11-11T01:00:00\\\",\\n \\\"earliestWantTime\\\": \\\"2021-11-11T01:00:00\\\",\\n \\\"externalAddressId\\\": \\\"100\\\",\\n \\\"stopType\\\": \\\"PortOfLoading\\\"\\n }\\n ],\\n \\\"simpleUpdate\\\": \\\"true\\\",\\n \\\"simpleUpdateGlobalAddress\\\": \\\"true\\\"\\n}\"\nlet postData = parameters.data(using: .utf8)\n\nvar request = URLRequest(url: URL(string: \"\")!,timeoutInterval: Double.infinity)\nrequest.addValue(\"application/json\", forHTTPHeaderField: \"Content-Type\")\n\nrequest.httpMethod = \"PATCH\"\nrequest.httpBody = postData\n\nlet task = URLSession.shared.dataTask(with: request) { data, response, error in \n guard let data = data else {\n print(String(describing: error))\n semaphore.signal()\n return\n }\n print(String(data: data, encoding: .utf8)!)\n semaphore.signal()\n}\n\ntask.resume()\nsemaphore.wait()\n", "customLabel": "" }, { "id": "ayUqbfQBGksrBP5w-wZrc", "language": "csharp", "code": "var client = new RestClient(\"\");\nclient.Timeout = -1;\nvar request = new RestRequest(Method.PATCH);\nrequest.AddHeader(\"Content-Type\", \"application/json\");\nvar body = @\"{\" + \"\\n\" +\n@\" \"\"load\"\": {\" + \"\\n\" +\n@\" \"\"loadNumber\"\": \"\"0083889134\"\",\" + \"\\n\" +\n@\" \"\"carrier\"\": \"\"MAEU\"\",\" + \"\\n\" +\n@\" \"\"shipper\"\": \"\"equipmentType\"\"\" + \"\\n\" +\n@\" },\" + \"\\n\" +\n@\" \"\"trackingInfo\"\": {\" + \"\\n\" +\n@\" \"\"truckNumber\"\": \"\"3\"\",\" + \"\\n\" +\n@\" \"\"containerNumber\"\": \"\"ABCD1234567\"\"\" + \"\\n\" +\n@\" },\" + \"\\n\" +\n@\" \"\"stops\"\": [\" + \"\\n\" +\n@\" {\" + \"\\n\" +\n@\" \"\"addressLine1\"\": \"\"500 West Madison Street\"\",\" + \"\\n\" +\n@\" \"\"addressLine2\"\": \"\"Floor 33\"\",\" + \"\\n\" +\n@\" \"\"city\"\": \"\"Chicago\"\",\" + \"\\n\" +\n@\" \"\"country\"\": \"\"US\"\",\" + \"\\n\" +\n@\" \"\"customer\"\": {\" + \"\\n\" +\n@\" \"\"id\"\": \"\"789789\"\",\" + \"\\n\" +\n@\" \"\"poNumbers\"\": [\" + \"\\n\" +\n@\" \"\"00210123OF-203503\"\"\" + \"\\n\" +\n@\" ],\" + \"\\n\" +\n@\" \"\"pointOfContact\"\": {\" + \"\\n\" +\n@\" \"\"alert\"\": false,\" + \"\\n\" +\n@\" \"\"email\"\": \"\"poc@test.com\"\",\" + \"\\n\" +\n@\" \"\"name\"\": \"\"John Doe\"\",\" + \"\\n\" +\n@\" \"\"phone\"\": \"\"+19999999999\"\"\" + \"\\n\" +\n@\" }\" + \"\\n\" +\n@\" },\" + \"\\n\" +\n@\" \"\"earliestAppointmentTime\"\": \"\"2021-11-11T01:00:00\"\",\" + \"\\n\" +\n@\" \"\"earliestWantTime\"\": \"\"2021-11-11T01:00:00\"\",\" + \"\\n\" +\n@\" \"\"externalAddressId\"\": \"\"100\"\",\" + \"\\n\" +\n@\" \"\"stopType\"\": \"\"PortOfLoading\"\"\" + \"\\n\" +\n@\" }\" + \"\\n\" +\n@\" ],\" + \"\\n\" +\n@\" \"\"simpleUpdate\"\": \"\"true\"\",\" + \"\\n\" +\n@\" \"\"simpleUpdateGlobalAddress\"\": \"\"true\"\"\" + \"\\n\" +\n@\"}\";\nrequest.AddParameter(\"application/json\", body, ParameterType.RequestBody);\nIRestResponse response = client.Execute(request);\nConsole.WriteLine(response.Content);", "customLabel": "" }, { "id": "9S9Qd-UfEOGOUaeAA340d", "language": "go", "code": "package main\n\nimport (\n \"fmt\"\n \"strings\"\n \"net/http\"\n \"io/ioutil\"\n)\n\nfunc main() {\n\n url := \"\"\n method := \"PATCH\"\n\n payload := strings.NewReader(`{\n \"load\": {\n \"loadNumber\": \"0083889134\",\n \"carrier\": \"MAEU\",\n \"shipper\": \"equipmentType\"\n },\n \"trackingInfo\": {\n \"truckNumber\": \"3\",\n \"containerNumber\": \"ABCD1234567\"\n },\n \"stops\": [\n {\n \"addressLine1\": \"500 West Madison Street\",\n \"addressLine2\": \"Floor 33\",\n \"city\": \"Chicago\",\n \"country\": \"US\",\n \"customer\": {\n \"id\": \"789789\",\n \"poNumbers\": [\n \"00210123OF-203503\"\n ],\n \"pointOfContact\": {\n \"alert\": false,\n \"email\": \"poc@test.com\",\n \"name\": \"John Doe\",\n \"phone\": \"+19999999999\"\n }\n },\n \"earliestAppointmentTime\": \"2021-11-11T01:00:00\",\n \"earliestWantTime\": \"2021-11-11T01:00:00\",\n \"externalAddressId\": \"100\",\n \"stopType\": \"PortOfLoading\"\n }\n ],\n \"simpleUpdate\": \"true\",\n \"simpleUpdateGlobalAddress\": \"true\"\n}`)\n\n client := &http.Client {\n }\n req, err := http.NewRequest(method, url, payload)\n\n if err != nil {\n fmt.Println(err)\n return\n }\n req.Header.Add(\"Content-Type\", \"application/json\")\n\n res, err := client.Do(req)\n if err != nil {\n fmt.Println(err)\n return\n }\n defer res.Body.Close()\n\n body, err := ioutil.ReadAll(res.Body)\n if err != nil {\n fmt.Println(err)\n return\n }\n fmt.Println(string(body))\n}", "customLabel": "" }, { "id": "dfSQD_rkszwaKVwt90Sm0", "language": "ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"\")\n\nhttp = Net::HTTP.new(url.host, url.port);\nrequest = Net::HTTP::Patch.new(url)\nrequest[\"Content-Type\"] = \"application/json\"\nrequest.body = JSON.dump({\n \"load\": {\n \"loadNumber\": \"0083889134\",\n \"carrier\": \"MAEU\",\n \"shipper\": \"equipmentType\"\n },\n \"trackingInfo\": {\n \"truckNumber\": \"3\",\n \"containerNumber\": \"ABCD1234567\"\n },\n \"stops\": [\n {\n \"addressLine1\": \"500 West Madison Street\",\n \"addressLine2\": \"Floor 33\",\n \"city\": \"Chicago\",\n \"country\": \"US\",\n \"customer\": {\n \"id\": \"789789\",\n \"poNumbers\": [\n \"00210123OF-203503\"\n ],\n \"pointOfContact\": {\n \"alert\": false,\n \"email\": \"poc@test.com\",\n \"name\": \"John Doe\",\n \"phone\": \"+19999999999\"\n }\n },\n \"earliestAppointmentTime\": \"2021-11-11T01:00:00\",\n \"earliestWantTime\": \"2021-11-11T01:00:00\",\n \"externalAddressId\": \"100\",\n \"stopType\": \"PortOfLoading\"\n }\n ],\n \"simpleUpdate\": \"true\",\n \"simpleUpdateGlobalAddress\": \"true\"\n})\n\nresponse = http.request(request)\nputs response.read_body\n", "customLabel": "" }, { "id": "HpK_PetONBRxgIWmMmgDX", "language": "python", "code": "import http.client\nimport json\n\nconn = http.client.HTTPSConnection(\"\")\npayload = json.dumps({\n \"load\": {\n \"loadNumber\": \"0083889134\",\n \"carrier\": \"MAEU\",\n \"shipper\": \"equipmentType\"\n },\n \"trackingInfo\": {\n \"truckNumber\": \"3\",\n \"containerNumber\": \"ABCD1234567\"\n },\n \"stops\": [\n {\n \"addressLine1\": \"500 West Madison Street\",\n \"addressLine2\": \"Floor 33\",\n \"city\": \"Chicago\",\n \"country\": \"US\",\n \"customer\": {\n \"id\": \"789789\",\n \"poNumbers\": [\n \"00210123OF-203503\"\n ],\n \"pointOfContact\": {\n \"alert\": False,\n \"email\": \"poc@test.com\",\n \"name\": \"John Doe\",\n \"phone\": \"+19999999999\"\n }\n },\n \"earliestAppointmentTime\": \"2021-11-11T01:00:00\",\n \"earliestWantTime\": \"2021-11-11T01:00:00\",\n \"externalAddressId\": \"100\",\n \"stopType\": \"PortOfLoading\"\n }\n ],\n \"simpleUpdate\": \"true\",\n \"simpleUpdateGlobalAddress\": \"true\"\n})\nheaders = {\n 'Content-Type': 'application/json'\n}\nconn.request(\"PATCH\", \"/\", payload, headers)\nres = conn.getresponse()\ndata = res.read()\nprint(data.decode(\"utf-8\"))", "customLabel": "" } ], "selectedLanguageId": "BcXEwba08NgGuR3A2DTDr" }, "results": { "languages": [ { "id": "10rRgfayEsKnd-jU_Cw2u", "language": "200", "customLabel": "", "code": "{\n \"message\": \"Load updated successfully\",\n \"statusCode\": 200\n}" } ], "selectedLanguageId": "10rRgfayEsKnd-jU_Cw2u" }, "request": { "pathParameters": [], "queryParameters": [], "headerParameters": [], "bodyDataParameters": [], "formDataParameters": [] }, "currentNewParameter": { "label": "Body Parameter", "value": "bodyDataParameters" }, "hasTryItOut": false, "autoGeneratedAnchorSlug": "update-load", "legacyHash": "vmLPghVBfIJcZl2ExR2vC" } ``` ::: ```json { "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": "poc@test.com", "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.   ```json { "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": "poc@test.com", "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" } ```