`get_shipment_list`

Updated May 19, 20262 min read

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

Date range is mandatory

Server-published guidance: creation_date_from and creation_date_to are required. Default to the last 30 days when the user doesn't specify. Maximum range is 90 days. Requests without a date range will fail.

Required parameters

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 parameters

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`	Surface 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.

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"
)

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 use get_shipment_list to compute counts you could fetch as a single number.

Notes

Reports tools are cheaper than this for aggregate questions. Use get_shipment_list for enumeration (which shipments?), not for counting (how many?).
Always pair with select in chat contexts to keep responses small.

get_shipment_list