Last updated

Update a Vessel Shipment

Update an existing shipment in project44’s network using the following API.

Update a Vessel Shipment with Transshipment Port

To update an existing vessel shipment with a transshipment port, you can modify the same payload that you used to create the shipment. If the payload that you used during creation is not available, then you can first get the current shipment details using the GET API /api/v4/shipments/{shipmentId}/tracking/history and then prepare the request payload as described below. You need to add the following to prepare the request payload:

  • Add the master shipment ID in the id field (this is the id returned during shipment creation).
  • Add a new stop of type TRANSSHIPMENT_PORT with location information.
  • Update the routeSegments array to include the new transshipment port with the required vessel identifiers in the identifiers array.
  • Update the events arrays to include the new events related to the transshipment port, such as ARRIVAL_AT_STOP and DEPARTURE_FROM_STOP.

Workflow

Complete these steps:

  1. Prepare a PUT request to /api/v4/shipments/tracking
  2. Include the shipment id and updated stops, routeSegments, and events in the payload as described above.

For example, if you want to add a new TRANSSHIPMENT_PORT to an existing shipment created with id 2b1911da-d58c-4f1a-8c6b-55dc1e06df39, see the below schema.

JSON
{
  "id": "2b1911da-d58c-4f1a-8c6b-55dc1e06df39",
  "identifiers": [
    {
      "type": "CUSTOMER_REFERENCE",
      "value": "REF-123456"
    }
  ],
  "attributes": [
    {
      "name": "Cargo Type",
      "values": [
        "Electronics"
      ]
    },
    {
      "name": "Special Handling",
      "values": [
        "Fragile"
      ]
    }
  ],
  "plan": {
    "expectedTransportationModes": [
      "OCEAN"
    ],
    "vesselTracking": {
      "enabled": "true"
    }
  },
  "routeInfo": {
    "stops": [
      {
        "id": "f1246a3e-322f-492b-9b7f-d5dccad0d232",
        "type": "PORT_OF_LOADING",
        "location": {
          "identifiers": [
            {
              "type": "PORT_UN_LOCODE",
              "value": "USNYC"
            }
          ]
        }
      },
      {
        "id": "a6e27d7d-f2cd-3052-81d8-2cb33753cd99",
        "type": "TRANSSHIPMENT_PORT",
        "location":
        {
            "identifiers":
            [
                {
                    "type": "PORT_UN_LOCODE",
                    "value": "BEANR"
                }
            ]
        }
      },
      {
        "id": "f7aab7ac-e3b0-4d21-b935-3a3ea64e0f4d",
        "type": "PORT_OF_DISCHARGE",
        "location": {
          "identifiers": [
            {
              "type": "PORT_UN_LOCODE",
              "value": "USLAX"
            }
          ]
        }
      }
    ],
    "routeSegments": [
      {
        "id": "2e332c4b-1846-4e75-bfd2-cb7ac978b220",
        "fromStopId": "f1246a3e-322f-492b-9b7f-d5dccad0d232",
        "toStopId": "a6e27d7d-f2cd-3052-81d8-2cb33753cd99",
        "transportationMode": "BARGE",
        "identifiers": [
          {
            "type": "VESSEL_IMO",
            "value": "9729104"
          }
        ]
      },
      {
        "id": "5e183d59-ae9c-3623-bd4d-ab83e7ae8cf3",
        "fromStopId": "a6e27d7d-f2cd-3052-81d8-2cb33753cd99",
        "toStopId": "f7aab7ac-e3b0-4d21-b935-3a3ea64e0f4d",
        "transportationMode": "BARGE",
        "identifiers": [
          {
            "type": "VESSEL_IMO",
            "value": "9809826"
          }
        ]
      }
    ]
  },
  "events": [
    {
      "plannedDateTime": "2025-07-10T17:30:29+0000",
      "plannedEndDateTime": "2025-07-11T12:30:29+0000",
      "type": "DEPARTURE_FROM_STOP",
      "stopId": "f1246a3e-322f-492b-9b7f-d5dccad0d232",
      "routeSegmentId": "2e332c4b-1846-4e75-bfd2-cb7ac978b220"
    },
    {
      "plannedDateTime": "2025-07-12T17:30:29+0000",
      "plannedEndDateTime": "2025-07-13T12:30:29+0000",
      "type": "ARRIVAL_AT_STOP",
      "stopId": "a6e27d7d-f2cd-3052-81d8-2cb33753cd99",
      "routeSegmentId": "2e332c4b-1846-4e75-bfd2-cb7ac978b220"
    },
    {
      "plannedDateTime": "2025-07-13T17:30:29+0000",
      "plannedEndDateTime": "2025-07-14T12:30:29+0000",
      "type": "DEPARTURE_FROM_STOP",
      "stopId": "a6e27d7d-f2cd-3052-81d8-2cb33753cd99",
      "routeSegmentId": "5e183d59-ae9c-3623-bd4d-ab83e7ae8cf3"
    },
    {
      "plannedDateTime": "2025-07-14T15:30:29+0000",
      "plannedEndDateTime": "2025-07-15T10:30:29+0000",
      "type": "ARRIVAL_AT_STOP",
      "stopId": "f7aab7ac-e3b0-4d21-b935-3a3ea64e0f4d",
      "routeSegmentId": "5e183d59-ae9c-3623-bd4d-ab83e7ae8cf3"
    }
  ]
}
  1. Send the request.

