report_shipment_status_summary

Aggregated shipment counts by current status, with optional subgrouping. Useful for a filtered operational snapshot rather than a single shipment lookup.

Parameters

Name	Type	Required	Description
tenantId	string	Yes	The tenant to report on.
select	string	No	json-mask syntax to trim the response.
merchant	string | string[]	No	Restrict to one or more merchants.
location_access	string | string[]	No	Restrict by accessible location ids.
country_access	string | string[]	No	Restrict by country code.
shipment_type	string	No	forward or reverse — defaults to forward.
milestone	string	No	Filter by milestone (e.g. created, booked, shipped).
sub_group_by	string	No	Optional secondary breakdown for each shipment status bucket. 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.
tzoffset	string	No	Timezone offset for date calculations.

This tool also accepts the broad shipment-filter set (carrier, status, date ranges, custom-attribute filters) used elsewhere — see get_shipment_list for the full list, which it shares.

Returns

A counts-by-status object. With sub_group_by, each status bucket contains a nested breakdown by the requested dimension.

Example agent prompts

"How many shipments are currently in each status?"

report_shipment_status_summary(tenantId="…")

"Show me the status breakdown by carrier for last week's reverse shipments."

report_shipment_status_summary(
  tenantId="…",
  shipment_type="reverse",
  sub_group_by="carrier",
  creation_date_from="…",
  creation_date_to="…"
)

Related tools

• report_dashboard_summary — fixed 30-day operational snapshot; broader than just status counts.
• report_shipment_volume_trend — trend over time rather than current snapshot.
• report_shipment_ageing — same data, sliced by how long shipments have been in each state.

Equivalent in the dashboard

Reports → Shipment Status Summary.