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	Dimension to build the history table by (default: units). Use one of these values exactly as written; do not shorten or rename them: units (returned item SKU), return_reason (reason given for the return), resolution (resolution chosen, such as refund or exchange), return_item_condition (condition of the returned item). Values: units, return_reason, resolution, return_item_condition.
breakdown_by	string	No	Dimension to use for the main return breakdown (default: return_reason). Use one of these values exactly as written; do not shorten or rename them: units (returned item SKU), return_reason (reason given for the return), resolution (resolution chosen, such as refund or exchange), return_item_condition (condition of the returned item), status (return request status), merchant (brand or store the return belongs to), pickup_country (country the return is collected from), pickup_city (city the return is collected from), pickup_state (state the return is collected from). Values: units, return_reason, resolution, return_item_condition, status, merchant, pickup_country, pickup_city, pickup_state.
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",
  breakdown_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.