Shipment

Endpoints relating to Shipment objects

List all shipments

Returns a list of shipments.

Request
query Parameters
page
integer >= 1

Page number of the page to retrieve

Example: page=1
per
integer [ 1 .. 100 ]

Count of items in each page. Should be between 1 and 100 (inclusive).

Example: per=20
sort
string
Default: "id"

Sort results by the specified field.

Enum: "id" "transportation_mode" "status" "updated_at" "archived_at"
direction
string
Default: "desc"

Set sort order. Allows "asc" (ascending) or "desc" (descending).

Enum: "asc" "desc"
f.transportation_mode
string (TransportationMode)

Filters the list based on the shipment's transportation_mode. One of ocean or air.

Enum: "ocean" "air" "barge" "truck" "rail" "unknown_transportation" "ocean_air" "truck_intl" "warehouse_storage"
Example: f.transportation_mode=ocean
f.status
string (ShipmentStatus)

Filters the list based on the shipment's status. Cannot be used with f.statuses.any

Enum: "seller_location" "origin_stop_off" "in_transit_to_departure_port" "departure_port" "in_transit_to_intermediary_port" "intermediary_port" "in_transit_to_arrival_port" "arrival_port" "deconsolidation" "in_transit_to_final_destination" "destination_stop_off" "gated_out" "final_destination"
Example: f.status=in_transit_to_arrival_port
f.statuses.any
string (ShipmentStatus)

Filters the list for all shipments whose status is one of the passed in statuses. Can pass in multiple comma-separated statuses.

Enum: "seller_location" "origin_stop_off" "in_transit_to_departure_port" "departure_port" "in_transit_to_intermediary_port" "intermediary_port" "in_transit_to_arrival_port" "arrival_port" "deconsolidation" "in_transit_to_final_destination" "destination_stop_off" "gated_out" "final_destination"
Example: f.statuses.any=in_transit_to_arrival_port
f.container_number
string

Filters the list for shipments that are associated with a container specified by the given container number.

Example: f.container_number=BWSE3982156
f.purchase_order
string

Filters the list for shipments that are associated with the given purchase order number

Example: f.purchase_order=PO002811
f.sku
string

Filters the list for shipments that are associated a product identified by the given SKU.

Example: f.sku=ASA121
f.updated_at.gt
string

DEPRECATED -- Filters the list for shipments that where updated after the given time

f.updated_at.lt
string

DEPRECATED -- Filters the list for shipments that where updated before the given time

f.archived_at.gt
string

Filters the list for shipments that where archived after the given time

f.archived_at.lt
string

Filters the list for shipments that where archived before the given time

f.master_bill_number
string

Filters the list for shipments that are associated with the given master bill number

f.house_bill_number
string

Filters the list for shipments that are associated with the given house bill number

f.consignee_external_ref
string

Filters the list for shipments that have the specified company entity (denoted by external ref) as a consignee

f.origin_address_ref
string

Filters the list for shipments that have a shipment leg with the same origin address ref

f.destination_address_ref
string

Filters the list for shipments that have a shipment leg with the same destination address ref

f.metadata.YOUR_METADATA_KEY
string

Filters the list for shipments that have a specific metadata key-value pair. Multiple metadata filters can be added to a single query. If there are multiple metadata filters each with the same metadata key, then the filter will return shipments matching any of the specified metadata values for that metadata key. Note that keys must be URL encoded; e.g.: f.metadata.PO #=123 is invalid. It should instead be f.metadata.PO%20%23

f.wants_freight_management_bco
boolean

Filters the list based on shipment's wants_freight_management_bco

f.wants_flexport_freight
boolean

Filters the list based on shipment's wants_flexport_freight

f.wants_import_customs_service
boolean

Filters the list based on shipment's wants_import_customs_service

f.wants_export_customs_service
boolean

Filters the list based on shipment's wants_export_customs_service

f.wants_commercial_invoice_transcription
boolean

Filters the list based on shipment's wants_commercial_invoice_transcription

f.wants_flexport_insurance
boolean

