Booking

Endpoints relating to Booking objects

List all bookings

Returns a list of bookings.

Request
query Parameters
page
integer >= 1
Default: 1

Page number of the page to retrieve

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

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

Example: per=20
sort
string

Sort results by the specified field.

Enum: "cargo_ready_date" "created_at"
direction
string
Default: "desc"

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

Enum: "asc" "desc"
f.status
string

Filter the list based on status of the booking

Enum: "booked" "submitted"
f.shipment.id
integer

Filter by the shipment resulting from the booking

Example: f.shipment.id=123456
f.consignee_entity_ref
string

Filters the list based on the booking's consignee

Example: f.consignee_entity_ref=amazon-us
f.shipper_entity_ref
string

Filters the list based on the booking's shipper

Example: f.shipper_entity_ref=amazon-us
f.name
string
f.cargo_ready_date
string

Filters the list for bookings with the specified cargo ready date

f.cargo_ready_date.gt
string

Filters the list for bookings with cargo ready date after the specified date

f.cargo_ready_date.gte
string

Filters the list for bookings with cargo ready date after the specified date, inclusive

f.cargo_ready_date.lt
string

Filters the list for bookings with cargo ready date before the specified date

f.cargo_ready_date.lte
string

Filters the list for bookings with cargo ready date before the specified date, inclusive

f.created_at
string

Filters the list for bookings with the specified created_at

f.created_at.gt
string

Filters the list for bookings created after the specified date

f.created_at.gte
string

Filters the list for bookings created after the specified date, inclusive

f.created_at.lt
string

Filters the list for bookings created before the specified date

f.created_at.lte
string

Filters the list for bookings created before the specified date, inclusive

f.updated_at
string

Filters the list for bookings with the specified updated_at

f.updated_at.gt
string

Filters the list for bookings updated after the specified date

f.updated_at.gte
string

Filters the list for bookings updated after the specified date, inclusive

f.updated_at.lt
string

Filters the list for bookings updated before the specified date

f.updated_at.lte
string

Filters the list for bookings updated before the specified date, inclusive

f.metadata.YOUR_METADATA_KEY
string

Filters the list for bookings 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 bookings 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

Responses
200

collection of bookings

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

error

get/bookings
Response samples
application/json

Success

{
  • "_object": "/api/response",
  • "self": "https://api.flexport.com/bookings?page=13&per=10",
  • "version": 2,
  • "data": {
    • "_object": "/api/collections/paginated",
    • "prev": "https://api.flexport.com/bookings?page=12&per=10",
    • "next": null,
    • "data": [
      • {
        }
      ]
    }
}

Create and return a booking

Request
Request Body schema: application/json
required
name
required
string

Always required. Name of the booking.

shipper_entity_ref
required
string

Always required. Customizable reference ID of company entity that is the shipper of the booking.

consignee_entity_ref
required
string

Always required. Customizable reference ID of company entity that is the consignee of the booking.

notify_party
string or null

Optional. Name and address of company that is the notify party of the booking. If null, then this is the same as consignee.

object (CreateOceanBooking)
is_lcl
required
boolean

Always required. Whether the booking is for an LCL shipment. If false, the booking is FCL. If true, the booking is LCL.

required
object (CreateContainerCounts)
incoterm
required
string

Always required. The Incoterm of your shipment

Enum: "EXW" "FOB" "FAS" "FCA" "CPT" "CFR" "CIF" "CIP" "DAT" "DAP" "DDP" "DPU"
required
Array of objects (CreateBookingHsCode)
wants_pickup_service
required
boolean

Always required. Whether transportation is requested from the origin location to the port.

wants_delivery_service
boolean

Optional. Whether transportation is requested from the destination port to destination address. If unknown, then leave as null.

origin_port_us_cbp_port_code
string

One of origin_port_us_cbp_port_code or origin_port_loc_code is required if pickup_service = no. Unique port reference code used by US Customs and Border Protection.

origin_port_loc_code
string

One of origin_port_us_cbp_port_code or origin_port_loc_code is required if pickup_service = no. Unique port reference code used by US CBP.

destination_port_us_cbp_port_code
string

Optional, provide one of destination_port_us_cbp_port_code or destination_port_loc_code. Unique port reference code published in the United Nations Code for Trade and Transport Locations (UN/LOCODE).

destination_port_loc_code
string

