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 finding 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 the ageing buckets by. 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.
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.