Shipment API Tutorial
Table of contents
Flexport’s Shipment API provides the ability to monitor shipments through integration, giving the needed insight into shipments to drive more efficient management and control. The Shipment Status API provides you with the ability to list your shipments, retrieve a shipment, and update an existing shipment.
Endpoints
GET /shipments
GET /shipments/id
PATCH /shipments/id
The Shipment object is integral to the Shipment API. Before we dive into the API, you can look at it’s various fields here.
Wow, that’s an impressive amount of information! Let’s see how and where it can be used.
In our first example, we’ll retrieve all shipments available to us. Here’s the curl command:
curl -X "GET" "https://api.flexport.com/shipments?sort=id&direction=desc"\
-H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Flexport-Version: 3" \
-H "Content-Type: application/json" \
Notice that we set two arguments directly within the URL: sort and direction, which sort the returned shipments by id in a descending sequence:
{
"_object": "/api/response",
"self": "https://api.flexport.com/shipments?page=1&per=20&sort=id&direction=desc",
"version": 2,
"data": {
"_object": "/api/collections/paginated",
"prev": null,
"next": null,
"data": [
{
"metadata": {},
"_object": "/shipments",
"id": 2983,
"name": "ABC Shipment",
"booking": {...},
"transportation_mode": "ocean",
"freight_type": "door_to_door",
"incoterm": "FOB",
"calculated_weight": {...},
"calculated_volume": {...},
"pieces": 8372,
"it_number": "V12345678",
"created_date": "2019-02-06T19:28:25.741Z",
"status": "in_transit_to_arrival_port",
"priority": "high",
"updated_at": "2019-02-06T19:28:25.119Z",
"estimated_departure_date": "2019-02-06T19:28:25+00:00",
"actual_departure_date": "2019-02-06T19:28:25+00:00",
"estimated_arrival_date": "2019-02-06T19:28:25+00:00",
"actual_arrival_date": "2019-02-06T19:28:25+00:00",
"estimated_picked_up_in_full_date": "2019-02-06T19:28:25+00:00",
"actual_picked_up_in_full_date": "2019-02-06T19:28:25+00:00",
"estimated_delivered_in_full_date": "2019-02-06T19:28:25+00:00",
"actual_delivered_in_full_date": "2019-02-06T19:28:25+00:00",
"cargo_ready_date": "2019-02-06",
"wants_export_customs_service": true,
"wants_import_customs_service": true,
"air_shipment": null,
"wants_freight_management_bco": true,
"wants_flexport_freight": true,
"wants_commercial_invoice_transcription": true,
"wants_flexport_insurance": true,
"wants_pickup_service": false,
"wants_trade_declaration_service": false,
"wants_visibility": false,
"ocean_shipment": {...},
"dangerous_goods": {...},
"shippers": [...],
"consignees": [...],
"buyers": [...],
"sellers": [...],
"importers_of_record": [...],
"items": [...],
"legs": {...},
"customs_entries": {...},
"commercial_invoices": {...},
"documents": {...},
"departure_date": "2019-02-06T19:28:25+00:00",
"arrival_date": "2019-02-06T19:28:25+00:00",
"picked_up_in_full_date": "2019-02-06T19:28:25+00:00",
"delivered_in_full_date": "2019-02-06T19:28:25+00:00"
}
]
}
}
You can filter the response on the parameters mentioned in the reference document.
That’s quite the list! As you can see, you have a great deal of flexibility to help focus your search.
Retrieving a specific shipment is fairly straightforward: you supply a shipment_id and make your request:
curl -X "GET" "https://api.flexport.com/shipments/id" \
-H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Flexport-Version: 3" \
-H "Accept: application/json" \
after which you receive
{
"_object": "/api/response",
"self": "https://api.flexport.com/shipments/1234",
"version": 2,
"data": {
"metadata": {},
"_object": "/shipments",
"id": 2983,
"name": "ABC Shipment",
"booking": {...},
"transportation_mode": "ocean",
"freight_type": "door_to_door",
"incoterm": "FOB",
"calculated_weight": {...},
"calculated_volume": {...},
"pieces": 8372,
"it_number": "V12345678",
"created_date": "2019-02-06T19:28:25.741Z",
"status": "in_transit_to_arrival_port",
"priority": "high",
"updated_at": "2019-02-06T19:28:25.119Z",
"estimated_departure_date": "2019-02-06T19:28:25+00:00",
"actual_departure_date": "2019-02-06T19:28:25+00:00",
"estimated_arrival_date": "2019-02-06T19:28:25+00:00",
"actual_arrival_date": "2019-02-06T19:28:25+00:00",
"estimated_picked_up_in_full_date": "2019-02-06T19:28:25+00:00",
"actual_picked_up_in_full_date": "2019-02-06T19:28:25+00:00",
"estimated_delivered_in_full_date": "2019-02-06T19:28:25+00:00",
"actual_delivered_in_full_date": "2019-02-06T19:28:25+00:00",
"cargo_ready_date": "2019-02-06",
"wants_export_customs_service": true,
"wants_import_customs_service": true,
"air_shipment": "NULL",
"wants_freight_management_bco": true,
"wants_flexport_freight": true,
"ocean_shipment": {...},
"dangerous_goods": {...},
"shippers": [...],
"consignees": [...],
"buyers": [...],
"sellers": [...],
"importers_of_record": [...],
"items": [...],
"legs": {...},
"customs_entries": {...},
"commercial_invoices": {...},
"documents": {...},
"departure_date": "2019-02-06T19:28:25+00:00",
"arrival_date": "2019-02-06T19:28:25+00:00",
"picked_up_in_full_date": "2019-02-06T19:28:25+00:00",
"delivered_in_full_date": "2019-02-06T19:28:25+00:00"
}
}
The Flexport Shipment API provides you with the ability to update your shipment metadata. An example HTTP request is:
curl -X "PATCH" "https://api.flexport.com/shipments/2983" \
-H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Flexport-Version: 3" \
-H "Accept: application/json" \
-d $'{
"metadata": [{
"name":"newKey",
"value":["newValue"]
}]
}'
On occasion, things don’t always proceed as you expect. Naturally, various HTTP error codes, along with an exception JSON object, are returned to help you build your exception handling routines. An example of an Error Response is shown below.
{
"_object": "/api/error",
"status": 400,
"code": "invalid_pagination",
"message": "Invalid Sort Direction. allowed values: desc, asc"
}
You’ll want to use the status and message fields to handle exceptions.