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
  • Base endpoint
  • Authorization
  • Headers
  • API versioning
  • Resources
  • Query types
  • Request
  • Response
  1. Getting started

API specification

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

PreviousWelcome to Metrics APINextQueries

Last updated 1 year ago

In addition to the , 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 and the option to the results.

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

The guide that follows is your reference for all the operations (, , , and ) that you can perform on the resource available to do statistics on (, , and ) 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 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 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 included in the token.

Headers

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

Header
Required
Details

Accept

Content-Type

Must be application/vnd.api+json

Authorization

Must be Bearer {{your_access_token}}

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

Resource
Endpoint
Description

Orders

/orders

Returns

/returns

Carts

/carts

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

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

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

Filter

Meta

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

Meta

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

type

String

The query type (one of breakdown, date_breakdown, stats, or search).

trace_id

String

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

Must be application/vnd.api.v1+json (learn more about )

Where {{your_access_token}} is the access token you get by to Commerce Layer core API.

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

Your organization (draft and pending ones excluded), filtered by the market(s) in scope.

Your organization , filtered by the market(s) in scope.

Your organization draft and pending , filtered by the market(s) in scope.

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

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

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

The query object is required and specifies the type of query you're going to perform (one of , , , or ) and the related fields, operators, and limits.

The filter object is optional (if missing a 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.

The meta object is optional and can be used to customize the information that will be returned in the of the response. At the moment the only option available for this block is:

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

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

Contains the total record_count and the cursor pointing at the next page, useful to navigate through the results (not available for , , and ).

The ID of the user's web request, useful for debugging in case of .

The payload of the query you performed, filled with any computed and/or default values (returned only if when performing the query).

queries
authenticating
resource
type of query
base endpoint
corresponding object
orders
returns
orders
errors
versioning
explicitly requested
core commerce API
queries
filter
UTF-8
strings parameters
ISO 8601
breakdown
date breakdown
stats
search
HTTPS
authenticate
scopes
orders
returns
carts
sections
breakdowns
date breakdowns
stats
core resources
stats
stats
see example
date breakdown
date breakdown
here
default filter
breakdown
breakdown
search
search
search queries
search