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:
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:
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:
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
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:
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:
The JSON data payload you need to send in the request body is composed of three main blocks:
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:
payload
Boolean
If true
the actual payload used to perform the query will be returned in the response.
Default is false
.
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
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):
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
).
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 updated