API specification

Basic info about endpoints and access tokens, request types and headers, payload and response structure

In addition to the core commerce API, Commerce Layer exposes a fast Metrics API that lets you extract relevant metric data from your organizations.

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).

Commerce Layer Metrics API is an HTTP API that supports different types of queries and the option to filter the results.

All the strings passed to the API must be UTF-8 encoded. date-time strings parameters must comply with the ISO 8601 standard (complete date plus hours, minutes, and seconds — more info here).

The guide that follows is your reference for all the operations (breakdown, date breakdown, stats, and search) that you can perform on the resource available to do statistics on (orders, returns, and carts) 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 to the following base endpoint:

https://{{your_domain}}.commercelayer.io/metrics

Where {{your_domain}} is the unique subdomain of your Commerce Layer organization.

Authorization

You need to authenticate 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 included in the token.

Headers

Include the following HTTP request headers when making calls to the Metrics API endpoint:

Header	Required	Details
Accept		Must be application/vnd.api.v1+json (learn more about versioning)
Content-Type		Must be application/vnd.api+json
Authorization		Must be Bearer {{your_access_token}}

Where {{your_access_token}} is the access token you get by authenticating 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.

The latest version of the Metrics API is v1 — use application/vnd.api.v1+json as the Accept header to make your calls.

Resources

The Commerce Layer core resources you can do statistics on using the Metrics API currently are:

Resource	Endpoint	Description
Orders	/orders	Your organization orders (draft and pending ones excluded), filtered by the market(s) in scope.
Returns	/returns	Your organization returns, filtered by the market(s) in scope.
Carts	/carts	Your organization draft and pending orders, filtered by the market(s) in scope.

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).

Query types

Commerce Layer Metrics API lets you retrieve metric data through four types of queries:

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

Metric data requests are submitted to the Metrics API through a POST request. Any other method will return an error (see example).

To build the endpoint you need to make your requests just add the name of the resource you want to do statistics on and the type of query you'd like to perform to the base endpoint, like so:

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:

{
  "{{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, date breakdown, stats, or search) and the related fields, operators, and limits.

Filter

The filter object is optional (if missing a 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 of the response. At the moment the only option available for this block is:

Key	Type	Required	Description	Value
payload	Boolean		If true the actual payload used to perform the query will be returned in the response.	Default is false.

{
  "{{query_type}}": { ... },
  "filter": { ... },
  "meta": {
    "payload": true
  }
}

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:

{
  "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 and search) or a single object (breakdown and stats). The returned fields will be detailed case by case, with some examples in the related sections.

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 response only):

{
  "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 results (not available for breakdowns, date breakdowns, and stats).
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.
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 when performing the query).