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.
shipmentIdentifiers
, capacityProviderAccountGroup
, and apiConfiguration
changes is not currently supported. Requirements
Have the following information:
- project44-generated ID (this is the
id
returned in the200 OK
response during Shipment Creation). - Carrier Identifier (
SCAC
,MC_NUMBER
,DOT_NUMBER
,SYSTEM
, orP44_EU
) - Shipment Identifier (
BILL_OF_LADING
orORDER
) - 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
, orTIVE_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 } ] }
- 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" } ] }
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. |