# Breakdown

To perform a breakdown query on the cart resource send a `POST` request to the `/carts/breakdown` endpoint specifying the [query keys](#query-keys) and [filter](/metrics-api-reference/resources/carts/filters.md) parameters like in the generic example below:

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

{% hint style="info" %}
Please find more information on how breakdown queries work [here](/metrics/getting-started/queries/breakdown.md).
{% endhint %}

### Query keys

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

<table><thead><tr><th>Key</th><th>Type</th><th data-type="checkbox">Required</th><th>Description</th><th>Values</th></tr></thead><tbody><tr><td><strong><code>by</code></strong></td><td>String</td><td>true</td><td>The field you want the results of the query aggragated by.</td><td>See the <a href="#nestable-breakdowns-and-by-values">related table</a> to check the full list of valid values for this key.</td></tr><tr><td><strong><code>field</code></strong></td><td>String</td><td>true</td><td>The field of the resource you want the metrics or statistics computed on.</td><td>See the <a href="#operators-and-field-values">related table</a> to check the full list of valid values for this key.</td></tr><tr><td><strong><code>operator</code></strong></td><td>String</td><td>true</td><td>The computing operator.</td><td>See the <a href="#operators-and-field-values">related table</a> to check the full list of valid operators based on the value you assigned to the <code>field</code> key.</td></tr><tr><td><strong><code>condition</code></strong></td><td>Object</td><td>false</td><td>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.</td><td><p>One of:<br><code>"eq": ...</code></p><p><code>"ne": ...</code></p><p><code>"gt": ...</code></p><p><code>"gte": ...</code></p><p><code>"lt": ...</code></p><p><code>"lte": ...</code></p><p><code>"gt_lt": [...]</code></p><p><code>"gte_lte": [...]</code></p><p><code>"gte_lt": [...]</code></p><p><code>"gt_lte": [...]</code><br>(default is no condition).</p></td></tr><tr><td><strong><code>sort</code></strong></td><td>String</td><td>false</td><td>The way you want the results of the query to be sorted.</td><td>One of <code>asc</code> or <code>desc</code> (default is <code>desc</code>).</td></tr><tr><td><strong><code>limit</code></strong></td><td>Integer</td><td>false</td><td>The maximum number of records shown in the response.</td><td>Default is <code>10</code>, max is <code>100</code>.</td></tr><tr><td><strong><code>breakdown</code></strong></td><td>Object</td><td>false</td><td>The optional nested breakdown.</td><td>See the <a href="#nestable-breakdowns-and-by-values">related table</a> to check full list of valid values for the nested breakdown <code>by</code> key, based on the value you assigned to the parent breakdown <code>by</code> key.</td></tr></tbody></table>

### 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`**                         | <p><code>cardinality</code></p><p><code>value\_count</code></p>                                                       |
| **`customer.email`**                      | <p><code>cardinality</code></p><p><code>value\_count</code></p>                                                       |
| **`customer.group_name`**                 | <p><code>cardinality</code></p><p><code>value\_count</code></p>                                                       |
| **`customer.reference`**                  | <p><code>cardinality</code></p><p><code>value\_count</code></p>                                                       |
| **`customer.reference_origin`**           | <p><code>cardinality</code></p><p><code>value\_count</code></p>                                                       |
| **`line_items.code`**                     | <p><code>cardinality</code></p><p><code>value\_count</code></p>                                                       |
| **`line_items.discount`**                 | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`line_items.id`**                       | <p><code>cardinality</code></p><p><code>value\_count</code></p>                                                       |
| **`line_items.item_id`**                  | <p><code>cardinality</code></p><p><code>value\_count</code></p>                                                       |
| **`line_items.options_amount`**           | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`line_items.quantity`**                 | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`line_items.tax_amount`**               | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`line_items.tax_rate`**                 | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`line_items.total_amount`**             | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`line_items.unit_amount`**              | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`line_items.options.id`**               | <p><code>cardinality</code></p><p><code>value\_count</code></p>                                                       |
| **`line_items.options.quantity`**         | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`line_items.options.total_amount`**     | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`line_items.options.unit_amount`**      | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`market.id`**                           | `cardinality`                                                                                                         |
| **`market.number`**                       | <p><code>cardinality</code></p><p><code>value\_count</code></p>                                                       |
| **`order.adjustment_amount`**             | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`order.adjustment_tax_amount`**         | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`order.adjustment_taxable_amount`**     | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`order.discount_amount`**               | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`order.duty_amount`**                   | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`order.gift_card_code`**                | `value_count`                                                                                                         |
| **`order.gift_card_amount`**              | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`order.id`**                            | <p><code>cardinality</code></p><p><code>value\_count</code></p>                                                       |
| **`order.line_item_options_count`**       | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`order.number`**                        | `value_count`                                                                                                         |
| **`order.payment_method_amount`**         | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`order.payment_method_tax_amount`**     | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`order.payment_method_taxable_amount`** | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`order.reference`**                     | <p><code>cardinality</code></p><p><code>value\_count</code></p>                                                       |
| **`order.reference_origin`**              | <p><code>cardinality</code></p><p><code>value\_count</code></p>                                                       |
| **`order.shipments_count`**               | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`order.shipping_amount`**               | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`order.shipping_taxable_amount`**       | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`order.skus_count`**                    | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`order.subtotal_amount`**               | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`order.subtotal_tax_amount`**           | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`order.subtotal_taxable_amount`**       | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`order.total_amount`**                  | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`order.total_amount_with_taxes`**       | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`order.total_tax_amount`**              | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`order.total_taxable_amount`**          | <p><code>avg</code></p><p><code>max</code></p><p><code>min</code></p><p><code>sum</code></p><p><code>stats</code></p> |
| **`resource_errors.code`**                | <p><code>cardinality</code></p><p><code>value\_count</code></p>                                                       |
| **`resource_errors.id`**                  | <p><code>cardinality</code></p><p><code>value\_count</code></p>                                                       |
| **`resource_errors.message`**             | <p><code>cardinality</code></p><p><code>value\_count</code></p>                                                       |

### 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`**      | <p><code>billing\_address.geocoded</code></p><p><code>billing\_address.localized</code></p><p><code>customer.*</code></p><p><code>shipping\_address.*</code></p><p><code>line\_items.item\_type</code></p><p><code>order.freight\_taxable</code></p><p><code>order.fulfillment\_status</code></p><p><code>order.payment\_status</code></p><p><code>order.status</code></p>  |
| **`billing_address.city`**          | <p><code>billing\_address.country\_code</code></p><p><code>billing\_address.state\_code</code></p><p><code>customer.*</code></p><p><code>shipping\_address.*</code></p><p><code>line\_items.item\_type</code></p>                                                                                                                                                           |
| **`billing_address.country_code`**  | <p><code>customer.*</code></p><p><code>shipping\_address.*</code></p><p><code>line\_items.item\_type</code></p>                                                                                                                                                                                                                                                             |
| **`billing_address.geocoded`**      | <p><code>billing\_address.*</code></p><p><code>customer.*</code></p><p><code>shipping\_address.\*</code></p><p><code>line\_items.item\_type</code></p>                                                                                                                                                                                                                      |
| **`billing_address.localized`**     | <p><code>billing\_address.*</code></p><p><code>customer.*</code></p><p><code>shipping\_address.\*</code></p><p><code>line\_items.item\_type</code></p>                                                                                                                                                                                                                      |
| **`billing_address.state_code`**    | <p><code>billing\_address.country\_code</code></p><p><code>customer.*</code></p><p><code>shipping\_address.*</code></p><p><code>line\_items.item\_type</code></p>                                                                                                                                                                                                           |
| **`billing_address.zip_code`**      | <p><code>billing\_address.country\_code</code></p><p><code>billing\_address.city</code></p><p><code>billing\_address.geocoded</code></p><p><code>billing\_address.localized</code></p><p><code>customer.*</code></p><p><code>shipping\_address.*</code></p><p><code>line\_items.item\_type</code></p>                                                                       |
| **`customer.id`**                   |                                                                                                                                                                                                                                                                                                                                                                             |
| **`customer.email`**                |                                                                                                                                                                                                                                                                                                                                                                             |
| **`customer.group_name`**           |                                                                                                                                                                                                                                                                                                                                                                             |
| **`customer.reference`**            |                                                                                                                                                                                                                                                                                                                                                                             |
| **`customer.reference_origin`**     |                                                                                                                                                                                                                                                                                                                                                                             |
| **`line_items.code`**               |                                                                                                                                                                                                                                                                                                                                                                             |
| **`line_items.id`**                 |                                                                                                                                                                                                                                                                                                                                                                             |
| **`line_items.item_id`**            |                                                                                                                                                                                                                                                                                                                                                                             |
| **`line_items.item_type`**          |                                                                                                                                                                                                                                                                                                                                                                             |
| **`line_items.name`**               |                                                                                                                                                                                                                                                                                                                                                                             |
| **`line_items.options.id`**         | `line_items.*`                                                                                                                                                                                                                                                                                                                                                              |
| **`line_items.options.name`**       | `line_items.*`                                                                                                                                                                                                                                                                                                                                                              |
| **`market.id`**                     | <p><code>billing\_address.geocoded</code></p><p><code>billing\_address.localized</code></p><p><code>shipping\_address.geocoded</code></p><p><code>shipping\_address.localized</code></p><p><code>line\_items.item\_type</code></p>                                                                                                                                          |
| **`market.name`**                   |                                                                                                                                                                                                                                                                                                                                                                             |
| **`market.number`**                 |                                                                                                                                                                                                                                                                                                                                                                             |
| **`order.customer_type`**           |                                                                                                                                                                                                                                                                                                                                                                             |
| **`order.country_code`**            |                                                                                                                                                                                                                                                                                                                                                                             |
| **`order.coupon_code`**             |                                                                                                                                                                                                                                                                                                                                                                             |
| **`order.currency_code`**           |                                                                                                                                                                                                                                                                                                                                                                             |
| **`order.freight_taxable`**         |                                                                                                                                                                                                                                                                                                                                                                             |
| **`order.gift_card_code`**          |                                                                                                                                                                                                                                                                                                                                                                             |
| **`order.guest`**                   |                                                                                                                                                                                                                                                                                                                                                                             |
| **`order.language_code`**           |                                                                                                                                                                                                                                                                                                                                                                             |
| **`order.reference`**               |                                                                                                                                                                                                                                                                                                                                                                             |
| **`order.reference_origin`**        |                                                                                                                                                                                                                                                                                                                                                                             |
| **`order.status`**                  |                                                                                                                                                                                                                                                                                                                                                                             |
| **`order.tax_included`**            |                                                                                                                                                                                                                                                                                                                                                                             |
| **`order.link_id`**                 |                                                                                                                                                                                                                                                                                                                                                                             |
| **`order.user_id`**                 |                                                                                                                                                                                                                                                                                                                                                                             |
| **`order.store_id`**                |                                                                                                                                                                                                                                                                                                                                                                             |
| **`order.affiliate_code`**          |                                                                                                                                                                                                                                                                                                                                                                             |
| **`payment_method.source_type`**    |                                                                                                                                                                                                                                                                                                                                                                             |
| **`payment_method.name`**           |                                                                                                                                                                                                                                                                                                                                                                             |
| **`payment_method.moto`**           |                                                                                                                                                                                                                                                                                                                                                                             |
| **`shipping_address.business`**     | <p><code>shipping\_address.geocoded</code></p><p><code>shipping\_address.localized</code></p><p><code>customer.*</code></p><p><code>billing\_address.*</code></p><p><code>line\_items.item\_type</code></p><p><code>order.freight\_taxable</code></p><p><code>order.fulfillment\_status</code></p><p><code>order.payment\_status</code></p><p><code>order.status</code></p> |
| **`shipping_address.city`**         | <p><code>shipping\_address.country\_code</code></p><p><code>shipping\_address.state\_code</code></p><p><code>customer.*</code></p><p><code>billing\_address.*</code></p><p><code>line\_items.item\_type</code></p>                                                                                                                                                          |
| **`shipping_address.country_code`** | <p><code>customer.*</code></p><p><code>billing\_address.*</code></p><p><code>line\_items.item\_type</code></p>                                                                                                                                                                                                                                                              |
| **`shipping_address.geocoded`**     | <p><code>billing\_address.*</code></p><p><code>customer.*</code></p><p><code>shipping\_address.\*</code></p><p><code>line\_items.item\_type</code></p>                                                                                                                                                                                                                      |
| **`shipping_address.localized`**    | <p><code>billing\_address.*</code></p><p><code>customer.*</code></p><p><code>shipping\_address.\*</code></p><p><code>line\_items.item\_type</code></p>                                                                                                                                                                                                                      |
| **`shipping_address.state_code`**   | <p><code>shipping\_address.country\_code</code></p><p><code>customer.*</code></p><p><code>billing\_address.*</code></p><p><code>line\_items.item\_type</code></p>                                                                                                                                                                                                           |
| **`shipping_address.zip_code`**     | <p><code>shipping\_address.country\_code</code></p><p><code>shipping\_address.city</code></p><p><code>shipping\_address.geocoded</code></p><p><code>shipping\_address.localized</code></p><p><code>customer.*</code></p><p><code>billing\_address.*</code></p><p><code>line\_items.item\_type</code></p>                                                                    |
| **`tags.id`**                       |                                                                                                                                                                                                                                                                                                                                                                             |
| **`tags.name`**                     |                                                                                                                                                                                                                                                                                                                                                                             |
| **`resource_errors.code`**          |                                                                                                                                                                                                                                                                                                                                                                             |
| **`resource_errors.name`**          |                                                                                                                                                                                                                                                                                                                                                                             |
| **`resource_errors.id`**            |                                                                                                                                                                                                                                                                                                                                                                             |
| **`resource_errors.message`**       |                                                                                                                                                                                                                                                                                                                                                                             |

{% hint style="info" %}
Remember also that you cannot group the nested breakdown by the same field by which you're already grouping the parent breakdown.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.commercelayer.io/metrics-api-reference/resources/carts/breakdown.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.