Optional, provide one of destination_port_us_cbp_port_code or destination_port_loc_code. Unique port reference code published in the United Nations Code for Trade and Transport Locations (UN/LOCODE).

object (CreateAirBooking)

If a non-null value is passed in for 'air_booking', then the new booking will be assumed to be an air booking, even if the 'ocean_booking' or 'trucking_booking' fields are set.

incoterm
required
string
Enum: "EXW" "FOB" "FAS" "FCA" "CPT" "CFR" "CIF" "CIP" "DAT" "DAP" "DDP" "DPU"
required
Array of objects (CreateBookingHsCode)
wants_pickup_service
required
boolean

Always required. Whether transportation is requested from the origin location to the port.

wants_delivery_service
boolean

Optional. Whether transportation is requested from the destination port to destination address. If unknown, then leave as null.

origin_port_us_cbp_port_code
string

One of origin_port_us_cbp_port_code, origin_port_loc_code, origin_port_iata_code, or origin_port_icao_code is required if pickup_service = no. Unique port reference code used by US CBP, not applicable for non-US airports.

origin_port_loc_code
string

One of origin_port_us_cbp_port_code, origin_port_loc_code, origin_port_iata_code, or origin_port_icao_code is required if pickup_service = no. Unique port reference code published in the UN/LOCODE.

origin_port_iata_code
string

One of origin_port_us_cbp_port_code, origin_port_loc_code, origin_port_iata_code, or origin_port_icao_code is required if pickup_service = no. Unique airport reference code used by IATA.

origin_port_icao_code
string

One of origin_port_us_cbp_port_code, origin_port_loc_code, origin_port_iata_code, or origin_port_icao_code is required if pickup_service = no. Unique airport reference code used by ICAO.

destination_port_us_cbp_port_code
string

Optional, provide one of destination_port_us_cbp_port_code, destination_port_loc_code, destination_port_iata_code, or destination_port_icao_code. Unique port reference code used by US CBP, not applicable for non-US airports.

destination_port_loc_code
string

Optional, provide one of destination_port_us_cbp_port_code, destination_port_loc_code, destination_port_iata_code, or destination_port_icao_code. Unique port reference code published in the UN/LOCODE.

destination_port_iata_code
string

Optional, provide one of destination_port_us_cbp_port_code, destination_port_loc_code, destination_port_iata_code, or destination_port_icao_code. Unique airport reference code used by IATA.

destination_port_icao_code
string

Optional, provide one of destination_port_us_cbp_port_code, destination_port_loc_code, destination_port_iata_code, or destination_port_icao_code. Unique airport reference code used by ICAO.

object (CreateTruckingBooking)
is_ltl
required
boolean

Whether the booking is for an LTL shipment. If false, the booking is FTL. If true, then the booking is LTL.

payment_terms
required
string

Whether the shipper or consignee is responsible for payment of trucking freight. This can be collect (consignee) or prepaid (shipper).

Enum: "collect" "prepaid"
description_of_products
string

General description of the products in the shipment.

origin_address_ref
required
string

Always required. Customizable reference ID of network location that is the pickup location.

destination_address_ref
required
string

Always required for trucking bookings. Always required for air and ocean bookings if wants_delivery_service is TRUE. Customizable reference ID of network location that is the delivery location.

cargo_ready_date
required
string <date>

Always required. Date when cargo is ready for pickup at the origin location.

delivery_date
string <date>

Optional. Target date by when cargo must be delivered.

wants_export_customs_service
required
boolean

Always required. Whether the booking requires Flexport to provide export customs services.

wants_flexport_freight
boolean

Optional. Whether the booking requires Flexport to provide freight services.

wants_import_customs_service
boolean

Optional. Whether the booking requires Flexport to provide import customs services.

wants_bco
boolean

Optional. Whether the booking requires Flexport to provide BCO services.

required
object (CreateCargo)

With cargo you have two options, detailed or simple. These are both expressed directly on the cargo object. For detailed cargo, shipping_units is required, and weight and volume is required in the cargo object or the shipping_units object. For simple cargo, shipping_units is required, but only one should be specified, and weight and volume are required in the cargo object.

object (VolumeCreate)
object (WeightCreate)
marks_and_numbers
string

Optional. Identifying markings and numbers that are visible on the cargo.

Array of objects (ShippingUnitCreate)
contains_hazmat
boolean

Required. Whether the cargo contains hazardous materials.

contains_magnets
boolean

