API specification
Basic info about endpoints and access tokens, request types and headers, payload and response structure
Last updated
Basic info about endpoints and access tokens, request types and headers, payload and response structure
Last updated
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 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 ).
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.
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.
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:
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.
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.
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.
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:
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
.
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:
pagination
Object
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).
The Commerce Layer you can do statistics on using the Metrics API currently are:
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.
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 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 response only):
Contains the total record_count
and the cursor
pointing at the next page, useful to navigate through the results (not available for breakdowns, date breakdowns, and stats).