j1.0.0
API Overview
The Analytics API provides metadata and query access to the analytics data in the Commerce Intelligence Platform. Use it to discover the subject areas available to your organization, inspect the dimensions and measures that each subject area exposes, and run structured queries that return aggregated reporting data.
A subject area is a curated set of related dimensions (attributes you group by, such as site_name or utc_submit_timestamp) and measures (values you aggregate, such as units or revenue). You query a subject area by specifying the dimensions and measures to return, optional filters and sort order, and pagination controls.
Authentication & Authorization
The Analytics API requires an Account Manager access token.
For details on how to request an access token, see Authorization for Admin APIs.
You must include sfcc.analytics in the client ID used to generate the token. For a full list of permissions, see the Authorization Scopes Catalog.
Response Details
Caching
Responses from this API are not cached. Query results are computed per request and reflect the latest available analytics data. Results also vary with the dimensions, measures, filters, and pagination specified in each request. For details, see Server-Side Web-Tier Caching.
Timeouts
Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see Timeouts and Limits.
Error Handling
Error responses follow the RFC 7807 problem detail format. To trace errors, include a correlation-id header in your request — the response returns it as x-correlation-id. For details, see HTTP Status Codes and Errors.
Use Cases
Discover available subject areas
Retrieve the list of subject areas your organization can query before building a report. Use the returned IDs with the metadata and query endpoints.
curl -X GET \
"https://{shortCode}.api.commercecloud.salesforce.com/intelligence/analytics/v1/organizations/{organizationId}/subject-areas" \
-H "Authorization: Bearer {access_token}"
Inspect a subject area's dimensions and measures
Before you build a query, retrieve a subject area's metadata to see which dimensions and measures are available, along with their data types. Use these IDs to construct valid queries.
curl -X GET \
"https://{shortCode}.api.commercecloud.salesforce.com/intelligence/analytics/v1/organizations/{organizationId}/subject-areas/orderitems" \
-H "Authorization: Bearer {access_token}"
Query subject area data for reporting
Run a structured query to return aggregated data for reporting and analytics. Specify the dimensions and measures to return, optional filters and sort order, and use limit and offset to page through results. The response echoes your original query, including pagination parameters, in the query object.
curl -X POST \
"https://{shortCode}.api.commercecloud.salesforce.com/intelligence/analytics/v1/organizations/{organizationId}/query/orderitems" \
-H "Authorization: Bearer {access_token}" \
-H "Content-Type: application/json" \
-d '{
"dimensions": ["utc_submit_timestamp", "site_name"],
"measures": ["units"],
"filters": [
{ "dimension": "utc_submit_timestamp", "operator": "gt", "values": ["2020-01-01"] }
],
"order": [
{ "field": "utc_submit_timestamp", "order": "asc" }
],
"limit": 100,
"offset": 0
}'
Best Practices
- Discover metadata before querying. Use the subject-areas endpoints to confirm the exact dimension and measure IDs and their data types. Querying with IDs that don't belong to the subject area returns an HTTP 400 error.
- Page through large result sets. Use
limitandoffsetin the query request body to retrieve results in manageable batches, and read the echoedqueryobject in the response to track your pagination position. - Filter and sort on the server. Apply
filtersandorderin the query request instead of retrieving all rows and processing them client-side. This reduces response size and improves performance. - Use the
fieldsarray to render results. The responsefieldsarray lists all column keys in order (dimensions followed by measures), so you can iterate columns for tabular output without concatenatingdimensionsandmeasuresyourself.
Let us know so we can improve!