MCP Tools

Pagination cursor. The end_cursor from the previous response retrieves the next page.

ETA range — filter by arrival at the first port of arrival for customs clearance. This is often NOT the same date as the shipment's final destination arrival — an inland leg after this port can add days to weeks. Either from or to may be omitted for an open-ended range.

Filter by delivery at the final destination. For shipments not yet delivered, the date falls back to scheduled and then estimated delivery, so future ranges are supported. Either from or to may be omitted for an open-ended range.

The date used by this filter is not returned and cannot be calculated from the response. The DESTINATION route stop's arrival_at is an approximation and may differ. Container last-free-day values are demurrage or detention deadlines, not delivery dates. Results are ordered by the delivery date used by the filter, most distant first; the soonest deliveries in a future range may fall beyond the page limit. Unlike arrival_range, this filter includes delivery after any inland leg from the arrival port.

Filter by shipments that have at least one container whose demurrage last free day falls within this date range (inclusive). Both from and to are required.

ETD range — filter by port-of-loading departure date. Either from or to may be omitted for an open-ended range.

Filter by shipments that have at least one container whose detention last free day falls within this date range (inclusive). Both from and to are required.

Number of results to return. Defaults to 10, maximum 100.

Filter to shipments matching all provided flags (AND, not OR): HAS_OPEN_TASK matches at least one open client work item; HAS_ACTIVE_EXCEPTION matches at least one open operational exception in a client-facing category; HAS_CUSTOMS_HOLD matches at least one customs declaration flagged by an agency.

HAS_CUSTOMS_HOLD includes agency reviews, which do not block cargo, and misses holds recorded only as operational exceptions. Declaration dispositions are available in customs[].agency_statuses[].disposition. A complete search for held shipments also requires a separate HAS_ACTIVE_EXCEPTION query and a union of the results, since flags are combined with AND. Relevant exceptions have the category "Customs & regulatory holds" and an open status. Exception history includes RESOLVED and CANCELED entries; those are not current holds. The exception type distinguishes exams or orders to hold cargo from reviews or confirmations.

Filter by whether the shipment is administratively complete. False restricts results to active, in-progress shipments; true returns finished/delivered shipments; omitting the field returns both. This is tracked separately from statuses, so it is combined with AND rather than implied: a shipment can sit at FINAL_DESTINATION and still not be complete.

Filter by transportation mode. Values match track_shipment's mode field (OCEAN_FCL, OCEAN_LCL, AIR, TRUCK_FTL, TRUCK_LTL). Returns shipments matching any of the provided modes.

Flexport FLEX-ID to search for (e.g. "FLEX-1234567"). Exact match only — unlike name and tag, an ID with no exact match returns no results rather than a close (fuzzy) one. Mutually exclusive with name and tag — supply exactly one.

Shipment name to search for. Matches exactly when possible, otherwise returns close (fuzzy) matches. Mutually exclusive with flex_id and tag — supply exactly one.

Cargo details. For ocean_fcl, provide container_info with container counts. For ocean_lcl or air, provide loose_cargo_info with total_weight_kg and total_volume_cbm; for air, also provide shipping_units with dimensions to detect oversized cargo. Must include dangerous_goods screening.

ISO date when cargo is ready at origin, e.g. 2025-09-01.

Destination address — a Flexport FID string beginning 'flx::', not a numeric ID. Required when freight_type is port_to_door or door_to_door; also accepted for *_to_port to let the backend resolve the nearest port from the address coordinates. Use the address_fid from a network_search_addresses result for an address already onboarded in Flexport, or the commerce_address_fid from a network_search_google_addresses result for a general address (e.g. city, postal code, street address).

Destination port — a numeric ID, taken from the port_id field of a network_search_ports result. Used when freight_type is port_to_port or door_to_port and a specific port is specified. Mutually exclusive with destination_commerce_address_fid for PORT.

Service scope controlling pickup and delivery: port_to_port, port_to_door, door_to_port, or door_to_door. Door service requires an address. Port service accepts either a port ID or an address whose coordinates the backend uses to find the nearest port.

Trade term governing cost/risk split: EXW, FCA, FAS, FOB, CFR, CIF, CPT, CIP, DAP, DAT, DPU, or DDP.

Origin address — a Flexport FID string beginning 'flx::', not a numeric ID. Required when freight_type is door_to_port or door_to_door; also accepted for port_to_* to let the backend resolve the nearest port from the address coordinates. Use the address_fid from a network_search_addresses result for an address already onboarded in Flexport, or the commerce_address_fid from a network_search_google_addresses result for a general address (e.g. city, postal code, street address).

Origin port — a numeric ID, taken from the port_id field of a network_search_ports result. Used when freight_type is port_to_port or port_to_door and a specific port is specified. Mutually exclusive with origin_commerce_address_fid for PORT.