Filters the list based on shipment's wants_flexport_insurance

f.wants_pickup_service
boolean

Filters the list based on shipment's wants_pickup_service

f.wants_trade_declaration_service
boolean

Filters the list based on shipment's wants_trade_declaration_service

f.visibility_only
boolean

Filters the list based on shipment's visibility_only flag

f.wants_delivery_service
boolean

Filters the list based on shipment's wants_delivery_service flag

f.belongs_to_a_buyers_consol
boolean

Filters the list based on whether the shipment belongs to a buyer's consolidation

Responses
200

collection of shipments

Response Schema: application/json
_object
string
self
string
version
integer
object
_object
string
prev
string or null
next
string or null
Array of objects (Shipment)
400

error

get/shipments
Response samples
application/json

Success

{
  • "_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": [
      • {
        }
      ]
    }
}

Retrieve a shipment

Retrieves the details of a single shipment.

Request
path Parameters
id
required
string

The unique id for the shipment to be retrieved.

Responses
200

Success

Response Schema: application/json
_object
string
self
string
version
integer
object (Shipment)
metadata
object (Metadata)

Set of custom key-values specific to the object. The keys are strings and values are arrays of strings. The set of valid keys is always the consignee's list of keys, even if call was made by a different party.

_object
string

Type of the object

id
integer

Unique identifier for the shipment

name
string

The name of the shipment

object (GenericObjectRef)
transportation_mode
string (TransportationMode)
Enum: "ocean" "air" "barge" "truck" "rail" "unknown_transportation" "ocean_air" "truck_intl" "warehouse_storage"
freight_type
string (FreightType)
Enum: "port_to_door" "port_to_port" "door_to_door" "door_to_port"
freight_cost
string

The dollar amount spent on freight

incoterm
string
Enum: "EXW" "FOB" "FAS" "FCA" "CPT" "CFR" "CIF" "CIP" "DAT" "DAP" "DDP" "DPU"
object (Weight)
object (Volume)
pieces
integer
it_number
string

Inbond Transit number used for US Customs

created_date
string <date-time>

Date the user confirmed the Flexport quote for this Shipment

status
string (ShipmentStatus)
Enum: "seller_location" "origin_stop_off" "in_transit_to_departure_port" "departure_port" "in_transit_to_intermediary_port" "intermediary_port" "in_transit_to_arrival_port" "arrival_port" "deconsolidation" "in_transit_to_final_destination" "destination_stop_off" "gated_out" "final_destination"
priority
string

The level of attention Flexport should give to this shipment

Enum: "standard" "high"
updated_at
string <date-time>

Date when the shipment object was last updated

estimated_departure_date
string <date-time>

Estimated departure date from the first port of the main voyage

actual_departure_date
string <date-time>

Actual departure date from the first port of the main voyage

estimated_arrival_date
string <date-time>

Estimated arrival date to the last port of the main voyage

actual_arrival_date
string <date-time>

Actual arrival date to the last port of the main voyage

cargo_ready_date
string <date>

Date when cargo is ready for pickup at the origin location

wants_freight_management_bco
boolean

Determines if a shipment bypasses a freight forwader and is booked directly with a steamship line.

wants_flexport_freight
boolean

Determines if a shipment is using Flexport services for a combination of import customs clearance or final leg delivery.

wants_commercial_invoice_transcription
boolean

Determines if a shipment is using Flexport’s commercial invoice transcription service.

wants_flexport_insurance
boolean

Determines if a shipment is using Flexport’s insurance service.

wants_pickup_service
boolean

Determines if a shipment uses Flexport trucking services from origin location to port.

wants_trade_declaration_service
boolean

Determines if a shipment uses trade declaration service for HK exports.

visibility_only
boolean

Indicates if a shipment was requested for tracking via the Flexport visibility-only service.

wants_delivery_service
boolean

Determines if Flexport is responsible for door delivery on a shipment.

wants_214_filing
boolean

Determines if the shipment wants a 214 filing.

wants_ftz_entry
boolean

