Last updated

Update a Shipment

Use an API endpoint to update a shipment that has already been added to project44's network.

Update a Shipment to Include Additional Identifiers

Add identifiers to a shipment that has already been created. This action uses a POST endpoint to add information to the shipment. The added information never removes or replaces previous shipment data. Users do not need to use a GET before updating a shipment's information.

During the course of tracking a shipment, project44 may discover new identifiers that relate to your shipment. These discovered identifiers are often purely informational and are not being used to determine which cargo to track – you do not need to add these to your shipment. In most cases, we strongly discourage sending these discovered identifiers when updating the shipment because this will cause project44 to track all cargo related to those identifiers. This can have unintended consequences, such as tracking more cargo than desired and changing which related shipment a container is being tracked under.

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. Add the new shipment identifiers to the identifiers array.

    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.

JSON
{
  "id": "string",
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "string"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "string"
    },
    {
      "type": "BOOKING_NUMBER",
      "value": "string"
    }
  ]
}

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.

  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:

JSON
{
  "id": "string",
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "string"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "string"
    },
    {
      "type": "BOOKING_NUMBER",
      "value": "string"
    }
  ]
}

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

FieldDescription
idThe Master Shipment ID of the shipment. This field is not required to create the shipment. It is returned in the 200 OK response when you create the shipment. Store the Master Shipment ID and use it to create or update a PUSH configuration (link to section) or get shipment tracking information (link to section).
identifiersThe shipment ID (different from the master shipment ID above) is necessary for shipment creation and for other actions including getting tracking information, updating a shipment, and deleting a shipments.
identifiers.typeThe type of identifier for the shipment. For shipment creation, you must include at least one BILL_OF_LADING (unique identifier given to you by the Ocean carrier. Bills of Lading (BOLs) often contain multiple containers (each with their own Container ID) allowing you to track multiple containers with a single identifier.) or BOOKING_NUMBER (unique identifiers given to you by the Ocean carrier. Booking Numbers (BNs) often contain multiple containers (each with their own Container ID) allowing you to track multiple containers with a single identifier.) AND exactly one CARRIER_SCAC (the carrier's Standard Carrier Alpha Code, a unique identification number for a specific carrier, usually two to four letters long.)
identifiers.valueThe value for the identifiers for the shipment.

Update Shipment Attributes

Change an Ocean shipment's attributes after the shipment has been created by deleting the shipment and then recreating it with the correct attributes.

project44's system supports updating shipments through a DELETE and POST only three times. This prevents accidental creation of the same shipment too many times.

Requirements

Have the following information:

  • Master Shipment ID (this is the id returned in the 200 OK response during shipment creation). You will need this to delete the shipment with the old attributes.
  • Shipment IDs (BILL_OF_LADING or BOOKING_NUMBER, plus CARRIER_SCAC). You will need these to create the shipment with the new attributes.
  • The new shipment attributes.

Workflow

Complete these steps:

  1. Prepare a POST request to /api/v4/shipments/tracking and add the original shipment identifiers you used during shipment creation and the new attributes.

For example:

JSON
 	{
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "string"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "string"
    }
  ],
  "attributes": [
    {
      "name": "string",
      "value": "string",
      "values": [
        "string"
      ]
    }
  ]
}

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.

  1. Send the request.

Expected Response

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

JSON
{
  "id": "string",
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "string"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "string"
    }
  ],
  "attributes": [
    {
      "name": "string",
      "value": "string",
      "values": [
        "string"
      ]
    }
  ],
  "relatedShipments": [
    {
      "id": "string",
      "identifiers": [
        {
          "type": "CONTAINER_ID",
          "value": "string"
        }
      ]
    },
    {
      "id": "string",
      "identifiers": [
        {
          "type": "CONTAINER_ID",
          "value": "string"
        }
      ]
    },
    {
      "id": "string",
      "identifiers": [
        {
          "type": "CONTAINER_ID",
          "value": "string"
        }
      ]
    }
  ]
}

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.

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 create a shipment for tracking and the fields returned with the API Response 200 OK.

FieldDescription
idThe Master Shipment ID of the shipment. This field is not required to create the shipment. It is returned in the 200 OK response when you create the shipment. Store the Master Shipment ID and use it to create or update a PUSH configuration (link to section) or get shipment tracking information (link to section).
identifiersThe shipment ID (different from the master shipment ID above) is necessary for shipment creation and for other actions including getting tracking information, updating a shipment, and deleting a shipments.
identifiers.typeThe type of identifier for the shipment. For shipment creation, you must include at least one BILL_OF_LADING (unique identifier given to you by the Ocean carrier. Bills of Lading (BOLs) often contain multiple containers (each with their own Container ID) allowing you to track multiple containers with a single identifier.) or BOOKING_NUMBER (unique identifiers given to you by the Ocean carrier. Booking Numbers (BNs) often contain multiple containers (each with their own Container ID) allowing you to track multiple containers with a single identifier.) AND exactly one CARRIER_SCAC (the carrier's Standard Carrier Alpha Code, a unique identification number for a specific carrier, usually two to four letters long.)
identifiers.valueThe value for the identifiers for the shipment.
attributesAn optional user-defined set of custom attributes to associate with this shipment.
attributes.nameThe key (name) for the custom attribute. Must be unique.
attributes.valuesAn array of the values for the custom attribute.