Required. Whether the cargo contains magnets.

contains_other_dangerous_goods
boolean

Required. Whether the cargo contains other non-hazmat, non-magnet, non-battery dangerous goods.

contains_li_ion
boolean

Required. Whether the cargo contains lithium-ion batteries.

contains_non_li_ion_battery
boolean

Required. Whether the cargo contains non-lithium-ion batteries, e.g. lithium batteries.

lithium_batteries_packing_types
Array of any

Required if contains_li_ion is true. List of ways in which lithium-ion batteries will be packed for this booking. This can be a subset of packed_loose, packed_with_equipment, contained_in_equipment, and contained_in_battery_powered_vehicle.

Items Enum: "packed_loose" "packed_with_equipment" "contained_in_equipment" "contained_in_battery_powered_vehicles"
special_instructions
string

Additional instructions not included in rest of booking form.

object or Array of objects (MetadataCreate)
One of:

Metadata has two allowed formats. Either array format or object format. Refer to the metadata section in this documentation for more information.

example_key
Array of strings
declared_as_strategy
string

Required when origin or destination port is Hong Kong. Does your shipment contain goods subject to export control regulations? Export Control Regulations include dual use item control, Hong Kong strategic commodity control, US and EU export control, etc.

Enum: "yes" "no" "notsure"
eccn_codes
string

Required when declared_as_strategy is "yes". Please provide the ECCN codes (Export Control Classification Number) of the products subject to export control regulations. Make sure you find the right ECCN codes in the Commerce Control List. Make sure you provide the correct format of the ECCN code (five character alpha-numeric such as 3A001, 5A002, etc) seperated by commas. According to the laws, providing the wrong ECCN information might cause fines.

flow_direct
boolean
Default: false

Optional. Whether to create Flow Direct Quote for the Booking. Currently, only Ocean LCL Booking is supported

object

Optional. Container-level references provided by client before actual container numbers are assigned. These references are used throughout the shipment lifecycle until actual container numbers are available. Maps container size types to arrays of reference objects containing client-provided identifiers.

additional property
Array of objects
Array
property name*
additional property
Array of strings
user_email
string

Optional. Email address of the user who created the booking. If omitted, the email of the client's admin will be used by default. The email address must belong to a user within the client's organization.

Responses
200

The created booking

Response Schema: application/json
_object
string
self
string
version
integer
object (Booking)
_object
string

Type of the object

id
integer

Unique identifier for the booking

name
string

The name of the booking

object (ShipmentRef)
status
string
Enum: "archived" "draft" "submitted" "booked" "shipment"
quote_status
string or null
Enum: "pending_quote" "sent_quote" "received_quote" "shared_quote" "expired_quote" "ready_to_share_quote" "accepted_quote" "received_quote" "rejected_quote" "requoted_quote" "archived_quote"
object (CompanyEntity)
object (CompanyEntity)
notify_party
string or null
Default: null
transportation_mode
string (TransportationMode)
Enum: "ocean" "air" "barge" "truck" "rail" "unknown_transportation" "ocean_air" "truck_intl" "warehouse_storage"
object or null (OceanBookingDetail)
object or null (AirBookingDetail)
object or null (TruckingBookingDetail)
object (Address)
cargo_ready_date
string <date>
object (Address)
delivery_date
string <date>
wants_export_customs_service
boolean

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

wants_import_customs_service
boolean

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

object (Cargo)

With cargo you have two options, detailed or simple. These are both expressed directly on the cargo object. For detailed cargo, shipping_units is required, and weight and volume is required in the cargo object or the shipping_units object. For simple cargo, shipping_units is required, but only one should be specified, and weight and volume are required in the cargo object.

special_instructions
string
object (BookingLineItemCollectionRef)
user_email
string

Email of the user who created the booking

created_at
string <date-time>
updated_at
string <date-time>
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.

400

error

