# API specification In addition to the [core commerce API](https://docs.commercelayer.io/), Commerce Layer exposes a fast **Metrics API** that lets you extract relevant metric data from your organizations. {% hint style="info" %} Commerce Layer Metrics API is currently released in **open beta**. It has completed intensive internal testing, as well as being tested by a carefully selected range of external users, so that we feel it is now as bug-free as possible and is therefore ready to be safely used by a broader set of customers. We strongly encourage you to try it out and provide any kind of feedback that could help us fine-tune the API behavior. Based on that and on our constant monitoring of the API usage as it is tested by a larger audience we'll adjust the API features and any other opinionated detail (rate limits, default values, and more). {% endhint %} Commerce Layer Metrics API is an **HTTP** API that supports different types of [queries](/metrics/getting-started/queries.md) and the option to [filter](/metrics/getting-started/filters.md) the results. {% hint style="warning" %} All the **strings** passed to the API must be [UTF-8](https://en.wikipedia.org/wiki/UTF-8) encoded. `date-time` [strings parameters](https://swagger.io/docs/specification/data-models/data-types/#string) must comply with the [ISO 8601](https://www.w3.org/TR/NOTE-datetime) standard (complete date plus hours, minutes, and seconds — more info [here](/metrics/getting-started/filters.md#date-formats)). {% endhint %} The guide that follows is your reference for all the operations ([breakdown](/metrics/getting-started/queries/breakdown.md), [date breakdown](/metrics/getting-started/queries/date-breakdown.md), [stats](/metrics/getting-started/queries/stats.md), and [search](/metrics/getting-started/queries/search.md)) that you can perform on the resource available to do statistics on ([orders](/metrics-api-reference/resources/orders.md), [returns](/metrics-api-reference/resources/returns.md), and [carts](/metrics-api-reference/resources/carts.md)) and contains all the information you need to get a comprehensive overview of how it works. ### Base endpoint All API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure) to the following base endpoint: ```http https://{{your_domain}}.commercelayer.io/metrics ``` Where `{{your_domain}}` is the unique subdomain of your Commerce Layer organization. ### Authorization You need to [authenticate](https://docs.commercelayer.io/core/authentication) to Commerce Layer core API and get an **integration** or a **webapp** access token. The Metrics API results will be automatically filtered (in terms of organizations and markets) according to the [scopes](https://docs.commercelayer.io/core/authentication#authorization-scopes) included in the token. ### Headers Include the following HTTP request headers when making calls to the Metrics API endpoint:
HeaderRequiredDetails
AccepttrueMust be application/vnd.api.v1+json (learn more about versioning)
Content-TypetrueMust be application/vnd.api+json
AuthorizationtrueMust be Bearer {{your_access_token}}
Where `{{your_access_token}}` is the access token you get by [authenticating](#authorization) to Commerce Layer core API. ### API versioning The **Accept** header will be also used to manage future versioning. You'll be able to request a specific version of the Metrics API just by changing it as follows: ``` Accept: application/vnd.api.v{{version}}+json ``` Where `{{version}}` is the unique progressive number that identifies the version you want to use. {% hint style="info" %} The latest version of the Metrics API is **v1** — use `application/vnd.api.v1+json` as the **Accept** header to make your calls. {% endhint %} ### Resources The Commerce Layer [core resources](https://docs.commercelayer.io/core-api-reference/) you can do statistics on using the Metrics API currently are: | Resource | Endpoint | Description | | ----------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Orders** | `/orders` | Your organization [orders](https://docs.commercelayer.io/core/v/api-reference/orders) (*draft* and *pending* ones excluded), filtered by the market(s) in scope. | | **Returns** | `/returns` | Your organization [returns](https://docs.commercelayer.io/core/v/api-reference/returns), filtered by the market(s) in scope. | | **Carts** | `/carts` | Your organization *draft* and *pending* [orders](https://docs.commercelayer.io/core/v/api-reference/orders), filtered by the market(s) in scope. | {% hint style="info" %} Given the definitions above, *draft* and *pending* orders act as **Carts**, so if you want to do statistics on that kind of orders you need to make requests to the `/carts` endpoint. As soon as an order is *placed* it is moved to the **Orders** collection, so if you want to do statistics on that kind of orders you need to make requests to the `/orders` endpoint. For cross-statistics on the two kinds of orders (e.g. the total number of orders, whether or not they were placed, over a specific date and time range), you need to perform the same query both on the `/carts` and on the `/orders` endpoints and add additional logic based on the specific use case (e.g. summing the values returned by the two queries). {% endhint %} ### Query types Commerce Layer Metrics API lets you retrieve metric data through four types of [queries](/metrics/getting-started/queries.md): | Query type | Endpoint | Description | | ------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Breakdown** | `/breakdown` | Returns the value of the computation (based on the selected operator) on the selected field, aggregated by another field. | | **Date breakdown** | `/date_breakdown` | Returns a list by date of the values of the computation (based on the selected operator) on the selected field, over the selected time interval (e.g. day, month, etc.). | | **Stats** | `/stats` | Returns the value of the computation (based on the selected operator) on the selected field. | | **Search** | `/search` | Returns the list of the requested fields of the actual records that match the query. | ### Request {% hint style="info" %} Metric data requests are submitted to the Metrics API through a **`POST`** request. Any other method will return an error ([see example](/metrics/getting-started/errors.md#405-method-not-allowed)). {% endhint %} To build the **endpoint** you need to make your requests just add the name of the [resource](#resources) you want to do statistics on and the [type of query](#query-types) you'd like to perform to the [base endpoint](#base-endpoint), like so: ```http https://{{your_domain}}.commercelayer.io/metrics/{{resource_name}}/{{query_type}} ``` The JSON data **payload** you need to send in the request body is composed of three main blocks: ```json { "{{query_type}}": { "...": ..., // query keys "...": ... }, "filter": { "{{field_name}}": { "...": ..., // filter parameters "...": ... } }, "meta": { "...": ... // meta options "...": ... } } ``` #### Query The `query` object is required and specifies the type of query you're going to perform (one of [breakdown](/metrics/getting-started/queries/breakdown.md#request), [date breakdown](/metrics/getting-started/queries/date-breakdown.md#request), [stats](/metrics/getting-started/queries/stats.md#request), or [search](/metrics/getting-started/queries/search.md#request)) and the related fields, operators, and limits. #### Filter The `filter` object is optional (if missing a [default filter](/metrics/getting-started/filters.md#default-filter) will be used) but you'll likely want to use it to narrow the results of the query by date or any other parameter available for filtering the selected resource. #### Meta The `meta` object is optional and can be used to customize the information that will be returned in the [corresponding object](#meta-1) of the response. At the moment the only option available for this block is:
KeyTypeRequiredDescriptionValue
payloadBooleanfalseIf true the actual payload used to perform the query will be returned in the response.Default is false.
```json { "{{query_type}}": { ... }, "filter": { ... }, "meta": { "payload": true } } ``` {% hint style="info" %} Being their response a plain CSV file, the meta object is **not** returned by [export](/metrics/getting-started/queries/export.md) queries. {% endhint %} ### Response On success, the API responds with a `200 OK` status code, returning a response in the JSON format. The successful response is composed of two main blocks: ```json { "data": ... , "meta": { ... } } ``` #### Data `data` contains the actual results of the query, filtered accordingly. Its structure depends on the type of query you're performing. It can be a collection ([date breakdown](/metrics/getting-started/queries/date-breakdown.md#response) and [search](/metrics/getting-started/queries/search.md#response)) or a single object ([breakdown](/metrics/getting-started/queries/breakdown.md#response) and [stats](/metrics/getting-started/queries/stats.md#response)). The returned fields will be detailed case by case, with some examples in the related [sections](/metrics/getting-started/queries.md). #### Meta The `meta` object contains useful information about the query itself. It has the same structure for all the queries (except for the `pagination` key, which is present in the [search queries](/metrics/getting-started/queries/search.md#pagination) response only): ```json { "data": ... , "meta": { "pagination": { "record_count": 123, "cursor": "LS0tCi0gJzIwMjItMDYtMTNUMTQ6==" }, "type": "{{query_type}}", "trace_id": "32ef0bfb-39ff-409b-b98f-6433da2f8e09", "mode": "test", "organization_id": "xYZkjABcde", "market_ids": [ "yzXKjYzaCx", "..." ], "payload": { "{{query_type}}": { ... }, "filter": { ... } } } } ``` | Field | Type | Description | | --------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`pagination`** | Object | Contains the total `record_count` and the `cursor` pointing at the next page, useful to navigate through the [search](/metrics/getting-started/queries/search.md#pagination) results (not available for [breakdowns](/metrics/getting-started/queries/breakdown.md), [date breakdowns](/metrics/getting-started/queries/date-breakdown.md), and [stats](/metrics/getting-started/queries/stats.md)). | | **`type`** | String | The query type (one of `breakdown`, `date_breakdown`, `stats`, or `search`). | | **`trace_id`** | String | The ID of the user's web request, useful for debugging in case of [errors](/metrics/getting-started/errors.md). | | **`mode`** | String | The resource environment (one of `test` or `live`), read from the access token used to perform the request. | | **`organization_id`** | String | Your organization ID, read from the access token used to perform the request. | | **`market_ids`** | Array | The ID(s) of the market(s) in scope, read from the access token used to perform the request. | | **`payload`** | Object | The payload of the query you performed, filled with any computed and/or default values (returned only if [explicitly requested](#meta) when performing the query). | --- # 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/getting-started/api-specification.md?ask= ``` 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.