Breakdown

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

To perform a breakdown query on the order resource send a POST request to the /orders/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	cardinality value_count
customer.email	cardinality value_count
customer.group_name	cardinality value_count
line_items.code	cardinality value_count
line_items.discount	avg max min sum stats
line_items.id	cardinality value_count
line_items.item_id	cardinality value_count
line_items.options_amount	avg max min sum stats
line_items.quantity	avg max min sum stats
line_items.tax_amount	avg max min sum stats
line_items.tax_rate	avg max min sum stats
line_items.total_amount	avg max min sum stats
line_items.unit_amount	avg max min sum stats
line_items.options.id	cardinality value_count
line_items.options.quantity	avg max min sum stats
line_items.options.total_amount	avg max min sum stats
line_items.options.unit_amount	avg max min sum stats
market.id	cardinality
market.number	cardinality value_count
order.adjustment_amount	avg max min sum stats
order.adjustment_tax_amount	avg max min sum stats
order.adjustment_taxable_amount	avg max min sum stats
order.discount_amount	avg max min sum stats
order.duty_amount	avg max min sum stats
order.gift_card_code	value_count
order.gift_card_amount	avg max min sum stats
order.id	cardinality value_count
order.line_item_options_count	avg max min sum stats
order.number	value_count
order.payment_method_amount	avg max min sum stats
order.payment_method_tax_amount	avg max min sum stats
order.payment_method_taxable_amount	avg max min sum stats
order.reference	cardinality value_count
order.reference_origin	cardinality value_count
order.shipments_count	avg max min sum stats
order.shipping_amount	avg max min sum stats
order.shipping_taxable_amount	avg max min sum stats
order.skus_count	avg max min sum stats
order.subtotal_amount	avg max min sum stats
order.subtotal_tax_amount	avg max min sum stats
order.subtotal_taxable_amount	avg max min sum stats
order.total_amount	avg max min sum stats
order.total_amount_with_taxes	avg max min sum stats
order.total_tax_amount	avg max min sum stats
order.total_taxable_amount	avg max min sum stats
order.seconds_in_draft	avg max min stats percentiles
order.seconds_in_approved	avg max min stats percentiles
order.seconds_in_placed	avg max min stats percentiles
order.refunds_total_amount_with_taxes	avg max min sum stats
order.total_amount_with_taxes_net_of_refunds	avg max min sum stats
refunds.id	value_count
refunds.amount	avg max min sum stats
refunds.number	value_count
shipments.reference	cardinality value_count
shipments.reference_origin	cardinality value_count
shipments.seconds_in_picking	avg max min stats percentiles
shipments.seconds_in_ready_to_ship	avg max min stats percentiles
shipments.stock_location.reference	cardinality value_count
shipments.stock_location_reference_origin	cardinality value_count
shipments.shipping_method.reference	cardinality value_count
shipments.shipping_method.reference_origin	cardinality value_count
shipments.shipping_category.reference	cardinality value_count
shipments.shipping_category.reference_origin	cardinality 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
billing_address.business	billing_address.geocoded billing_address.localized customer.* shipping_address.* line_items.item_type order.freight_taxable order.fulfillment_status order.payment_status order.status
billing_address.city	billing_address.country_code billing_address.state_code customer.* shipping_address.* line_items.item_type
billing_address.country_code	customer.* shipping_address.* line_items.item_type
billing_address.geocoded	billing_address.* customer.* shipping_address.* line_items.item_type
billing_address.localized	billing_address.* customer.* shipping_address.* line_items.item_type
billing_address.state_code	billing_address.country_code customer.* shipping_address.* line_items.item_type
billing_address.zip_code	billing_address.country_code billing_address.city billing_address.geocoded billing_address.localized customer.* shipping_address.* line_items.item_type
customer.id
customer.email
customer.group_name
line_items.code
line_items.id
line_items.item_id
line_items.item_type
line_items.name
line_items.options.id	line_items.* shipments.*
line_items.options.name	line_items.* shipments.*
market.id	billing_address.geocoded billing_address.localized shipping_address.geocoded shipping_address.localized line_items.item_type
market.name
market.number
order.country_code
order.coupon_code
order.currency_code
order.freight_taxable
order.fulfillment_status
order.gift_card_code
order.guest
order.language_code
order.payment_status
order.reference
order.reference_origin
order.status
order.tax_included
order.placed_day_of_week
payment_method.source_type
payment_method.name
payment_method.moto
payment_method.issuer
payment_method.issuer_type
payment_method.card_type
shipping_address.business	shipping_address.geocoded shipping_address.localized customer.* billing_address.* line_items.item_type order.freight_taxable order.fulfillment_status order.payment_status order.status
shipping_address.city	shipping_address.country_code shipping_address.state_code customer.* billing_address.* line_items.item_type
shipping_address.country_code	customer.* billing_address.* line_items.item_type
shipping_address.geocoded	billing_address.* customer.* shipping_address.* line_items.item_type
shipping_address.localized	billing_address.* customer.* shipping_address.* line_items.item_type
shipping_address.state_code	shipping_address.country_code customer.* billing_address.* line_items.item_type
shipping_address.zip_code	shipping_address.country_code shipping_address.city shipping_address.geocoded shipping_address.localized customer.* billing_address.* line_items.item_type
shipments.status
shipments.reference
shipments.reference_origin
shipments.stock_location.name
shipments.stock_location.reference
shipments.stock_location_reference_origin
shipments.shipping_method.name
shipments.shipping_method.reference
shipments.shipping_method.reference_origin
shipments.shipping_method.currency_code
shipments.shipping_category.name
shipments.shipping_category.reference
shipments.shipping_category.reference_origin
shipments.tags.id
shipments.tags.name
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.