post/bookings
Request samples
application/json
{
  • "name": "PO 123",
  • "shipper_entity_ref": "zoomit-us",
  • "consignee_entity_ref": "zoomit_ref",
  • "notify_party": null,
  • "ocean_booking": {
    • "is_lcl": false,
    • "incoterm": "FOB",
    • "container_counts": {
      • "twenty_ft": 2,
      • "forty_ft": 3,
      • "forty_ft_hc": 4,
      • "forty_five_ft_hc": 5
      },
    • "product_descriptions": [
      • {
        }
      ],
    • "wants_pickup_service": false,
    • "wants_delivery_service": false
    },
  • "origin_address_ref": "id-274346",
  • "destination_address_ref": "my-albany-ref",
  • "cargo_ready_date": "2019-06-30",
  • "delivery_date": "2019-07-31",
  • "wants_export_customs_service": true,
  • "cargo": {
    • "volume": {
      • "_object": "/quantity/volume",
      • "value": 472.62,
      • "unit": "cbm"
      },
    • "weight": {
      • "_object": "/quantity/weight",
      • "value": 2300.4,
      • "unit": "kg"
      },
    • "marks_and_numbers": "Fragile",
    • "shipping_units": [
      • {
        }
      ],
    • "contains_hazmat": true,
    • "contains_magnets": true,
    • "contains_other_dangerous_goods": true,
    • "contains_li_ion": true,
    • "contains_non_li_ion_battery": true,
    • "lithium_batteries_packing_types": [
      • "packed_loose"
      ]
    },
  • "special_instructions": "Handle carefully",
  • "metadata": {
    • "purchase_order": [
      • "12345"
      ],
    • "sku": [
      • "abc123"
      ]
    },
  • "user_email": "john@example.com"
}
Response samples
application/json
{
  • "_object": "/api/response",
  • "self": "https://api.flexport.com/bookings",
  • "version": 2,
  • "data": {
    • "id": 2983,
    • "_object": "/booking",
    • "name": "PO 123",
    • "shipper_entity": {
      • "_object": "/company_entity",
      • "id": 9281,
      • "name": "My Manufacturer",
      • "ref": "manufacturer_1",
      • "mailing_address": {
        },
      • "vat_numbers": [
        ]
      },
    • "consignee_entity": {
      • "_object": "/company_entity",
      • "id": 9281,
      • "name": "Zoomit",
      • "ref": "self",
      • "mailing_address": {
        },
      • "vat_numbers": [
        ]
      },
    • "notify_party": null,
    • "transportation_mode": "ocean",
    • "ocean_booking": {
      • "_object": "/ocean/booking",
      • "is_lcl": false,
      • "container_counts": {
        },
      • "incoterm": "FOB",
      • "wants_pick_up_service": false,
      • "wants_delivery_service": false,
      • "origin_port": {
        },
      • "destination_port": {
        },
      • "product_descriptions": [
        ]
      },
    • "air_booking": null,
    • "trucking_booking": null,
    • "origin_address": {
      • "_object": "/address",
      • "street_address": "1641 Settlers Lane",
      • "street_address2": "STE 2918",
      • "city": "Albany",
      • "state": "MN",
      • "country": "United States of America",
      • "country_code": "US",
      • "zip": "56307",
      • "unlocode": "US AL2",
      • "timezone": "America/Los_Angeles",
      • "ref": "warehouse_cn"
      },
    • "cargo_ready_date": "2019-05-30",
    • "destination_address": {
      • "_object": "/address",
      • "street_address": "325 Balboa St",
      • "street_address2": "Apt 6",
      • "city": "San Francisco",
      • "state": "CA",
      • "country": "United States of America",
      • "country_code": "US",
      • "zip": "94113",
      • "unlocode": "US SF3",
      • "timezone": "America/Los_Angeles",
      • "ref": "warehouse_us"
      },
    • "delivery_date": "2019-05-30",
    • "wants_export_customs_service": true,
    • "wants_import_customs_service": true,
    • "cargo": {
      • "volume": {
        },
      • "weight": {
        },
      • "marks_and_numbers": "Fragile",
      • "shipping_units": [
        ],
      • "contains_hazmat": true,
      • "contains_magnets": true,
      • "contains_other_dangerous_goods": true,
      • "contains_li_ion": true,
      • "contains_non_li_ion_battery": true,
      • "lithium_batteries_packing_types": [
        ]
      },
    • "special_instructions": "Handle carefully",
    • "metadata": {
      • "purchase_order": [
        ],
      • "sku": [
        ]
      },
    • "created_at": "2019-04-01T18:44:34.098Z",
    • "quote_status": null,
    • "user_email": "john@example.com"
    }
}

Retrieve a booking

Retrieves the details of a single booking.

Request
path Parameters
id
required
integer

The unique id for the booking to be retrieved

Responses
200

Success

Response Schema: application/json
_object
string
self
string
version
integer
object (Booking)
_object
string

