Returns a list of bookings.
Success
{- "_object": "/api/response",
- "version": 2,
- "data": {
- "_object": "/api/collections/paginated",
- "next": null,
- "data": [
- {
- "_object": "/booking",
- "id": 123,
- "name": "PO 123",
- "shipper_entity": {
- "_object": "/company_entity",
- "id": 9281,
- "name": "Zoomit V2",
- "ref": "zoomit-us",
- "mailing_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": "USAL2",
- "timezone": "America/Los_Angeles",
- "ref": "my-address-ref"
}, - "vat_numbers": [
- {
- "_object": "company_entity/vat_number",
- "country_code": "GB",
- "number": "GB 123746396"
}
]
}, - "consignee_entity": {
- "_object": "/company_entity",
- "id": 9281,
- "name": "Zoomit",
- "mailing_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": "USAL2",
- "timezone": "America/Los_Angeles",
- "ref": "my-address-ref"
}, - "ref": "zoomit_ref",
- "vat_numbers": [
- {
- "_object": "company_entity/vat_number",
- "country_code": "US",
- "number": "US 123746396"
}
]
}, - "notify_party": null,
- "ocean_booking": {
- "_object": "/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": [
- {
- "description": "Watches",
- "hs_code": {
- "_object": "/hs_code",
- "description": null,
- "code": "9101.00",
- "country_code": "US"
}, - "description_for_export_customs": "手表",
- "description_for_export_customs_locale": "zh_CN"
}
], - "origin_port": {
- "_object": "/place",
- "name": "Shenzhen, China",
- "address": {
- "_object": "/address",
- "street_address": "123 Queen St",
- "street_address2": null,
- "city": "Shanghai",
- "state": null,
- "country": "China",
- "country_code": "CN",
- "zip": null,
- "unlocode": "CNSZP",
- "timezone": "America/Los_Angeles",
- "ref": null
}, - "details": [
- {
- "_object": "/trucking/port",
- "port_code": "57035"
}, - {
- "_object": "/ocean/port",
- "port_code": "57035"
}
]
}, - "destination_port": {
- "_object": "/place",
- "name": "Long Beach, Los Angeles, California",
- "address": {
- "_object": "/address",
- "street_address": "123 Queen St",
- "street_address2": null,
- "city": "Los Angeles",
- "state": null,
- "country": "United States",
- "country_code": "US",
- "zip": null,
- "unlocode": "USLA",
- "timezone": "America/Los_Angeles",
- "ref": null
}, - "details": [
- {
- "_object": "/trucking/port",
- "port_code": "2704"
}, - {
- "_object": "/ocean/port",
- "port_code": "2704"
}
]
}, - "wants_pickup_service": false,
- "wants_delivery_service": false
}, - "cargo_ready_date": "2019-06-30",
- "delivery_date": "2019-07-31",
- "wants_export_customs_service": true,
- "wants_import_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": [
- {
- "name": "Watches",
- "volume": {
- "_object": "/quantity/volume",
- "value": 472.62,
- "unit": "cbm"
}, - "weight": {
- "_object": "/quantity/weight",
- "value": 2300.4,
- "unit": "kg"
}, - "height": {
- "_object": "/quantity/length",
- "value": 472.62,
- "unit": "cm"
}, - "length": {
- "_object": "/quantity/length",
- "value": 472.62,
- "unit": "cm"
}, - "width": {
- "_object": "/quantity/length",
- "value": 472.62,
- "unit": "cm"
}, - "count": 9,
- "atomic_count": 9,
- "unit_type": "carton"
}
], - "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",
- "created_at": "2019-04-01T18:44:34.098Z",
- "updated_at": "2019-04-01T18:44:34.098Z",
- "metadata": {
- "purchase_order": [
- "12345"
], - "sku": [
- "abc123"
]
}, - "quote_status": "accepted_quote",
- "user_email": "john@example.com"
}
]
}
}Create and return a booking.
When a request fails validation, the API returns a 400 with an error object. error.code is invalid_param for malformed/invalid input or bad_request for business-rule violations, and error.message describes the specific problem. The table below lists the errors you may encounter, their cause, and how to resolve them.
| Error message | Code | Cause | Suggested fix |
|---|---|---|---|
<field>_ref does not exist in your network (e.g. shipper_entity_ref, consignee_entity_ref) |
invalid_param |
The company entity ref does not resolve to an entity in your network. | Use an entity ref that exists in your Network and is visible to your account. |
origin_address_ref does not exist in your network / destination_address_ref does not exist in your network |
invalid_param |
The address/location ref is not a valid location in your network. | Use a location ref that exists in your Network (create it first if needed). |
Missing property <field> |
invalid_param |
A required field is absent from the request body (e.g. name, consignee_entity_ref, wants_pickup_service, product_descriptions). |
Include all required fields in the request. |
Null values are not allowed for property <field> |
invalid_param |
A required field was sent as null. |
Provide a non-null value for the field. |
Unknown attribute(s): <name> (e.g. origin_port) |
invalid_param |
The request used a field name the API does not recognize. | Use the documented field names (e.g. origin_port_loc_code / origin_port_us_cbp_port_code), not custom names. |
Container count is required for ocean FCL shipments |
bad_request |
An ocean FCL booking (is_lcl: false) was submitted without container counts. |
Provide container_counts (e.g. forty_ft: 1) for FCL ocean bookings. |
No port found for port_of_loading / No port found for port_of_unloading |
invalid_param |
The supplied port code does not match a known port. | Use a valid UN/LOCODE or US CBP port code for the port. |
Only one code can be specified for a port |
invalid_param |
Both a LOCODE and a US CBP code were sent for the same port. | Specify exactly one port code per port. |
Invalid HS code / Invalid HS code - Must be a string |
invalid_param |
A product_descriptions[].hs_code is unrecognized or not a string. |
Provide a valid HS code as a string (e.g. "9403.60"). |
Invalid enum value provided for: incoterm |
invalid_param |
The incoterm is not one of the accepted values. |
Use a valid incoterm (EXW, FOB, FAS, FCA, CPT, CFR, CIF, CIP, DAT, DAP, DDP, DPU). |
Invalid payment_terms <value>; expected one of prepaid,collect |
invalid_param |
The trucking payment_terms value is invalid. |
Use prepaid or collect. |
For these values of pickup and delivery service <location(s)> is/are required |
bad_request |
The pickup/delivery selection requires origin/destination address or port that was not provided. | Provide the required origin/destination address and port for your pickup/delivery selection. |
shipping_unit must be provided |
invalid_param |
Cargo has no shipping units. | Include at least one shipping unit in cargo.shipping_units. |
Count and atomic count should be equal for unit type of <type> |
bad_request |
For non-pallet units, count does not equal atomic_count. |
Set count equal to atomic_count for non-pallet unit types. |
With incoterms <X> the <role> must be a Flexport client |
bad_request |
The paying party (per incoterm) is not a Flexport client. | Ensure the incoterm-designated paying party is a Flexport client, or contact your Flexport team. |
The created booking
| _object | string | ||||||||||||||||||||||||||||||||||||||||||||||||||||
| self | string | ||||||||||||||||||||||||||||||||||||||||||||||||||||
| version | integer | ||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Booking) | |||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||
error
{- "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": [
- {
- "description": "Watches",
- "hs_code": "9101.00",
- "description_for_export_customs": "手表",
- "description_for_export_customs_locale": "zh_CN"
}
], - "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": [
- {
- "name": "Watches",
- "volume": {
- "_object": "/quantity/volume",
- "value": 472.62,
- "unit": "cbm"
}, - "weight": {
- "_object": "/quantity/weight",
- "value": 2300.4,
- "unit": "kg"
}, - "height": {
- "_object": "/quantity/length",
- "value": 472.62,
- "unit": "cm"
}, - "length": {
- "_object": "/quantity/length",
- "value": 472.62,
- "unit": "cm"
}, - "width": {
- "_object": "/quantity/length",
- "value": 472.62,
- "unit": "cm"
}, - "count": 9,
- "atomic_count": 9,
- "unit_type": "carton"
}
], - "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"
}{- "_object": "/api/response",
- "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": {
- "_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"
}, - "vat_numbers": [
- {
- "_object": "company_entity/vat_number",
- "country_code": "US",
- "number": "US 123746396"
}
]
}, - "consignee_entity": {
- "_object": "/company_entity",
- "id": 9281,
- "name": "Zoomit",
- "ref": "self",
- "mailing_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"
}, - "vat_numbers": [
- {
- "_object": "company_entity/vat_number",
- "country_code": "US",
- "number": "US 123746396"
}
]
}, - "notify_party": null,
- "transportation_mode": "ocean",
- "ocean_booking": {
- "_object": "/ocean/booking",
- "is_lcl": false,
- "container_counts": {
- "_object": "/container_counts",
- "twenty_ft": 2,
- "forty_ft": 3,
- "forty_ft_hc": 4,
- "forty_five_ft_hc": 5
}, - "incoterm": "FOB",
- "wants_pick_up_service": false,
- "wants_delivery_service": false,
- "origin_port": {
- "_object": "/place",
- "name": "Shenzhen, China",
- "address": {
- "_object": "/address",
- "street_address": "123 Queen St",
- "street_address2": null,
- "city": "Shanghai",
- "state": null,
- "country": "China",
- "country_code": "CN",
- "zip": null,
- "unlocode": "CNSZP",
- "timezone": "America/Los_Angeles",
- "ref": "shanghai-ref"
}, - "details": [
- {
- "_object": "/trucking/port",
- "port_code": "57035"
}, - {
- "_object": "/ocean/port",
- "port_code": "57035"
}
]
}, - "destination_port": {
- "_object": "/place",
- "name": "Long Beach, Los Angeles, California",
- "address": {
- "_object": "/address",
- "street_address": "123 Queen St",
- "street_address2": null,
- "city": "Los Angeles",
- "state": null,
- "country": "United States",
- "country_code": "US",
- "zip": null,
- "unlocode": "USLA",
- "timezone": "America/Los_Angeles",
- "ref": "la-address-ref"
}, - "details": [
- {
- "_object": "/trucking/port",
- "port_code": "2704"
}, - {
- "_object": "/ocean/port",
- "port_code": "2704"
}
]
}, - "product_descriptions": [
- {
- "_object": "/bookings/product_descriptions",
- "description": "Watches",
- "description_for_export_customs": "手表",
- "description_for_export_customs_locale": "zh_CN",
- "hs_code": {
- "_object": "/hs_code",
- "description": "N-Butyl-2,2,6,6-tetramethylpiperidin-4-amine (CAS No. 36177-92-1) (provided for in subheading 2933.39.91)",
- "code": "9101.00",
- "country_code": "US"
}
}
]
}, - "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": {
- "_object": "/quantity/volume",
- "value": 472.62,
- "unit": "cbm"
}, - "weight": {
- "_object": "/quantity/weight",
- "value": 2300.4,
- "unit": "kg"
}, - "marks_and_numbers": "Fragile",
- "shipping_units": [
- {
- "name": "Watches",
- "volume": {
- "_object": "/quantity/volume",
- "value": 472.62,
- "unit": "cbm"
}, - "weight": {
- "_object": "/quantity/weight",
- "value": 2300.4,
- "unit": "kg"
}, - "height": {
- "_object": "/quantity/length",
- "value": 472.62,
- "unit": "cm"
}, - "length": {
- "_object": "/quantity/length",
- "value": 472.62,
- "unit": "cm"
}, - "width": {
- "_object": "/quantity/length",
- "value": 472.62,
- "unit": "cm"
}, - "count": 9,
- "atomic_count": 9,
- "unit_type": "carton"
}
], - "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"
]
}, - "created_at": "2019-04-01T18:44:34.098Z",
- "quote_status": null,
- "user_email": "john@example.com"
}
}Retrieves the details of a single booking.
Success
| _object | string | ||||||||||||||||||||||||||||||||||||||||||||||||||||
| self | string | ||||||||||||||||||||||||||||||||||||||||||||||||||||
| version | integer | ||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Booking) | |||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||
error
Success
{- "_object": "/api/response",
- "version": 2,
- "data": {
- "id": 2983,
- "_object": "/booking",
- "name": "PO 123456",
- "shipper_entity": {
- "_object": "/company_entity",
- "id": 9281,
- "name": "Zoomit",
- "mailing_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"
}, - "vat_numbers": [
- {
- "_object": "company_entity/vat_number",
- "country_code": "US",
- "number": "US 123746396"
}
]
}, - "consignee_entity": {
- "_object": "/company_entity",
- "id": 9281,
- "name": "Zoomit",
- "mailing_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"
}, - "vat_numbers": [
- {
- "_object": "company_entity/vat_number",
- "country_code": "US",
- "number": "US 123746396"
}
]
}, - "notify_party": "Jane Doe; jane@example.com; 905-555-1234",
- "transportation_mode": "ocean",
- "ocean_booking": {
- "_object": "/ocean/booking",
- "is_lcl": false,
- "container_counts": {
- "_object": "/container_counts",
- "twenty_ft": 1,
- "forty_ft": 2,
- "forty_ft_hc": 4,
- "forty_five_ft_hc": 8
}, - "incoterm": "FOB",
- "wants_pick_up_service": true,
- "wants_delivery_service": false,
- "origin_port": {
- "_object": "/place",
- "name": "Shanghai, China",
- "address": {
- "_object": "/address",
- "street_address": "123 Queen St",
- "street_address2": null,
- "city": "Shanghai",
- "state": null,
- "country": "China",
- "country_code": "CN",
- "zip": null,
- "unlocode": "CNSHA",
- "timezone": "China/Shanghai",
- "ref": "my-shanghai-ref"
}, - "details": [
- {
- "_object": "/trucking/port",
- "port_code": "57035"
}, - {
- "_object": "/ocean/port",
- "port_code": "57035"
}
]
}, - "destination_port": {
- "_object": "/place",
- "name": "Shanghai, China",
- "address": {
- "_object": "/address",
- "street_address": "123 Queen St",
- "street_address2": null,
- "city": "Shanghai",
- "state": null,
- "country": "China",
- "country_code": "CN",
- "zip": null,
- "unlocode": "CNSHA",
- "timezone": "China/Shanghai",
- "ref": "my-shanghai-ref"
}, - "details": [
- {
- "_object": "/trucking/port",
- "port_code": "57035"
}, - {
- "_object": "/ocean/port",
- "port_code": "57035"
}
]
}
}, - "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": {
- "_object": "/quantity/volume",
- "value": 472.62,
- "unit": "cbm"
}, - "weight": {
- "_object": "/quantity/weight",
- "value": 2300.4,
- "unit": "kg"
}, - "marks_and_numbers": "Very fragile",
- "shipping_units": [
- {
- "name": "Airplanes",
- "volume": {
- "_object": "/quantity/volume",
- "value": 472.62,
- "unit": "cbm"
}, - "weight": {
- "_object": "/quantity/weight",
- "value": 2300.4,
- "unit": "kg"
}, - "height": {
- "_object": "/quantity/length",
- "value": 472.62,
- "unit": "cm"
}, - "length": {
- "_object": "/quantity/length",
- "value": 472.62,
- "unit": "cm"
}, - "width": {
- "_object": "/quantity/length",
- "value": 472.62,
- "unit": "cm"
}, - "count": 3,
- "atomic_count": 9,
- "unit_type": "carton"
}
], - "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": [
- "contained_in_equipment"
]
}, - "special_instructions": "",
- "metadata": {
- "purchase_order": [
- "12345"
], - "sku": [
- "abc123"
]
}, - "created_at": "2019-04-01T18:44:34.098Z",
- "quote_status": "accepted_quote",
- "user_email": "john@example.com"
}
}