Determines if the shipment wants an FTZ entry

belongs_to_a_buyers_consol
boolean

Indicated whether the shipment is part of a buyer's consol.

Array of objects (ShipmentRef)

Links to the child shipments if the shipment is the parent shipment in a buyer's consol.

object (ShipmentRef)

Links to the parent shipment if the shipment is a child shipment in a buyer's consol.

estimated_picked_up_in_full_date
string <date-time>

Estimated pickup date from the origin location. For ocean shipments with multiple containers, this is the date of last picked up container

actual_picked_up_in_full_date
string <date-time>

Actual pickup date from the origin location. For ocean shipments with multiple containers, this is the date of last picked up container

target_delivery_date
string <date>

Target date for when the shipment will be fully delivered. This date is set when the shipment's booking is confirmed. This value may be different from estimated_delivered_in_full_date, which is updated when there is new information about the progress of a shipment.

estimated_delivered_in_full_date
string <date-time>

Estimated delivery date to the destination location. For ocean shipments with multiple containers, this is the date of last delivered container

actual_delivered_in_full_date
string <date-time>

Actual delivery date to the destination location. For ocean shipments with multiple containers, this is the date of last delivered container

wants_export_customs_service
boolean

Determines if the shipment requires Flexport to provide export customs services.

wants_import_customs_service
boolean

Determines if the shipment requires Flexport to provide import customs services.

object or null (OceanShipmentDetail)
object or null (AirShipmentDetail)
object (ShipmentDangerousGoods)
object

The accepted quote object associated with the shipment.

quoted_transit_time_days_min
number

Minimum transit time for the shipment in days

quoted_transit_time_days_max
number

Maximum transit time for the shipment in days

quoted_delivery_date_from
string <date-time>

Earliest delivery date

quoted_delivery_date_to
string <date-time>

Latest delivery date

Array of objects (CompanyEntity)
Array of objects (CompanyEntity)
Array of objects (CompanyEntity)
Array of objects (CompanyEntity)
Array of objects (CompanyEntity)
Array of objects (ShipmentItem)
object (LegCollectionRef)
object (CustomsEntryCollectionRef)
object (CommercialInvoiceCollectionRef)
object (DocumentCollectionRef)
departure_date
string <date-time>

DEPRECATED date field

arrival_date
string <date-time>

DEPRECATED date field

picked_up_in_full_date
string <date-time>

DEPRECATED date field

delivered_in_full_date
string <date-time>

DEPRECATED date field

400

error

get/shipments/{id}
Response samples
application/json

Success

{
  • "_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",
    • "freight_cost": 512.14,
    • "incoterm": "FOB",
    • "calculated_weight": {
      • "_object": "/quantity/weight",
      • "value": 2300.4,
      • "unit": "kg"
      },
    • "calculated_volume": {
      • "_object": "/quantity/volume",
      • "value": 472.62,
      • "unit": "cbm"
      },
    • "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,
    • "visibility_only": false,
    • "wants_delivery_service": false,
    • "belongs_to_a_buyers_consol": false,
    • "child_shipments": null,
    • "parent_shipment": null,
    • "ocean_shipment": {
      • "_object": "/ocean/shipment",
      • "is_lcl": false,
      • "house_bill_number": "TUWSANR18658",
      • "master_bill_number": "NEWO697216024",
      • "carrier_booking_number": "697216024",
      • "confirmed_space_released_at": "2021-06-08T06:18:46.299Z",
      • "containers": {}
      },
    • "dangerous_goods": {
      • "review_status": "complete",
      • "classifications": [ ]
      },
    • "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"
    }
}

Update an existing shipment

Request
path Parameters
id
required
integer

The unique id for the shipment to be updated

Example: 12345
Request Body schema: application/json
required
metadata
object

Metadata to replace existing metadata. Keys should be strings and values should be arrays. All existing metadata will be replaced by the passed in object.

Responses
200

The updated shipment

Response Schema: application/json
_object
string
self
string
version
integer
object (Shipment)
metadata
object (Metadata)