Additional detention free days beyond the base free days included in the rate, corresponding to an add-on tier from detention_addon_options in the search result. Equal to the chosen tier's total_free_days minus the base free days. Omit (null) to price with only the base free days included in the rate.

Identifier for the offering bundle to evaluate, taken from the item_snapshot_id field of a rates_search_instant_price result.

search_snapshot_id from the rates_search_instant_price result. Carries the search form data (cargo, routing, incoterm, dates) used to reconstruct the pricing request.

Whether to include Flexport export customs service in the evaluated price. True if the service is force-included (force_included=true) or was selected as an add-on, false otherwise.

Whether to include Hong Kong trade declaration service in the evaluated price. True if the service is force-included (force_included=true) or was selected as an add-on, false otherwise.

Whether to include Flexport import customs service in the evaluated price. True if the service is force-included (force_included=true) or was selected as an add-on, false otherwise.

Whether to include in-bond transit in the evaluated price. True if the service is force-included (force_included=true) or was selected as an add-on, false otherwise.

Cargo details for the booking. Required when booking via client_rate_id, and must match the rate's transportation mode (container_info for ocean_fcl, loose_cargo_info for ocean_lcl or air). Ignored when booking via search_snapshot_id/item_snapshot_id, since cargo is reused from the original search snapshot so the booking matches what was priced.

Cargo ready date in YYYY-MM-DD format. Required when booking via client_rate_id. Ignored when booking via search_snapshot_id/item_snapshot_id — the date from the original search is reused so the booking matches what was priced.

Optional note from client

Numeric client rate ID to book. No currently available tool returns this value; it must be supplied directly. Alternatively, a rate can be identified by search_snapshot_id and item_snapshot_id from rates_search_instant_price. Exactly one of these two modes is required.

Optional description of products being shipped

Additional detention free days in snapshot mode (search_snapshot_id and item_snapshot_id). Ignored for client_rate_id and does not purchase an add-on in that mode. Equal to the selected detention_addon_options[].total_free_days minus detention_base_free_days from the search result; for example, 11 total minus 4 base equals 7 additional days. Must match the additional days passed to rates_evaluate_total_price_from_instant_price_search. Omit to book with the base free days.

Item snapshot ID identifying which rates_search_instant_price result to book. Must be paired with search_snapshot_id.

Optional name/description for the booking

Required in snapshot mode. Must be the price_confirmation_token returned by rates_evaluate_total_price_from_instant_price_search for the same search_snapshot_id, item_snapshot_id, wants_* flags, and detention_addon_free_days being booked; this endpoint recomputes the same selection fingerprint and rejects the booking if it does not match. This is a workflow-consistency guard, not an authentication credential. Ignored for client_rate_id mode.

Search snapshot ID from a prior rates_search_instant_price call. Must be paired with item_snapshot_id. Exactly one of this pair or client_rate_id is required.

SSAT sailing week preference. Required in snapshot mode when the search result includes nac_allocation, using the year and week of a feasible allocation week. Each week includes week_date_range and available_allocation; nac_allocation.requested_teus contains the shipment's required TEUs. Omitted when nac_allocation is absent.

Whether to include Flexport export customs service. Must be true if it is force_included=true on the search result's addon_service_options, and should be kept in sync with the value passed to rates_evaluate_total_price_from_instant_price_search. Snapshot mode only (search_snapshot_id + item_snapshot_id); ignored for client_rate_id. Fails if this rate does not offer or allow export customs.

Whether to include Hong Kong trade declaration service. Must be true if it is force_included=true on the search result's addon_service_options, and should be kept in sync with the value passed to rates_evaluate_total_price_from_instant_price_search. Snapshot mode only (search_snapshot_id + item_snapshot_id); ignored for client_rate_id. Fails if this rate does not offer or allow Hong Kong trade declaration.

Whether to include Flexport import customs service. Must be true if it is force_included=true on the search result's addon_service_options, and should be kept in sync with the value passed to rates_evaluate_total_price_from_instant_price_search. Snapshot mode only (search_snapshot_id + item_snapshot_id); ignored for client_rate_id. Fails if this rate does not offer or allow import customs.

Whether to include in-bond transit. Must be true if it is force_included=true on the search result's addon_service_options, and should be kept in sync with the value passed to rates_evaluate_total_price_from_instant_price_search. Snapshot mode only (search_snapshot_id + item_snapshot_id); ignored for client_rate_id. Fails if this rate does not offer or allow in-bond transit.

Payload fingerprint returned by a previous preflight of these exact booking details. Reuse the token unchanged on retry; any change to the booking details invalidates it.

