report_shipment_ageing

Open and outstanding shipments by age bucket, grouped by an operational dimension.

When the question is "how long has this been sitting?", this tool answers it. Useful for ops triage and for surfacing carriers / merchants / locations whose shipments stall.

Parameters

Name	Type	Required	Description
tenantId	string	Yes	The tenant to report on.
group_by	string	Yes	Dimension to group aging buckets by — e.g. carrier, merchant, delivery_type.
shipment_type	string	No	forward or reverse.
select	string	No	json-mask syntax.
merchant / location_access / country_access	string | string[]	No	Standard scope filters.
tzoffset	string	No	Timezone offset.

group_by is required. Unlike most other reports, this one is a snapshot of currently open shipments — there's no from / to.

Returns

For each value of the group_by dimension, counts split by age bucket (e.g. under 1 day, 1–3 days, 3–7 days, over 7 days). The exact bucket boundaries are server-defined.

Example agent prompts

"Which carriers have the worst aging right now?"

report_shipment_ageing(
  tenantId="…",
  group_by="carrier"
)

"Show me how long reverse shipments are sitting, by merchant."

report_shipment_ageing(
  tenantId="…",
  shipment_type="reverse",
  group_by="merchant"
)

Related tools

• report_shipment_status_summary — same population sliced by status rather than age.
• report_failed_delivery_analysis — overlap when aging is caused by delivery failures.
• get_shipment_list — once the aging report flags a problem, drill into individual shipments.

Equivalent in the dashboard

Reports → Shipment Aging.