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).
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).https://{{your_domain}}.commercelayer.io/metrics
Where
{{your_domain}} is the unique subdomain of your Commerce Layer organization.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.
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}} |
Where
{{your_access_token}} is the access token you get by authenticating to Commerce Layer core API.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.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 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. |
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
"...": ...
}
}
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.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.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
}
}
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 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.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 | |
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). |
Last modified 1mo ago