Breakdown

A comprehensive list of the breakdown query keys, allowed fields values, and operators for the return resource

To perform a breakdown query on the return resource send a POST request to the /returns/breakdown endpoint specifying in the payload the query keys and filter parameters like in the generic example below:

{
  "breakdown": {
    "by": "...",
    "field": "...",
    "operator": "...",
    "condition": { ... },
    "sort": "...",
    "limit": ...,
    "breakdown": {
      "by": "...",
      "field": "...",
      "operator": "...",
      "condition": { ... },
      "sort": "...",
      "limit": ...
    }
  },
  "filter": { ... }
}

Please find more information on how breakdown queries work here.

Query keys

These are the keys you need to set when performing a breakdown query:

Key	Type	Required	Description	Values
by	String		The field you want the results of the query aggragated by.	See the related table to check the full list of valid values for this key.
field	String		The field you want the metrics or statistics computed on.	See the related table to check the full list of valid values for this key.
operator	String		The computing operator.	See the related table to check the full list of valid operators based on the value you assigned to the field key.
condition	Object		An additional constraint to fine-tune the set of records shown in the response, applied to the computed results of the query. It is available for operators that return single numeric (float or integer) values.	One of: "eq": ... "ne": ... "gt": ... "gte": ... "lt": ... "lte": ... "gt_lt": [...] "gte_lte": [...] "gte_lt": [...] "gt_lte": [...] (default is no condition).
sort	String		The way you want the results of the query to be sorted.	One of asc or desc (default is desc).
limit	Integer		The maximum number of records shown in the response.	Default is 10, max is 100.
breakdown	Object		The optional nested breakdown.	See the related table to check full list of fobidden values for the nested breakdown by key, based on the value you assigned to the parent breakdown by key.

Operators and field values

These are the valid values you can specify for the field key of the breakdown query and the related valid operators, based on that key:

Value	Operators
customer.id	value_count
customer.email	value_count
customer.group_name	value_count
destination_address.business	value_count
destination_address.city	value_count
destination_address.country_code	value_count
destination_address.geocoded	value_count
destination_address.localized	value_count
destination_address.state_code	value_count
destination_address.zip_code	value_count
origin_address.business	value_count
origin_address.city	value_count
origin_address.country_code	value_count
origin_address.geocoded	value_count
origin_address.localized	value_count
origin_address.state_code	value_count
origin_address.zip_code	value_count
market.id	cardinality value_count
market.number	cardinality value_count
return.number	value_count
return.reference	value_count
return.reference_origin	value_count
return.status	value_count
return.id	cardinality value_count
return.order_id	value_count
return.skus_count	avg max min sum stats
return_line_items.quantity	avg max min sum stats
return_line_items.line_item_id	value_count
return_line_items.line_item_code	value_count
return_line_items.line_item_item_type	value_count
return_line_items.line_item_total_amount	avg max min sum stats
return_line_items.line_item_tax_amount	avg max min sum stats
return_line_items.line_item_tax_rate	avg max min sum stats
stock_location.id	value_count
stock_location.name	value_count
stock_location.reference	value_count
stock_location.reference_origin	value_count

Nestable breakdowns and by values

These are the valid values you can specify for the by key of the breakdown query and the related forbidden values for the by key of the nested breakdown, based on the by key of the parent breakdown (i.e. for each row of the table below the full list of the valid values for the by key of the nested breakdown is given by all the values in the "Value" column except the values in the row's "Forbidden nesting" cell):

Value	Forbidden nesting
customer.email
customer.group_name
destination_address.business	destination_address.geocoded destination_address.localized customer.* origin_address.*
destination_address.city	destination_address.country_code destination_address.state_code customer.* origin_address.*
destination_address.country_code	customer.* origing_address.*
destination_address.geocoded	destination_address.* customer.* origing_address.*
destination_address.localized	destination_address.* customer.* origing_address.*
destination_address.state_code	destination_address.country_code customer.* origing_address.*
destination_address.zip_code	destination_address.country_code destination_address.city destination_address.geocoded destination_address.localized customer.* origing_address.*
origin_address.business	origin_address.geocoded origin_address.localized customer.* destination_address.*
origin_address.city	origin_address.country_code origin_address.state_code customer.* destination_address.*
origin_address.country_code	customer.* destrintation_address.*
origin_address.geocoded	destination_address.* customer.* origing_address.*
origin_address.localized	destination_address.* customer.* origing_address.*
origin_address.state_code	origin_address.country_code customer.* destination_address.*
origin_address.zip_code	origin_address.country_code origin_address.city origin_address.geocoded origin_address.localized customer.* destination_address.*
market.id
market.name
market.number
return.reference
return.reference_origin
return.status
return_line_items.line_item_item_type
stock_location.name
stock_location.reference
stock_location.reference_origin
tags.id
tags.name

Remember also that you cannot group the nested breakdown by the same field by which you're already grouping the parent breakdown.