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.
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
AIR_WAYBILL
,HOUSE_AIR_WAYBILL
orCARRIER_SCAC
.
Workflow
Complete these steps:
Prepare a
POST
request to /api/v4/shipments/tracking.Add the new shipment identifiers to the identifiers array.
For example, if you want to add the
AIR_WAYBILL
to a shipment that was created using theHOUSE_AIR_WAYBILL
and theCARRIER_SCAC
, see the below schema.
{ "id": "string", "identifiers": [ { "type": "HOUSE_AIR_WAYBILL", "value": "string" }, { "type": "CARRIER_SCAC", "value": "string" }, { "type": "AIR_WAYBILL", "value": "string" } ] }
- 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": "string", "identifiers": [ { "type": "HOUSE_AIR_WAYBILL", "value": "string" }, { "type": "CARRIER_SCAC", "value": "string" }, { "type": "AIR_WAYBILL", "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.
Field | Description |
---|---|
id | The 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. |
identifiers | The list of identifiers used for tracking the shipment. |
identifiers.type | The type of identifier for the shipment. For shipment creation, you must include at least one AIR_WAYBILL (unique identifier given to you by the Airline.) or HOUSE_AIR_WAYBILL (unique identifier given by Freight-Forwarders) along with exactly one CARRIER_SCAC (the unique identifier corresponding to the Freight-Forwarder, usually two to four letters long.) |
identifiers.value | The value for the identifiers for the shipment. |
Update Shipment Attributes
Change an Air shipment's attributes after the shipment has been created by deleting the shipment and then recreating it with the correct attributes.
Requirements
Have the following information:
- Master Shipment ID (this is the
id
returned in the200 OK
response during shipment creation). You will need this to delete the shipment with the old attributes. - Shipment IDs (
AIR_WAYBILL
orHOUSE_AIR_WAYBILL
, plusCARRIER_SCAC
). You will need these to create the shipment with the new attributes. - The new shipment attributes.
Workflow
Complete these steps:
- 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:
{ "identifiers": [ { "type": "HOUSE_AIR_WAYBILL", "value": "string" }, { "type": "CARRIER_SCAC", "value": "string" } ], "attributes": [ { "name": "string", "value": "string", "values": [ "string" ] } ] }
- 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:
{ "id": "string", "identifiers": [ { "type": "HOUSE_AIR_WAYBILL", "value": "string" }, { "type": "CARRIER_SCAC", "value": "string" } ], "attributes": [ { "name": "string", "value": "string", "values": [ "string" ] } ] }
In the response you receive the identifiers (AIR_WAYBILL
or HOUSE_AIR_WAYBILL
and CARRIER_SCAC
) and the shipment attributes (attributes
array) used in the request. Plus you will receive the Master Shipment ID (id
).
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
.
Field | Description |
---|---|
id | The 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. |
identifiers | The list of identifiers used for tracking the shipment. |
identifiers.type | The type of identifier for the shipment. For shipment creation, you must include at least one AIR_WAYBILL (unique identifier given to you by the Airline.) or HOUSE_AIR_WAYBILL (unique identifier given by Freight-Forwarders) along with exactly one CARRIER_SCAC (the unique identifier corresponding to the Freight-Forwarder, usually two to four letters long.) |
identifiers.value | The value for the identifiers for the shipment. |
attributes | An optional user-defined set of custom attributes to associate with this shipment. |
attributes.name | The key (name) for the custom attribute. Must be unique. |
attributes.values | An array of the values for the custom attribute. |