Update a Shipment

Update a Full Truckload (FTL) shipiment that has already been added to project44's Network.

project44 recommends to first get the current shipment object from the GET shipment endpoint, make the desired modifications, and then PUT the modified shipment to this endpoint. After the modified shipment is successfully submitted, the updated stops, attributes, shipping details, etc. will be applied and used in tracking from then on.

If a shipment PUT request comes in with only GeoCoordinates, it is possible that a street address will not be returned in the response.

Update an FTL Shipment by Shipment Identifier

Update an FTL shipment with a shipment identifier.

Making an update to tracking information including shipmentIdentifiers, capacityProviderAccountGroup, and apiConfiguration changes is not currently supported.

Requirements

Have the following information:

project44-generated ID (this is the id returned in the 200 OK response during Shipment Creation).
Carrier Identifier (SCAC, MC_NUMBER, DOT_NUMBER, SYSTEM, or P44_EU)
Shipment Identifier (BILL_OF_LADING or ORDER)
At least two shipment stops with stop information including
- Stop number
- Appointment windows (start and end dates and times)
- Location (using either an address or geocoordinates)
Equipment Identifier (MOBILE_PHONE, VEHICLE_ID, LICENSE_PLATE, SENSITECH_DEVICE, or TIVE_DEVICE_ID)

Workflow

Complete these steps:

Prepare a GET request to /api/v4/tl/shipments/{id}/statuses.
Prepare a PUT request to /api/v4/tl/shipments.
Add the required information to the request schema. For example,

{
  "carrierIdentifier": {
    "type": "SCAC",
    "value": "string"
  },
  "shipmentIdentifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "string"
    }
  ],
  "shipmentStops": [
    {
      "stopNumber": 0,
      "appointmentWindow": {
        "startDateTime": "2019-08-24T14:15:22",
        "endDateTime": "2019-08-24T14:15:22",
        "localTimeZoneIdentifier": "string"
      },
      "location": {
        "address": {
          "postalCode": "string",
          "addressLines": [
            "string"
          ],
          "city": "string",
          "state": "string",
          "country": "US"
        }
      }
    }
  ],
  "equipmentIdentifiers": [
    {
      "type": "MOBILE_PHONE_NUMBER",
      "value": "string",
      "shouldDelete": false
    }
  ]
}

This an example of a potential request. For the full request schema and descriptions for all fields and objects, please see our reference documentation.

Send the request.

Expected System Response

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

{
  "shipment": {
    "carrierIdentifier": {
      "type": "SCAC",
      "value": "string"
    },
    "shipmentIdentifiers": [
      {
        "type": "BILL_OF_LADING",
        "value": "string"
      }
    ],
    "shipmentStops": [
      {
        "stopNumber": 0,
        "appointmentWindow": {
          "startDateTime": "2019-08-24T14:15:22",
          "endDateTime": "2019-08-24T14:15:22",
          "localTimeZoneIdentifier": "string"
        },
        "location": {
          "address": {
            "postalCode": "string",
            "addressLines": [
              "string"
            ],
            "city": "string",
            "state": "string",
            "country": "US"
          }
        }
      }
    ],
    "equipmentIdentifiers": [
      {
        "type": "MOBILE_PHONE_NUMBER",
        "value": "string",
        "shouldDelete": false
      }
    ],
    "id": 0
  },
  "infoMessages": [
    {
      "severity": "ERROR",
      "message": "string",
      "diagnostic": "string",
      "source": "SYSTEM"
    }
  ]
}

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.

A unique project44 ID is returned in the response after shipment creation. Store this ID to use in future API calls.

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.

Field	Description
`carrierIdentifier`	This array contains your carrier identifier information.
`carrierIdentifier.type`	The carrier identifier type. Valid values include `SCAC`, `MC_NUMBER`, `DOT_NUMBER`, `SYSTEM`, or `P44_EU`.
`carrierIdentifier.value`	The value of the carrier identifier.
`shipmentIdentifiers`	The shipment identifiers that are unique to this shipment and carrier identifier. These may be used in subsequent API calls along with the carrier identifier to reference a shipment. They may also be used by project44 to track the shipment. Only one shipment identifier of each time may be provided.
`shipmentIdentifiers.type`	The type of the shipment identifier. Valid values include `ORDER` or `BILL_OF_LADING`.
`shipmentIdentifiers.value`	The value of the shipment identifier.
`shipmentStops`	An array that includes information for each stop.
`shipmentStops.stopNumber`	The user-defined stop number, where `1` is for the origin and the largest number is for the destination with any stops in between ordered by appointment time.
`shipmentStops.appointmentWindow`	The shipment's expected window of arrival at the defined stop.
`shipmentStops.appointmentWindow.startDateTime`	The appointment window start date and time for the stop.
`shipmentStops.appointmentWindow.endDateTime`	The appointment window end date and time for the stop.
`shipmentStops.location`	The user-defined location of the stop. Use if no geocoordinates are provided.
`shipmentStops.location.address`	The address of the stop.
`shipmentStops.location.address.postalCode`	The postal code for the stop.
`shipmentStops.location.address.addressLines`	The street address for the stop.
`shipmentStops.location.address.city`	The stop's city.
`shipmentStops.location.address.state`	The stop's state. Only relevant for USA, Mexico, and Canada.
`shipmentStops.location.address.country`	The stop's country.
`shipmentStops.geocoordinates`	The latitude and longitude of the stop. This field may not be provided when creating a shipment but will always be returned. Use if no address is provided.
`equipmentIdentifiers`	An array of the identifiers for the truckload equipment being tracked. These do not need to be unique to the shipment.
`equipmentIdentifiers.type`	The type of equipment identifier. Valid values include `MOBILE_PHONE`, `VEHICLE_ID`, `LICENSE_PLATE`, `SENSITECH_DEVICE`, or `TIVE_DEVICE_ID`.
`equipmentIdentifiers.value`	The value of the equipment identifier.