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

Date breakdown

How to perform a date breakdown query and how it works

PreviousBreakdownNextStats

Last updated 2 years ago

Date breakdowns are aggregations that show the frequency of occurrence of a specific date value within a dataset and let you apply a specific over a selected field of the records that are present on that date. When performing a date breakdown query on the Metrics API endpoint you get in the the list by date of the values of the computation (based on the selected operator) on the selected field, over the selected time interval, aggregated by another field.

Request

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

{
  "date_breakdown": {
    "by": "...",
    "field": "...",
    "operator": "...",
    "interval": "...",
    "breakdown": { ... }
  },
  "filter": { ... },
  "meta": { ... }
}

Query keys

Key
Type
Required
Description
Values

by

String

The date 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.

interval

String

One of hour, day, week, month, or year (default is month).

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": [
    {
      "date": "...",
      "value": ...,
      "...": [ // breakdown by
        {
          "label": "...",
          "value": ...,
          "...": [ // nested breakdown by
            {
              "label": "...",
              "value": ...
            },
            { ... }
          ]
        },
        { ... }
      ]
    },
    {
      "date": "...",
      "value": ...,
      "...": [ // breakdown by
        {
          "label": "...",
          "value": ...,
          "...": [ // nested breakdown by
            {
              "label": "...",
              "value": ...
            },
            { ... }
          ]
        },
        { ... }
      ]
    },
    { ... } 
  ],
  "meta": { ... }
}

Date intervals

The results of a date breakdown query are aggregated over the specified time intervals. You can identify them in the response by looking at the date keys:

{
  "data": [
    {
      "date": "2021-04-01T00:00:00.000Z",
      "value": { ... }
    },
    {
      "date": "2021-05-01T00:00:00.000Z",
      "value": { ... }
    },
    { ... },
    {
      "date": "2021-09-01T00:00:00.000Z",
      "value": { ... }
    }
  ],
  "meta": { ... }
}
Interval
Date key values

year

YYYY-01-01T00:00:00.000Z

month

YYYY-MM-01T00:00:00.000Z

day

YYYY-MM-DDT00:00:00.000Z

hour

YYYY-MM-DDTHH:00:00.000Z

Examples

Date breakdown

The following request performs a date breakdown query to get the stats about the orders placed by month:

curl -g -X POST \
  'https://{{your_domain}}.commercelayer.io/metrics/orders/date_breakdown' \
  -H 'Accept: application/vnd.api.v1+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d '{
    "date_breakdown": {
      "by": "order.placed_at",
      "field": "order.total_amount_with_taxes",
      "operator": "stats",
      "interval": "month"
    }
}'

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

{
  "data": [
    {
      "date": "2022-05-01T00:00:00.000Z",
      "value": {
        "count": 6,
        "min": 65.0,
        "max": 243.0,
        "avg": 128.87,
        "sum": 773.2
      }
    },
    {
      "date": "2022-06-01T00:00:00.000Z",
      "value": {
        "count": 132,
        "min": 0.0,
        "max": 325.0,
        "avg": 78.33,
        "sum": 10340.09
      }
    }
  ],
  "meta": {
    "type": "date_breakdown",
    "trace_id": "b666478b-9c50-497b-a5e4-c7ed4dd7d7f3",
    "mode": "test",
    "organization_id": "xYZkjABcde",
    "market_ids": [ "yzXKjYzaCx", "..." ]
  }
}

Date breakdown with nested breakdown

The following request performs a date breakdown query to get the stats about the orders placed by month. Over each time interval, a breakdown of the orders' total amounts to check the maximum by country code is also requested. For each country code, a breakdown of the orders' total amounts to check the maximum by currency code (as long as it's over a specific threshold) is then requested:

curl -g -X POST \
  'https://{{your_domain}}.commercelayer.io/metrics/orders/date_breakdown' \
  -H 'Accept: application/vnd.api.v1+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d '{
    "date_breakdown": {
      "by": "order.placed_at",
      "field": "order.total_amount_with_taxes",
      "operator": "stats",
      "interval": "month",
      "breakdown": {
        "by": "order.country_code",
        "field": "order.total_amount_with_taxes",
        "operator": "max",
        "sort": "desc",
        "limit": 3,
        "breakdown": {
          "by": "order.currency_code",
          "field": "order.total_amount_with_taxes",
          "operator": "max",
          "condition": {
            "gt": 100
          }
          "sort": "desc",
          "limit": 2
        }
      }
    }
  }'

On success, the API responds with a 200 OK status code, returning the aggregated values over the selected time intervals (nested accordingly) in the data object and extra information in the meta object:

{
  "data": [
    {
      "date": "2022-05-01T00:00:00.000Z",
      "value": {
        "count": 6,
        "min": 65.0,
        "max": 243.0,
        "avg": 128.87,
        "sum": 773.2
      },
      "order.country_code": [
        {
          "label": "IT",
          "value": 243.0,
          "order.currency_code": [
            {
              "label": "EUR",
              "value": 243.0
            }
          ]
        }
      ]
    },
    {
      "date": "2022-06-01T00:00:00.000Z",
      "value": {
        "count": 132,
        "min": 0.0,
        "max": 925.0,
        "avg": 78.33,
        "sum": 10340.09
      },
      "order.country_code": [
        {
          "label": "IT",
          "value": 925.0,
          "order.currency_code": [
              {
                "label": "EUR",
                "value": 925.0
              }
          ]
        },
        {
          "label": "NO",
          "value": 855.0,
          "order.currency_code": [
            {
              "label": "NOK",
              "value": 855.0
            },
            {
              "label": "EUR",
              "value": 105.0
            }
          ]
        },
        {
          "label": "US",
          "value": 278.72,
          "order.currency_code": [
            {
              "label": "USD",
              "value": 278.72
            }
          ]
        }
      ]
    }
  ],
  "meta": {
    "type": "date_breakdown",
    "trace_id": "0e8e8b2c-4d13-444e-bf5a-1501061b3010",
    "mode": "test",
    "organization_id": "xYZkjABcde",
    "market_ids": [ "yzXKjYzaCx", "..." ]
  }
}

The available values for this key depend on the resource you're doing statistics on (see , returns, 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).

The time interval over which the metrics / stats are computed. The results will be aggregated by date accordingly ().

The optional (eventually ).

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

You can nest a breakdown query into a date breakdown one. This means you can request each aggregation by date over the selected time interval to be in turn aggregated by another field. Since the nested breakdown is a full-fledged query, it supports its own (up to one level), as shown in the .

The response of a date breakdown query returns an aggregation by date over the time interval specified in the interval 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:

Please note that those key values are only a reference to identify the related interval. In fact, each date key refers to the very beginning of the interval, regardless of the range specified in the which instead will still be honored for the actual computation (e.g. if you set a date filter that starts on April 15th, 2021 and ends on September 7th, 2021 for a date breakdown by month on the order resource, the first date key will be 2021-04-01T00:00:00.000Z and the last 2021-09-01T00:00:00.000Z, but the stats computation will still count the orders from April 15th to September 7th).

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
read how
breakdown
nested
orders
carts
orders
returns
carts
orders
returns
carts
orders
returns
carts
filter
response
query keys
breakdown
following example
use cases
nesting
date filter
default filter
operator
query
filter
meta