Breakdown

How to perform a breakdown query and how it works

Breakdowns are aggregations that summarize your data as metrics (based on specific operators) or statistics, computed on field values. When performing a breakdown query on the Metrics API endpoint you get in the response the value of the computation (based on the selected operator) on the selected field, aggregated by another field.

Request

To perform a breakdown query send a POST request to the /{{resource_name}}/breakdown endpoint specifying the query keys and filter parameters:

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

Query keys

Key	Type	Required	Description	Values
by	String		The field you want the results of the query aggragated by.	The available values for this key depend on the resource you're doing statistics on (see orders, returns, or carts for the related lists).
field	String		The field you want the metrics or statistics computed on.	The available values for this key depend on the resource you're doing statistics on (see orders, returns, or carts for the related lists).
operator	String		The computing operator.	The available operators depend on the field key value (see orders, returns, or carts for the related lists).
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.	The nested breakdown by key available values depend of the parent breakdown by key value (see orders, returns, or carts for the related lists).

Nesting breakdowns

Breakdowns can be nested recursively one into the other, up to one level (see example). The valid values allowed for the by key of the nested breakdown are strictly dependent on the value you specified in the by key of the parent breakdown. Hence, they are different for each resource you're doing statistics on (see orders, returns, and carts for the related lists).

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

Response

The response of a breakdown query returns an aggregation by the field specified in the by key, containing the value of the computation (based on the operator specified in the operator key) on the field specified in the field key. If the query contains a nested breakdown, it is also detailed for each item of the array:

{
  "data": {
    "...": [ // breakdown by
      {
        "label": "...",
        "value": ...,
        "...": [ // nested breakdown by
          {
            "label": "...",
            "value": ...
          },
          {
            "label": "...",
            "value": ...
          },
          { ... }
        ]
      },
      {
        "label": "...",
        "value": ...,
        "...": [ // nested breakdown by
          {
            "label": "...",
            "value": ...
          },
          {
            "label": "...",
            "value": ...
          },
          { ... }
        ]
      },
      { ... }
    ]
  }
}

Key	Description
label	The different values of the by field the results are aggregated by.
value	The result of the computation for the specific label.

Examples

The following examples will be focused on the query part of the request. So no specific filter or meta options will be defined (i.e. all the results will be filtered by the default filter and the response won't include the request payload). See the use cases section for more complex combinations of queries and filters.

Single breakdown

Request

The following request performs a breakdown query to get the total count of orders by market, as long as the computed result is within a specific range:

curl -g -X POST \
  'https://{{your_domain}}.commercelayer.io/metrics/orders/breakdown' \
  -H 'Accept: application/vnd.api.v1+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d '{
    "breakdown": {
      "by": "market.name",
      "field": "order.id",
      "operator": "value_count",
      "condition": {
        "gte_lte": [ 10000, 100000 ]
      },
      "sort": "desc",
      "limit": 2
    }
  }'

Response

On success, the API responds with a 200 OK status code, returning the aggregated values in the data object and extra information in the meta object:

{
  "data": {
    "market.name": [
      {
        "label": "US",
        "value": 67890
      },
      {
        "label": "UK",
        "value": 12345
      }
    ]
  },
  "meta": {
    "type": "breakdown",
    "trace_id": "3e60cfb2-c0df-43c8-84e8-d9632705d2f9",
    "mode": "test",
    "organization_id": "xYZkjABcde",
    "market_ids": [ "yzXKjYzaCx", "..." ]
    }
  }
}

Nested breakdown

Request

The following request performs a breakdown query to get the total count of orders by market, as long as the computed result is within a specific range. For each market, a breakdown of the orders' total amounts by currency code is also requested:

curl -g -X POST \
  'https://{{your_domain}}.commercelayer.io/metrics/orders/breakdown' \
  -H 'Accept: application/vnd.api.v1+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d '{
    "breakdown": {
      "by": "market.name",
      "field": "order.id",
      "operator": "value_count",
      "condition": {
        "gte_lte": [ 10000, 100000 ]  
      },
      "sort": "desc",
      "limit": 3,
      "breakdown": {
        "by": "order.currency_code",
        "field": "order.total_amount_with_taxes",
        "operator": "sum"
        "sort": "desc",
        "limit": 2
      }
    }
  }'

Response

On success, the API responds with a 200 OK status code, returning the aggregated, nested values in the data object and extra information in the meta object:

{
  "data": {
    "market.name": [
      {
        "label": "US",
        "value": 67890,
        "order.currency_code": [
          {
            "label": "USD",
            "value": 1234567.89
          }
        ]
      },
      {
        "label": "UK",
        "value": 12345,
        "order.currency_code": [
          {
            "label": "GBP",
            "value": 234567.89
          },
          {
            "label": "EUR",
            "value": 9876.54
          }
        ]
      },
      {
        "label": "NO",
        "value": 11234,
        "order.currency_code": [
          {
            "label": "NOK",
            "value": 345678.90
          },
          {
            "label": "EUR",
            "value": 45678.90
          }
        ]
      }
    ]
  },
  "meta": {
    "type": "breakdown",
    "trace_id": "d0f7d8bf-1b3f-42a8-8b72-dfb158da95e7",
    "mode": "test",
    "organization_id": "xYZkjABcde",
    "market_ids": [ "yzXKjYzaCx", "..." ]
    }
  }
}