Update a Shipment

Update an existing shipment in project44’s network using the following API. You can either add more identifiers or modify shipment attributes or add new events. Updating a shipment includes either:

• Adding information to an existing shipment through a POST request.
• Fully replacing a shipment through a PUT request.

Add Information to an Existing Shipment

1. Add Identifiers to an Existing Shipment

Use this endpoint to append new identifiers to an already created shipment in Project44. This is a non-destructive operation — existing shipment data is preserved.

Note: You do not need to make a GET request before updating.

Project44 may discover related identifiers while tracking. These are for informational purposes only and should not be added unless necessary, as they may cause additional, unintended cargo to be tracked.

Requirements

Have the following information available:

• Master Shipment ID (the id returned during shipment creation).
• The new identifiers to add to the post. These can be BILL_OF_LADING, BOOKING_NUMBER, CONTAINER_ID, or CARRIER_SCAC.

Workflow

Complete these steps:

1. Prepare a POST request to /api/v4/shipments/tracking.
2. Include the shipment id and updated identifiers in the payload.

For example, if you want to add the BOOKING_NUMBER to a shipment that was created using the BILL_OF_LADING and the CARRIER_SCAC, see the below schema.

{
  "id": "2b1911da-d58c-4f1a-8c6b-55dc1e06df39",
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "213953651"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "MSCU"
    },
    {
      "type": "BOOKING_NUMBER",
      "value": "BKG123456"
    }
  ]
}

3. 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": "2b1911da-d58c-4f1a-8c6b-55dc1e06df39",
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "213953651"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "MSCU"
    },
    {
      "type": "BOOKING_NUMBER",
      "value": "BKG123456"
    }
  ]
}

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.

2. Update Shipment Attributes

Please refer to the guide on Managing Shipment Attributes for more details.

3. Replace an Existing Shipment

To fully update a shipment, project44 recommends retrieving the current shipment object using the GET Shipment endpoint. Make the necessary changes, then submit the updated shipment using the below endpoint. Once the modified shipment is successfully submitted, all updated data—such as stops, attributes, events, and identifiers—will be applied and used for tracking going forward.

Requirements

Have the following information available:

• Master Shipment ID (the id returned during shipment creation).

Workflow

Complete these steps:

1. Fetch the current shipment object using a GET request as described in Get Shipment.
2. Prepare a PUT request to /api/v4/shipments/tracking.

For example, if you want to update the identifiers of a shipment that was already created then you can do the following, see the below schema.

{
  "id": "2b1911da-d58c-4f1a-8c6b-55dc1e06df39",
  "identifiers": [
    {
      "type": "CARRIER_SCAC",
      "value": "MSCU"
    },
    {
      "type": "BOOKING_NUMBER",
      "value": "BKG123456"
    }
  ]
}

3. Send the request.

Expected Response

You have successfully submitted the request when you receive a 200 OK response and the response schema includes the updated shipment. Here is an example of the response schema:

{
  "id": "2b1911da-d58c-4f1a-8c6b-55dc1e06df39",
  "identifiers": [
    {
      "type": "BOOKING_NUMBER",
      "value": "BKG123456"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "MSCU"
    }
  ],
  "attributes": [
    {
      "name": "Attribute Name",
      "values": [
        "value 1", "value 2"
      ]
    }
  ],
  "relatedShipments": [
    {
      "id": "4g1911da-d58c-4f1a-8c6b-55dc1e06df56",
      "identifiers": [
        {
          "type": "CONTAINER_ID",
          "value": "MEDU1234567"
        }
      ]
    }
  ]
}

In the response you receive the identifiers (BILL_OF_LADING or BOOKING_NUMBER and CARRIER_SCAC) and the shipment attributes (attributes array) used in the request. Plus you will receive the Master Shipment ID (id) and all related CONTAINER_IDs and ids of containers discovered by Project44.

Store the Master Shipment ID. Use the Master Shipment ID to get shipment tracking updates.

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 table below describes only the minimum relevant fields of the API Request to update a shipment for tracking and the fields returned with the API Response 200 OK.