Type of the object

id
integer

Unique identifier for the booking

name
string

The name of the booking

object (ShipmentRef)
status
string
Enum: "archived" "draft" "submitted" "booked" "shipment"
quote_status
string or null
Enum: "pending_quote" "sent_quote" "received_quote" "shared_quote" "expired_quote" "ready_to_share_quote" "accepted_quote" "received_quote" "rejected_quote" "requoted_quote" "archived_quote"
object (CompanyEntity)
object (CompanyEntity)
notify_party
string or null
Default: null
transportation_mode
string (TransportationMode)
Enum: "ocean" "air" "barge" "truck" "rail" "unknown_transportation" "ocean_air" "truck_intl" "warehouse_storage"
object or null (OceanBookingDetail)
object or null (AirBookingDetail)
object or null (TruckingBookingDetail)
object (Address)
cargo_ready_date
string <date>
object (Address)
delivery_date
string <date>
wants_export_customs_service
boolean

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

wants_import_customs_service
boolean

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

object (Cargo)

With cargo you have two options, detailed or simple. These are both expressed directly on the cargo object. For detailed cargo, shipping_units is required, and weight and volume is required in the cargo object or the shipping_units object. For simple cargo, shipping_units is required, but only one should be specified, and weight and volume are required in the cargo object.

special_instructions
string
object (BookingLineItemCollectionRef)
user_email
string

Email of the user who created the booking

created_at
string <date-time>
updated_at
string <date-time>
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.

400

error

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

Success

{
  • "_object": "/api/response",
  • "self": "https://api.flexport.com/bookings/1234",
  • "version": 2,
  • "data": {
    • "id": 2983,
    • "_object": "/booking",
    • "name": "PO 123456",
    • "shipper_entity": {
      • "_object": "/company_entity",
      • "id": 9281,
      • "name": "Zoomit",
      • "mailing_address": {
        },
      • "vat_numbers": [
        ]
      },
    • "consignee_entity": {
      • "_object": "/company_entity",
      • "id": 9281,
      • "name": "Zoomit",
      • "mailing_address": {
        },
      • "vat_numbers": [
        ]
      },
    • "notify_party": "Jane Doe; jane@example.com; 905-555-1234",
    • "transportation_mode": "ocean",
    • "ocean_booking": {
      • "_object": "/ocean/booking",
      • "is_lcl": false,
      • "container_counts": {
        },
      • "incoterm": "FOB",
      • "wants_pick_up_service": true,
      • "wants_delivery_service": false,
      • "origin_port": {
        },
      • "destination_port": {
        }
      },
    • "air_booking": null,
    • "trucking_booking": null,
    • "origin_address": {
      • "_object": "/address",
      • "street_address": "1641 Settlers Lane",
      • "street_address2": "STE 2918",
      • "city": "Albany",
      • "state": "MN",
      • "country": "United States of America",
      • "country_code": "US",
      • "zip": "56307",
      • "unlocode": "US AL2",
      • "timezone": "America/Los Angeles",
      • "ref": "my-address-ref"
      },
    • "cargo_ready_date": "2019-01-30",
    • "destination_address": {
      • "_object": "/address",
      • "street_address": "325 Balboa St",
      • "street_address2": "Apt 6",
      • "city": "San Francisco",
      • "state": "CA",
      • "country": "United States of America",
      • "country_code": "US",
      • "zip": "94113",
      • "unlocode": "US SF3",
      • "timezone": "America/Los Angeles",
      • "ref": "my-sf-ref"
      },
    • "delivery_date": "2019-02-22",
    • "wants_export_customs_service": true,
    • "wants_import_customs_service": true,
    • "cargo": {
      • "volume": {
        },
      • "weight": {
        },
      • "marks_and_numbers": "Very fragile",
      • "shipping_units": [
        ],
      • "contains_hazmat": false,
      • "contains_magnets": false,
      • "contains_other_dangerous_goods": false,
      • "contains_li_ion": true,
      • "contains_non_li_ion_battery": false,
      • "lithium_batteries_packing_types": [
        ]
      },
    • "special_instructions": "",
    • "metadata": {
      • "purchase_order": [
        ],
      • "sku": [
        ]
      },
    • "created_at": "2019-04-01T18:44:34.098Z",
    • "quote_status": "accepted_quote",
    • "user_email": "john@example.com"
    }
}
➔ Next to Commercial Invoices