Shipment API Tutorial

Overview

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

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.

Listing All Shipments

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"
            }
        ]
    }
}

Filtering Your Response

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 Shipment

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"
    }
}

Updating a Shipment

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"]
            }]
        }'

Error Handling

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.