Stats

How to perform a stats query and how it works

Stats are numeric computations (based on specific operators) calculated over values extracted from a specific field of the selected resource. When performing a stats 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.
Request
To perform a date breakdown query send a POST request to the /{{resource_name}}/stats endpoint specifying the query keys and filter parameters:
{
  "stats": {
    "field": "...",
    "operator": "..."
  },
  "filter": { ... },
  "meta": { ... }
}
Query keys
Key
Type
Required
Description
Values
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).
Response
The response of a stats query returns the value of the computation (based on the operator specified in the operator key) on the field specified in the field key. The value type depends on the operator itself — it can be an object made of multiple numeric values (stats) or a simple integer/float number (any other operator):
{
  "data": {
    "value": ...
  },
  "meta": { ... }
}
Example
The following example 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.
Request
Response
The following request performs a stats query to get the average order total amount:
curl -g -X POST \
  'https://{{your_domain}}.commercelayer.io/metrics/orders/stats' \
  -H 'Accept: application/vnd.api.v1+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d '{
    "stats": {
      "field": "order.total_amount_with_taxes",
      "operator": "avg"
    }
  }'
On success, the API responds with a 200 OK status code, returning the computed value in the data object and additional information in the meta object:
{
  "data": {
    "value": 123.45
  },
  "meta": {
    "type": "stats",
    "trace_id": "f9df8a29-b5fe-4b4b-9a4d-f51017abb13b",
    "mode": "test",
    "organization_id": "xYZkjABcde",
    "market_ids": [ "yzXKjYzaCx", "..." ]
  }
}

Key	Type	Required	Description	Values
`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).

Date breakdown

Last modified 7mo ago