Expected Response

You have successfully submitted the request when you receive a 200 OK response. Here is a sample of the minimum response schema:

{
  "id": "eb0edc03-8078-48bf-bc0c-d2b6ceb7e631",
  "createdDateTime": "2025-07-31T10:06:46+0000",
  "identifiers": [
    {
      "type": "CUSTOMER_REFERENCE",
      "value": "REF-123456"
    }
  ],
  "shipmentShareLink": "https://movement.project44.com/share/976758b4-1185-4c8b-b55d-cb88dac8591b",
  "lastModifiedDateTime": "2025-07-31T10:06:46+0000",
  "plan": {
    "expectedTransportationModes": [
      "OCEAN"
    ],
    "vesselTracking": {
      "enabled": true
    }
  },
  "routeInfo": {
    "stops": [
      {
        "id": "f1246a3e-322f-492b-9b7f-d5dccad0d232",
        "type": "PORT_OF_LOADING",
        "location": {
          "identifiers": [
            {
              "type": "PORT_UN_LOCODE",
              "value": "USNYC"
            }
          ]
        }
      },
      {
        "id": "a6e27d7d-f2cd-3052-81d8-2cb33753cd99",
        "type": "TRANSSHIPMENT_PORT",
        "location":
        {
            "identifiers":
            [
                {
                    "type": "PORT_UN_LOCODE",
                    "value": "BEANR"
                }
            ]
        }
      },
      {
        "id": "f7aab7ac-e3b0-4d21-b935-3a3ea64e0f4d",
        "type": "PORT_OF_DISCHARGE",
        "location": {
          "identifiers": [
            {
              "type": "PORT_UN_LOCODE",
              "value": "USLAX"
            }
          ]
        }
      }
    ],
    "routeSegments": [
      {
        "id": "2e332c4b-1846-4e75-bfd2-cb7ac978b220",
        "fromStopId": "f1246a3e-322f-492b-9b7f-d5dccad0d232",
        "toStopId": "a6e27d7d-f2cd-3052-81d8-2cb33753cd99",
        "transportationMode": "BARGE",
        "identifiers": [
          {
            "type": "VESSEL_IMO",
            "value": "9729104"
          }
        ]
      },
      {
        "id": "5e183d59-ae9c-3623-bd4d-ab83e7ae8cf3",
        "fromStopId": "a6e27d7d-f2cd-3052-81d8-2cb33753cd99",
        "toStopId": "f7aab7ac-e3b0-4d21-b935-3a3ea64e0f4d",
        "transportationMode": "BARGE",
        "identifiers": [
          {
            "type": "VESSEL_IMO",
            "value": "9809826"
          }
        ]
      }
    ]
  },
  "events": [
    {
      "receivedDateTime": "2025-07-31T10:06:46+0000",
      "plannedDateTime": "2025-07-10T17:30:29+0000",
      "plannedEndDateTime": "2025-07-11T12:30:29+0000",
      "type": "DEPARTURE_FROM_STOP",
      "stopId": "f1246a3e-322f-492b-9b7f-d5dccad0d232",
      "routeSegmentId": "2e332c4b-1846-4e75-bfd2-cb7ac978b220"
    },
    {
      "receivedDateTime": "2025-07-31T10:06:46+0000",
      "plannedDateTime": "2025-07-12T17:30:29+0000",
      "plannedEndDateTime": "2025-07-13T12:30:29+0000",
      "type": "ARRIVAL_AT_STOP",
      "stopId": "a6e27d7d-f2cd-3052-81d8-2cb33753cd99",
      "routeSegmentId": "2e332c4b-1846-4e75-bfd2-cb7ac978b220"
    },
    {
      "receivedDateTime": "2025-07-31T10:06:46+0000",
      "plannedDateTime": "2025-07-13T17:30:29+0000",
      "plannedEndDateTime": "2025-07-14T12:30:29+0000",
      "type": "DEPARTURE_FROM_STOP",
      "stopId": "a6e27d7d-f2cd-3052-81d8-2cb33753cd99",
      "routeSegmentId": "5e183d59-ae9c-3623-bd4d-ab83e7ae8cf3"
    },
    {
      "receivedDateTime": "2025-07-31T10:06:46+0000",
      "plannedDateTime": "2025-07-14T15:30:29+0000",
      "plannedEndDateTime": "2025-07-15T10:30:29+0000",
      "type": "ARRIVAL_AT_STOP",
      "stopId": "f7aab7ac-e3b0-4d21-b935-3a3ea64e0f4d",
      "routeSegmentId": "5e183d59-ae9c-3623-bd4d-ab83e7ae8cf3"
    }
  ]
}

This is an example of what could be returned in the response. Null fields will not show up in the response. Please refer to the reference data for more information on required and potential null fields.

Errors

If there was a problem with your request, you will receive one of the following error codes:

  • 400 Invalid request
  • 401 Invalid or missing credentials
  • 403 User not authorized to perform this operation

See Error Response Codes in the Appendix for more information on the meaning of these error codes.

Fields and Objects

The fields and objects returned in the response are explained in detail in our Shipment Schema documentation. Please refer to the Ocean Shipment Schema for more information.

Previous page
Next page