Set of custom key-values specific to the object. The keys are strings and values are arrays of strings. The set of valid keys is always the consignee's list of keys, even if call was made by a different party.

_object
string

Type of the object

id
integer

Unique identifier for the shipment

name
string

The name of the shipment

object (GenericObjectRef)
transportation_mode
string (TransportationMode)
Enum: "ocean" "air" "barge" "truck" "rail" "unknown_transportation" "ocean_air" "truck_intl" "warehouse_storage"
freight_type
string (FreightType)
Enum: "port_to_door" "port_to_port" "door_to_door" "door_to_port"
freight_cost
string

The dollar amount spent on freight

incoterm
string
Enum: "EXW" "FOB" "FAS" "FCA" "CPT" "CFR" "CIF" "CIP" "DAT" "DAP" "DDP" "DPU"
object (Weight)
object (Volume)
pieces
integer
it_number
string

Inbond Transit number used for US Customs

created_date
string <date-time>

Date the user confirmed the Flexport quote for this Shipment

status
string (ShipmentStatus)
Enum: "seller_location" "origin_stop_off" "in_transit_to_departure_port" "departure_port" "in_transit_to_intermediary_port" "intermediary_port" "in_transit_to_arrival_port" "arrival_port" "deconsolidation" "in_transit_to_final_destination" "destination_stop_off" "gated_out" "final_destination"
priority
string

The level of attention Flexport should give to this shipment

Enum: "standard" "high"
updated_at
string <date-time>

Date when the shipment object was last updated

estimated_departure_date
string <date-time>

Estimated departure date from the first port of the main voyage

actual_departure_date
string <date-time>

Actual departure date from the first port of the main voyage

estimated_arrival_date
string <date-time>

Estimated arrival date to the last port of the main voyage

actual_arrival_date
string <date-time>

Actual arrival date to the last port of the main voyage

cargo_ready_date
string <date>

Date when cargo is ready for pickup at the origin location

wants_freight_management_bco
boolean

Determines if a shipment bypasses a freight forwader and is booked directly with a steamship line.

wants_flexport_freight
boolean

Determines if a shipment is using Flexport services for a combination of import customs clearance or final leg delivery.

wants_commercial_invoice_transcription
boolean

Determines if a shipment is using Flexport’s commercial invoice transcription service.

wants_flexport_insurance
boolean

Determines if a shipment is using Flexport’s insurance service.

wants_pickup_service
boolean

Determines if a shipment uses Flexport trucking services from origin location to port.

wants_trade_declaration_service
boolean

Determines if a shipment uses trade declaration service for HK exports.

visibility_only
boolean

Indicates if a shipment was requested for tracking via the Flexport visibility-only service.

wants_delivery_service
boolean

Determines if Flexport is responsible for door delivery on a shipment.

wants_214_filing
boolean

Determines if the shipment wants a 214 filing.

wants_ftz_entry
boolean

Determines if the shipment wants an FTZ entry

belongs_to_a_buyers_consol
boolean

Indicated whether the shipment is part of a buyer's consol.

Array of objects (ShipmentRef)

Links to the child shipments if the shipment is the parent shipment in a buyer's consol.

object (ShipmentRef)

Links to the parent shipment if the shipment is a child shipment in a buyer's consol.

estimated_picked_up_in_full_date
string <date-time>

Estimated pickup date from the origin location. For ocean shipments with multiple containers, this is the date of last picked up container

actual_picked_up_in_full_date
string <date-time>

Actual pickup date from the origin location. For ocean shipments with multiple containers, this is the date of last picked up container

target_delivery_date
string <date>

Target date for when the shipment will be fully delivered. This date is set when the shipment's booking is confirmed. This value may be different from estimated_delivered_in_full_date, which is updated when there is new information about the progress of a shipment.

estimated_delivered_in_full_date
string <date-time>

Estimated delivery date to the destination location. For ocean shipments with multiple containers, this is the date of last delivered container

actual_delivered_in_full_date
string <date-time>

Actual delivery date to the destination location. For ocean shipments with multiple containers, this is the date of last delivered container

