report_return_analytics

Return stats, breakdowns, status mix, item-level top products, and history for customer return requests.

The right tool when the question is about returns — return rates, top return reasons, top returned products, return-status breakdowns over time.

Parameters

Name	Type	Required	Description
tenantId	string	Yes	The tenant to report on.
from	string	Yes	Range start.
to	string	Yes	Range end.
milestone	string	No	Return lifecycle date field — e.g. created, collection_window_*.
group_by	string	No	Build the history table by — units, status, return_reason, etc.
bucket_size	string	No	Date histogram interval — hour, day, week, month.
select	string	No	json-mask syntax.
merchant / location_access / country_access	string | string[]	No	Standard scope filters.
tzoffset	string	No	Timezone offset.

Returns

A composite — totals, breakdown(s), status mix, item-level top products, and a bucketed history series.

Example agent prompts

"What are the top return reasons this quarter?"

report_return_analytics(
  tenantId="…",
  from="2026-02-01",
  to="2026-04-30",
  group_by="return_reason"
)

"Daily return units over the last 30 days."

report_return_analytics(
  tenantId="…",
  from="2026-04-07",
  to="2026-05-07",
  group_by="units",
  bucket_size="day"
)

Related tools

• report_product_performance — forward-side complement; pair when comparing forward vs reverse movement.
• report_shipment_status_summary (with shipment_type="reverse") — current snapshot of in-flight reverse shipments.

Equivalent in the dashboard

Reports → Returns History.