Enabled resource errors field for orders and carts —
Check the use case
LogoLogo
Metrics APIOther APIsChangelog
Getting started
Getting started
  • Welcome to Metrics API
  • Getting started
    • API specification
    • Queries
      • Breakdown
      • Date breakdown
      • Stats
      • Search
    • Filters
    • Analysis
      • FBT
    • Errors
    • Use cases
      • Orders by currency
      • Orders by status and payment status
      • Orders by repeat customer
      • Orders by bundle
      • Orders by shipment status and shipping method name
      • Orders paid with gift cards
      • Orders associated with a specific promotion
      • Number of products per order by country
      • Best-selling products by market
      • Customers that bought a specific product
      • Shipments average time in picking
      • Top 10 spenders by currency
      • Orders by day
      • Returns per year by destination city
      • Refunds by country and currency
      • Latest carts with a specific product from a specific market
      • Orders by resource error code and message
      • Latest archived orders
      • Latest placed orders from customers with specific email domains
      • Frequently bought together products
  • API reference
    • Orders
    • Returns
    • Carts
On this page
  • Request
  • Response
  • Examples
  1. Getting started
  2. Queries

Breakdown

How to perform a breakdown query and how it works

PreviousQueriesNextDate breakdown

Last updated 1 month ago

Breakdowns are aggregations that summarize your data as metrics (based on specific ) or statistics, computed on field values. When performing a breakdown query on the Metrics API endpoint you get in the 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 and 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.

field

String

The field you want the metrics or statistics computed on.

operator

String

The computing operator.

condition

Object

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

Nesting breakdowns

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

Response

{
  "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

Single breakdown

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
    }
  }'

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

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
      }
    }
  }'

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", "..." ]
    }
  }
}

The available values for this key depend on the resource you're doing statistics on (see , , or for the related lists).

The available values for this key depend on the resource you're doing statistics on (see , , or for the related lists).

The available operators depend on the field key value (see , , or for the related lists).

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 that return single numeric (float or integer) values.

The optional .

The nested breakdown by key available values depend of the parent breakdown by key value (see , , or for the related lists).

Breakdowns can be nested recursively one into the other, up to one level (see ). 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 , , and for the related lists).

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 , it is also detailed for each item of the array:

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

nested breakdown
example
orders
returns
carts
nested breakdown
orders
returns
carts
orders
returns
carts
orders
returns
carts
orders
returns
carts
filter
response
query keys
operators
operators
use cases
query
filter
meta
default filter