get_shipment_list

List shipments. The workhorse search tool — every flow that operates on more than one shipment starts here.

Parameters

Required

Name	Type	Description
tenantId	string	The tenant.
creation_date_from	string	Start of the creation-date window.
creation_date_to	string	End of the creation-date window. Range cannot exceed 90 days.

Key optional filters

The full schema has 50+ filter fields. The agent rarely uses more than a handful at a time. Most common:

Name	Description
select	json-mask — see "Select" below. Strongly recommended.
shipment_type	forward or reverse. Default to forward for less ambiguity.
status / statuses	One or more statuses (e.g. error, delivered).
merchant	One or more merchant ids.
carrier / carrier_id	One or more carriers.
search_string + search_mode	Free-text search.
shipment_ids / shipment_refs	Look up specific ids/refs in bulk.
order_ref	Filter by order reference.
delivery_type / order_type	Filter by configured types.
pickup_country / dropoff_country	Geo filters.
error_or_missing_label	Return only error / label-missing shipments.
failed_delivery_attempt_reason	Filter by failure reason.
page / page_size / sort_by / sort_direction	Pagination + sort.

For the full filter set, inspect the live tool schema via tools/list.

Counting

To count shipments per value of a field instead of reading them one by one, pass agg_by. agg_by and sub_agg_by take the same values.

Name	Type	Required	Description
agg_by	array or string	No	Count matching shipments per value of this field. Use one of these values exactly as written; do not shorten or rename them: merchant (brand or store the shipment belongs to), carrier (delivery company), carrier_account_name (carrier account used to book the shipment), pickup_location (location the shipment is picked up from), pickup_country (country the shipment is picked up from), pickup_city (city the shipment is picked up from), pickup_state (state the shipment is picked up from), dropoff_location (location the shipment is delivered to), dropoff_country (country the shipment is delivered to), dropoff_city (city the shipment is delivered to), dropoff_state (state the shipment is delivered to), ship_zone (shipping zone), order_type (order type), delivery_type (delivery service type), payment_mode (how the customer pays, such as prepaid or cash on delivery), status (shipment status), reason_code (reason code of the latest status), label_status (label generation status), carrier_pickup_status (carrier pickup scheduling status), error_code (error code), error_source (where the error came from), error_type (error type), error_trigger (action that triggered the error), source_type (channel the shipment came from), creation_source_type (channel that created the shipment), update_source_type (channel that last updated the shipment). For a custom attribute, pass its name with a leading underscore, e.g. _region. Values: merchant, carrier, carrier_account_name, pickup_location, pickup_country, pickup_city, pickup_state, dropoff_location, dropoff_country, dropoff_city, dropoff_state, ship_zone, order_type, delivery_type, payment_mode, status, reason_code, label_status, carrier_pickup_status, error_code, error_source, error_type, error_trigger, source_type, creation_source_type, update_source_type.
sub_agg_by	string	No	Secondary breakdown within each agg_by value, returned as subAggBy. Needs agg_by set to a field, not a custom attribute. Use one of these values exactly as written; do not shorten or rename them: merchant (brand or store the shipment belongs to), carrier (delivery company), carrier_account_name (carrier account used to book the shipment), pickup_location (location the shipment is picked up from), pickup_country (country the shipment is picked up from), pickup_city (city the shipment is picked up from), pickup_state (state the shipment is picked up from), dropoff_location (location the shipment is delivered to), dropoff_country (country the shipment is delivered to), dropoff_city (city the shipment is delivered to), dropoff_state (state the shipment is delivered to), ship_zone (shipping zone), order_type (order type), delivery_type (delivery service type), payment_mode (how the customer pays, such as prepaid or cash on delivery), status (shipment status), reason_code (reason code of the latest status), label_status (label generation status), carrier_pickup_status (carrier pickup scheduling status), error_code (error code), error_source (where the error came from), error_type (error type), error_trigger (action that triggered the error), source_type (channel the shipment came from), creation_source_type (channel that created the shipment), update_source_type (channel that last updated the shipment). For a custom attribute, pass its name with a leading underscore, e.g. _region. Values: merchant, carrier, carrier_account_name, pickup_location, pickup_country, pickup_city, pickup_state, dropoff_location, dropoff_country, dropoff_city, dropoff_state, ship_zone, order_type, delivery_type, payment_mode, status, reason_code, label_status, carrier_pickup_status, error_code, error_source, error_type, error_trigger, source_type, creation_source_type, update_source_type.

Custom-attribute filters

Custom attributes use the _<key> prefix (e.g. _priority_tier=gold). Resolve attribute keys via get_custom_attributes first.

Operator filters

For non-equality matches, use the op. prefix on the value (e.g. op.is-not=delivered). Useful for "everything except X".

Select (json-mask) — almost always use it

Shipment payloads are large (parcels, items, addresses, audit fields, etc.). The agent should almost always pass select to trim the response. Examples:

select="shipments(shipment_id,creation_date,status,tracking_no),pagination"
select="shipments(shipment_id,dropoff(city,country),carrier),pagination"

For first-time exploration of an unfamiliar tenant, list one shipment without select to learn the structure, then trim.

Returns

{
  "shipments": [...],
  "pagination": { ... }
}

Use pagination to iterate through large result sets — but mind context size (each page can be hundreds of KB without select).

Example agent prompts

"Show me my five most recent shipments."

get_shipment_list(
  tenantId="…",
  creation_date_from="<30 days ago>",
  creation_date_to="<today>",
  page_size=5,
  sort_by="creation_date",
  sort_direction="desc",
  shipment_type="forward",
  select="shipments(shipment_id,creation_date,status,tracking_no,dropoff(city,country)),pagination"
)

"How many shipments are stuck in error this week?"

get_shipment_list(
  tenantId="…",
  creation_date_from="<7 days ago>",
  creation_date_to="<today>",
  status="error",
  page_size=50,
  select="shipments(shipment_id,status,creation_date),pagination"
)

Related tools

• get_shipment — fetch a single shipment in detail once the list narrows it down.
• get_shipment_activity — activity timeline for a chosen shipment.
• Reports tools — for aggregated questions, prefer report_shipment_status_summary etc. Don't count by paging through get_shipment_list results; use agg_by or a report for a single number.

Notes

• Reports tools are cheaper than this for aggregate questions. Use get_shipment_list for enumeration (which shipments?). For counting (how many?), pass agg_by or use a report; never page through results to count.
• Always pair with select in chat contexts to keep responses small.