--- schema_version: "1" id: 0a0ce8c5e37127bd753c24aeb4f314347192c3ca63fe12b26d336ef49e225369 title: Analytics collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/analytics.md canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/analytics source_site: developer.salesforce.com content_type: documentation content_hash: c0c635fef7ef0366675fe73a006165729a3e2744e8ab60103ed90917d24abc22 products: - B2C Commerce API - Salesforce APIs --- Analytics # Analytics [Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/analytics/analytics-oas-v1-public.yaml) ## API Overview The Commerce Intelligence API provides access to metadata and query capabilities for analytics data available in the Commerce Intelligence Platform. Use this API to discover available subject areas and their dimensions and measures, and to query data for reporting and analytics purposes. ### Features * **List Subject Areas**: Retrieve all available subject areas for an organization * **Subject Area Details**: Get detailed metadata including dimensions, measures, display names, and data types for a specific subject area * **Query Subject Area Data**: Query specific subject area data for reporting and analytics * **Flexible Filtering**: Filter by dimensions using operators such as equals, gt, lt, contains, date ranges, and more * **Sorting**: Order results by any field in ascending or descending order * **Pagination**: Built-in pagination support with configurable limit and offset ### Endpoints #### GET /organizations/{organizationId}/subject-areas Retrieve a list of all available subject areas in an organization. **Parameters:** * `organizationId` (required) - The organization identifier #### GET /organizations/{organizationId}/subject-areas/{subjectAreaId} Retrieve metadata about a specific subject area, including its dimensions and measures. **Parameters:** * `organizationId` (required) - The organization identifier * `subjectAreaId` (required) - The subject area to retrieve metadata for (e.g., orderitems) #### POST /organizations/{organizationId}/query/{subjectAreaId} Query subject area data within an organization. Specify dimensions, measures, filters, and ordering in the request body. **Parameters:** * `organizationId` (required) - The organization identifier * `subjectAreaId` (required) - The subject area to query (e.g., orderitems) ### Authentication and Authorization This API uses OAuth 2.0 client credentials flow via Account Manager with the following scope: * `sfcc.analytics` - Access to analytics subject areas, metadata, and query operations **Version:** 1.0.0 ## Servers * `https://{shortCode}.api.commercecloud.salesforce.com/intelligence/analytics/v1` * `shortCode (default 0dnz6oep) A region-specific merchant identifier.` ## Security * `AmOAuth2` (oauth2) Account Manager OAuth 2.0 bearer token authentication. * OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token) * Scope sfcc.analytics: Access to analytics subject areas, metadata, and query operations * OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token) * Scope sfcc.analytics: Access to analytics subject areas, metadata, and query operations ## Operations ### GET Get Subject Areas `GET /organizations/{organizationId}/subject-areas` Operation ID: `getSubjectAreas`. Security: AmOAuth2 (sfcc.analytics). Retrieve a list of subject areas. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` #### Responses * **200** Subject Areas Response Media type: `application/json`. Schema: `SubjectAreasResponse`. _Example: subjectAreasExample_ ``` { "data": [ "orderitems", "sessions", "pageviews" ] } ``` * **400** Malformed query or request body parameter Media type: `application/problem+json`. Schema: `MalformedParameterErrorResponse`. _Example: MalformedParameterErrorResponseExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/malformed-parameter", "detail": "The requested query or request body parameter 'subjectAreaId' is malformed.", "title": "Malformed Parameter" } ``` * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Unauthorized request" } ``` * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ForbiddenExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "Access to requested resource forbidden" } ``` ### GET Get Subject Area by ID `GET /organizations/{organizationId}/subject-areas/{subjectAreaId}` Operation ID: `getSubjectAreaById`. Security: AmOAuth2 (sfcc.analytics). Access metadata about a subject area #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `subjectAreaId` (path, SubjectAreaId, required) The subject area to retrieve metadata for or to query #### Responses * **200** Subject Area Response Media type: `application/json`. Schema: `SubjectArea`. _Example: subjectAreaResponseExample_ ``` { "id": "orderitems", "displayName": "Order Items", "description": "Order item level data", "tags": [ "orders", "commerce" ], "dimensions": [ { "id": "utc_submit_timestamp", "displayName": "Submit Timestamp (UTC)", "description": "The UTC timestamp when the order was submitted", "type": "timestamp" }, { "id": "site_name", "displayName": "Site Name", "description": "The name of the site", "type": "string" } ], "measures": [ { "id": "units", "displayName": "Units", "description": "Number of units ordered", "type": "integer" }, { "id": "revenue", "displayName": "Revenue", "description": "Total revenue amount", "type": "decimal" } ] } ``` * **400** Malformed query or request body parameter Media type: `application/problem+json`. Schema: `MalformedParameterErrorResponse`. _Example MalformedParameterErrorResponseExample: same as GET /organizations/{organizationId}/subject-areas 400 response._ * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Unauthorized request" } ``` * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ForbiddenExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "Access to requested resource forbidden" } ``` * **404** Subject Area Not Found Media type: `application/problem+json`. Schema: `SubjectAreaNotFoundErrorResponse`. _Example: SubjectAreaNotFoundErrorResponseExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/subject-area-not-found", "detail": "The requested 'orderitems' subject area was not found.", "title": "Subject Area Not Found" } ``` ### POST Query subject area data `POST /organizations/{organizationId}/query/{subjectAreaId}` Operation ID: `querySubjectArea`. Security: AmOAuth2 (sfcc.analytics). Query subject area data for reporting and analytics purposes. Use `limit` and `offset` in the request body to control pagination. The response echoes the original query, including pagination parameters, in the `query` object. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `subjectAreaId` (path, SubjectAreaId, required) The subject area to retrieve metadata for or to query #### Request body (required) The query request document Media type: `application/json`. Schema: `QueryRequest`. _Example: queryRequestExample_ ``` { "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 } ``` _Example: queryRequestSetOperatorExample_ Filter using set / not\_set operators Example showing the `set` and `not_set` operators. These check for the presence or absence of a value on a dimension and do not take operands, so `values` must be an empty array (`[]`). ``` { "dimensions": [ "utc_submit_timestamp", "site_name" ], "measures": [ "units" ], "filters": [ { "dimension": "site_name", "operator": "set", "values": [] }, { "dimension": "campaign_id", "operator": "not_set", "values": [] } ], "limit": 100, "offset": 0 } ``` #### Responses * **200** Successful query response Media type: `application/json`. Schema: `QueryResponse`. _Example: queryResponseExample_ ``` { "subjectAreaId": "orderitems", "query": { "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 }, "dimensions": [ "utc_submit_timestamp", "site_name" ], "measures": [ "units" ], "fields": [ "utc_submit_timestamp", "site_name", "units" ], "data": [ { "utc_submit_timestamp": "2020-01-01", "site_name": "Sites-SiteGenesis-Site", "units": 42 }, { "utc_submit_timestamp": "2020-01-01", "site_name": "Sites-SiteGenesisGlobal-Site", "units": 37 }, { "utc_submit_timestamp": "2020-01-02", "site_name": "Sites-SiteGenesis-Site", "units": 12 }, { "utc_submit_timestamp": "2020-01-02", "site_name": "Sites-SiteGenesisGlobal-Site", "units": 75 } ] } ``` * **400** Malformed query or request body parameter Media type: `application/problem+json`. Schema: `MalformedParameterErrorResponse`. _Example MalformedParameterErrorResponseExample: same as GET /organizations/{organizationId}/subject-areas 400 response._ * **401** Your access token is invalid or expired and can’t be used to identify a user. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: UnauthorizedExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Unauthorized request" } ``` * **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: ForbiddenExample_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "title": "Forbidden", "detail": "Access to requested resource forbidden" } ``` * **404** Subject Area Not Found Media type: `application/problem+json`. Schema: `SubjectAreaNotFoundErrorResponse`. _Example SubjectAreaNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/subject-areas/{subjectAreaId} 404 response._ ## Schemas ### OrganizationId An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). Type: `string`. Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`. ### SubjectAreasResponse * `data` (_array of string_) Items: Minimum length: 1. Maximum length: 256. Example: `orderitems`. _Example_ ``` { "data": [ "orderitems", "sessions", "pageviews" ] } ``` ### MalformedParameterErrorResponse Returned when a query or request body parameter is malformed. Includes all fields of `ErrorResponse`. * `parameterId` (_string_) Minimum length: 1. Maximum length: 256. Example: `subjectAreaId`. _Example_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/malformed-parameter", "title": "Malformed Parameter", "detail": "The requested query or request body parameter 'subjectAreaId' is malformed." } ``` ### ErrorResponse * `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization Maximum length: 256. Example: `You do not have enough credit`. * `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5. Maximum length: 2048. Example: `NotEnoughMoney`. * `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem. Example: `Your current balance is 30, but that costs 50`. * `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5. Maximum length: 2048. Example: `/account/12345/msgs/abc`. ### SubjectAreaId The unique identifier of the subject area Type: `string`. Minimum length: 1. Maximum length: 256. Example: `orderitems`. ### SubjectArea * `id` (_SubjectAreaId_, required) * `description` (_string_) Description of the subject area Minimum length: 1. Maximum length: 1024. Example: `Order item level data`. * `tags` (_array of string_) Tags associated with the subject area Items: Minimum length: 1. Maximum length: 256. Example: `orders`. _Example_ ``` [ "orders", "commerce" ] ``` * `displayName` (_string_, required) The display name of the subject area Minimum length: 1. Maximum length: 256. Example: `Order Items`. * `dimensions` (_array of Dimension_, required) Array of dimension metadata for the subject area * `measures` (_array of Measure_, required) Array of measure metadata for the subject area ### SubjectAreaNotFoundErrorResponse Returned when the requested subject area was not found. Includes all fields of `ErrorResponse`. * `subjectAreaId` (_SubjectAreaId_) _Example_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/subject-area-not-found", "title": "Subject Area Not Found", "detail": "The requested 'orderitems' subject area was not found.\"", "subjectAreaId": "orderitems" } ``` ### QueryRequest * `dimensions` (_array of DimensionId_, required) Array of dimension IDs to include in the query _Example_ ``` [ "utc_submit_timestamp", "site_name" ] ``` * `measures` (_array of MeasureId_, required) Array of measure IDs to include in the query _Example_ ``` [ "units" ] ``` * `filters` (_array of DimensionFilter | MeasureFilter_) Array of filter expressions for dimensions or measures _Example_ ``` [ { "dimension": "utc_submit_timestamp", "operator": "gt", "values": [ "2020-01-01" ] } ] ``` * `order` (_array of SortOrder_) Array of ordering expressions _Example_ ``` [ { "field": "utc_submit_timestamp", "order": "asc" } ] ``` * `limit` (_integer_) Maximum number of results to return Minimum: 1. Example: `100`. * `offset` (_integer_) Number of results to skip Minimum: 0. Example: `0`. ### QueryResponse * `subjectAreaId` (_object_, required) The subject area that was queried Example: `orderitems`. Includes all fields of `SubjectAreaId`. Example: `orderitems`. * `query` (_QueryRequest_, required) * `dimensions` (_array of DimensionId_, required) Array of dimension IDs in the response _Example_ ``` [ "utc_submit_timestamp", "site_name" ] ``` * `measures` (_array of MeasureId_, required) Array of measure IDs in the response _Example_ ``` [ "units" ] ``` * `fields` (_array of string_, required) Ordered list of all column keys in the response — the concatenation of `dimensions` and `measures`. Each entry is a `DimensionId` or `MeasureId` string. Provided as a convenience for tabular rendering so consumers can iterate columns in order without having to concatenate `dimensions` and `measures` themselves. Items: Minimum length: 1. Maximum length: 256. Example: `utc_submit_timestamp`. _Example_ ``` [ "utc_submit_timestamp", "site_name", "units" ] ``` * `data` (_array of object_, required) Array of result objects containing the queried data. Each object has keys corresponding to the requested dimension and measure IDs. Value types vary based on each field's data type as described in the subject area metadata (e.g., string, integer, decimal, timestamp). ### Dimension * `id` (_DimensionId_, required) * `displayName` (_string_) The display name of the dimension Minimum length: 1. Maximum length: 256. Example: `Submit Timestamp (UTC)`. * `description` (_string_) Description of the dimension Minimum length: 1. Maximum length: 1024. Example: `The UTC timestamp when the order was submitted`. * `type` (_string_, required) The data type of the dimension Minimum length: 1. Maximum length: 256. Example: `timestamp`. ### Measure * `id` (_MeasureId_, required) * `displayName` (_string_) The display name of the measure Minimum length: 1. Maximum length: 256. Example: `Units`. * `description` (_string_) Description of the measure Minimum length: 1. Maximum length: 1024. Example: `Number of units ordered`. * `type` (_string_, required) The data type of the measure Minimum length: 1. Maximum length: 256. Example: `integer`. ### DimensionId The unique identifier of the dimension Type: `string`. Minimum length: 1. Maximum length: 256. Example: `utc_submit_timestamp`. ### MeasureId The unique identifier of the measure Type: `string`. Minimum length: 1. Maximum length: 256. Example: `units`. ### DimensionFilter Includes all fields of `Filter`. * `dimension` (_string_, required) The dimension to filter on Minimum length: 1. Maximum length: 256. Example: `utc_submit_timestamp`. ### MeasureFilter Includes all fields of `Filter`. * `measure` (_string_, required) The measure to filter on Minimum length: 1. Maximum length: 256. Example: `units`. ### SortOrder * `field` (_string_, required) The field to order by Minimum length: 1. Maximum length: 256. Example: `utc_submit_timestamp`. * `order` (_string_, required) The sort order (ascending or descending) Allowed values: `asc`, `desc`. Example: `asc`. ### Filter * `operator` (_string_, required) The filter operator to apply Allowed values: `equals`, `not_equals`, `contains`, `not_contains`, `gt`, `lt`, `gte`, `lte`, `set`, `not_set`, `in_date_range`, `not_in_date_range`, `before_date`, `after_date`. Example: `gt`. * `values` (_array of string_, required) Array of values for the filter. For operators `set` and `not_set`, which check for the presence or absence of a value, pass an empty array (`[]`) since these operators do not take operands. Items: Minimum length: 1. Maximum length: 256. Example: `2020-01-01`. _Example_ ``` [ "2020-01-01" ] ```