HS commodity lines for the shipment. Codes can be found via network_search_hs_codes. Exact duplicate code/description pairs are rejected rather than merged. At least one complete entry is required for a non-trucking booking.

Total cargo measurements, packaging, piece counts, and dangerous-goods screening answers. This tool supports only false for every dangerous-goods field.

Date in YYYY-MM-DD format when the supplier expects the cargo to be packed and available for pickup or handoff.

Consignee company entity numeric ID. Obtained from an active entity with the CONSIGNEE role via network_search_company_entities, using its company_entity_id field.

Whether the cargo contains strategic or export-controlled goods: yes, no, or notsure. Relevant when either the loading or unloading port is in Hong Kong. The eccn_codes field is required when yes.

Supplier's requested target arrival date at the final destination in YYYY-MM-DD format. This is a planning target, not a carrier-confirmed ETA or delivery appointment.

Plain-language description of the products being shipped.

Comma-separated Export Control Classification Numbers for controlled goods, for example '3A001, 5A002'.

Estimated total merchandise value that will appear on the commercial invoice, in whole USD. This is cargo value, not freight cost, customs duty, or insurance premium.

Optional booking note or handling instruction for Flexport operations.

Optional booking shipment tags configured by the consignee. The tool validates supplied tags against the consignee's active booking metadata schema. Provide an empty list when no tags should be added.

Supplier-facing reference name used to identify this booking or shipment.

Party to notify when the cargo arrives. Required when notify_party_same_as_consignee is false.

Whether the notify party is the consignee. When true, omit notify_party. When false, provide notify_party.

Cargo's origin location, normally the supplier facility where cargo is available for pickup — a Flexport FID string beginning 'flx::', NOT a numeric ID. Obtained from the address_fid field returned by network_search_addresses. If no matching address exists, it must be added in Flexport first.

Optional pickup instructions or access details for the origin location. Provide only when pickup service is selected.

Localized-language pickup address, primarily the Chinese version of a China origin address. Provide only when pickup service is selected.

Whether additional labor is needed to help load or unload cargo at pickup. Provide only when pickup service is selected.

Whether previously returned non-blocking Stoplight policy violations have been reviewed and confirmed. False on the initial attempt.

Whether the applicable service choices (pickup, delivery, export customs, and, where relevant, Hong Kong trade declaration) have been confirmed. Truck is always pickup and delivery door to door. For air and ocean, pickup defaults to true for EXW and FCA Factory and false for other incoterms; delivery defaults false. Export customs defaults true only for EXW. Hong Kong trade declaration is relevant when the origin address or loading port is in Hong Kong.

Supplier company entity numeric ID. Obtained from an active entity with the SHIPPER role via network_search_company_entities, using its company_entity_id field.

Whether Flexport should handle export customs clearance. Defaults to true for EXW and false for other incoterms.

Cargo ready date in YYYY-MM-DD format

Destination address, specified as a Flexport FID string beginning with 'flx::' (not a numeric ID). Obtained from the address_fid field returned by network_search_addresses, or the commerce_address_fid field returned by network_search_google_addresses if no matching address is found.

Destination port, specified as a numeric ID. Obtained from the port_id field returned by network_search_ports.

Freight type: port_to_port, port_to_door, door_to_port, door_to_door

Incoterm: EXW, FCA, FOB, CIF, CIP, CFR, CPT, DAP, DAT, DDP, DPU, FAS

Optional free-text note for the Flexport account team, such as cargo profile (commodity type, dimensions, weight, hazmat status, temperature requirements), target price or budget, expected shipment volume (shipments or TEUs per month/year), or other special requirements.

Contract type: HEDGE_FAK (spot/FAK rate, resolved in ~2 business days) or LONG_NAC (Named Account Contract, AE will communicate timeline). Omit if unspecified — defaults to HEDGE_FAK.

Origin address, specified as a Flexport FID string beginning with 'flx::' (not a numeric ID). Obtained from the address_fid field returned by network_search_addresses, or the commerce_address_fid field returned by network_search_google_addresses if no matching address is found.

Origin port, specified as a numeric ID. Obtained from the port_id field returned by network_search_ports.

Network addresses to filter by — Flexport FID strings beginning 'flx::', not numeric IDs. Matches either origin or destination. Obtained from the address_fid field returned by network_search_addresses.

Pagination cursor. Pass end_cursor from the previous response to get the next page.

Number of results to return. Defaults to 10, maximum 100.

Freight modes to include: OCEAN, AIR, or TRUCK.

Ports to filter by — numeric IDs from the port_id field returned by network_search_ports. Matches either origin or destination.

Quote request name or FLEX-ID. Omit to list matching quote requests.

User IDs of specific submitters to filter by, obtained from the user_id field returned by list_active_company_users. Omit to return requests from all visible submitters.