wants_export_customs_service
boolean

Determines if the shipment requires Flexport to provide export customs services.

wants_import_customs_service
boolean

Determines if the shipment requires Flexport to provide import customs services.

object or null (OceanShipmentDetail)
object or null (AirShipmentDetail)
object (ShipmentDangerousGoods)
object

The accepted quote object associated with the shipment.

quoted_transit_time_days_min
number

Minimum transit time for the shipment in days

quoted_transit_time_days_max
number

Maximum transit time for the shipment in days

quoted_delivery_date_from
string <date-time>

Earliest delivery date

quoted_delivery_date_to
string <date-time>

Latest delivery date

Array of objects (CompanyEntity)
Array of objects (CompanyEntity)
Array of objects (CompanyEntity)
Array of objects (CompanyEntity)
Array of objects (CompanyEntity)
Array of objects (ShipmentItem)
object (LegCollectionRef)
object (CustomsEntryCollectionRef)
object (CommercialInvoiceCollectionRef)
object (DocumentCollectionRef)
departure_date
string <date-time>

DEPRECATED date field

arrival_date
string <date-time>

DEPRECATED date field

picked_up_in_full_date
string <date-time>

DEPRECATED date field

delivered_in_full_date
string <date-time>

DEPRECATED date field

400

error

patch/shipments/{id}
Request samples
application/json
{
  • "metadata": {
    • "purchase_order": [
      • "12345"
      ]
    }
}
Response samples
application/json

Success

{
  • "_object": "/api/response",
  • "self": "https://api.flexport.com/shipments/12345",
  • "version": 2,
  • "data": {
    • "metadata": {
      • "purchase_order": [
        ]
      },
    • "_object": "/shipments",
    • "id": 2983,
    • "name": "ABC Shipment",
    • "booking": {},
    • "transportation_mode": "ocean",
    • "freight_type": "door_to_door",
    • "freight_cost": 512.14,
    • "incoterm": "FOB",
    • "calculated_weight": {
      • "_object": "/quantity/weight",
      • "value": 2300.4,
      • "unit": "kg"
      },
    • "calculated_volume": {
      • "_object": "/quantity/volume",
      • "value": 472.62,
      • "unit": "cbm"
      },
    • "pieces": 8372,
    • "it_number": "V12345678",
    • "created_date": "2019-02-06T19:28:25+00:00",
    • "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,
    • "visibility_only": false,
    • "wants_delivery_service": false,
    • "wants_214_filing": false,
    • "wants_ftz_entry": false,
    • "ocean_shipment": {
      • "_object": "/ocean/shipment",
      • "is_lcl": false,
      • "house_bill_number": "TUWSANR18658",
      • "master_bill_number": "NEWO697216024",
      • "carrier_booking_number": "697216024",
      • "confirmed_space_released_at": "2021-06-08T06:18:46.299Z",
      • "containers": {}
      },
    • "dangerous_goods": {
      • "review_status": "complete",
      • "classifications": [ ]
      },
    • "quoted_transit_time_days_min": 10,
    • "quoted_transit_time_days_max": 20,
    • "quoted_delivery_date_from": "2023-01-10T16:00:00.000-08:00",
    • "quoted_delivery_date_to": "2023-01-20T16:00:00.000-08:00",
    • "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"
    }
}

Create shareable URLs for shipments

Returns a list of shipments status shareable url.

The ShipmentShareable POST endpoint needs special permission to access. Please contact your Flexport Sales representative if you are interested in using this endpoint.

Request
Request Body schema: application/json
required
shipment_ids
Array of integers

A list (length < 10) of the unique id for the shipment to be retrieved.

Responses
200

collection of shipments shareable status url

Response Schema: application/json
_object
string
self
string
version
integer
object
_object
string
Array of objects
400

error

post/shipments_shareable
Request samples
application/json
{
  • "shipment_ids": [
    • 123,
    • 456
    ]
}
Response samples
application/json

Success

{}
➔ Next to ShipmentLeg