--- schema_version: "1" id: 8970599696e7e30f9ce250fc5b5662d59ce57bac62667f2a2fc0f8eb1fac57dd title: Salesforce Commerce Analytics API collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/salesforce-commerce/references/generated-api-specs/comm-analytics-ref.md canonical_url: https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-analytics-ref source_site: developer.salesforce.com content_type: documentation content_hash: 35cd1bcbbcf0a574b8b17f25c801ea8cd7bec495e1461af37117352ed2370cb2 products: - B2B Commerce Developer Guide - Salesforce APIs --- Salesforce Commerce Analytics API # Salesforce Commerce Analytics API This API retrieves details about key performance indicators (KPIs), including their associated data and insights. **Version:** 66.0 ## Servers * `https://{yourinstance}.salesforce.com/services/data/{version}` * `version (default v66.0): v66.0, v65.0, v64.0, v63.0, v62.0` ## Operations ### GET commerceIntelligenceKPIsGet `GET /commerce/intelligence/kpis` Operation ID: `commerceIntelligenceKPIsGet`. Retrieves a list of KPIs and the insights each KPI provides. Fetches a list of KPIs and the insights each KPI supports. #### Responses * **200** Success Media type: `application/json`. Schema: `KPIMetaDataCollectionRepresentation`. * **400** Bad Request. Media type: `application/json`. Schema: `object`. * `apiErrorCode` (_string_) The error code. * `message` (_string_) The error message. ### GET commerceIntelligenceKPIDataGet `GET /commerce/intelligence/kpis/{kpiName}` Operation ID: `commerceIntelligenceKPIDataGet`. Provides point-in-time data for KPIs based on the current time range, an optional previous time range, and webstore. If only startDateTime and endDateTime are specified, the value field shows the KPI and insight values within that period. If previousStartDate and previousEndDateTime are also provided, the previousValue field will be populated with data from the previous time range. Additionally, the API returns insights if requested, using the same filter criteria. It also returns the relative dashboard URL if the KPI and insight are part of any dashboard. Retrieves KPI data for the specified time range. The API also returns insights data for the KPI when the appropriate query parameters are provided. #### Parameters * `kpiName` (path, string, required) Name of the KPI. _Example_ ``` average_order_value ``` * `webstoreId` (query, string, required) Required. Query the KPI and insight within the specific store context. If not specified, the KPI is calculated across all webstores for the org. _Example_ ``` 0ZExx000000004DGAQ ``` * `startDateTime` (query, string (date-time)) Optional. Specifies the start date and time for the current timeframe of the KPI and insights. The maximum supported range between the start and end dates is 180 days. If not provided, it defaults to 30 days prior to the current date. _Example_ ``` 2018-03-20T09:12:28Z ``` * `endDateTime` (query, string (date-time)) Optional. Specifies the end date and time for the current timeframe of the KPI and insights. If not provided, defaults to TODAY. _Example_ ``` 2018-03-20T09:12:28Z ``` * `previousStartDateTime` (query, string (date-time)) Optional. Specifies the start date and time for the previous timeframe of the KPI and insights. The maximum supported range between the start and end dates is 180 days. If previousStartDateTime is provided, previousEndDateTime must also be specified. _Example_ ``` 2018-03-20T09:12:28Z ``` * `previousEndDateTime` (query, string (date-time)) Optional. Specifies the end date and time for the previous timeframe of the KPI and insights. If previousEndDateTime is provided, previousStartDateTime must also be specified. _Example_ ``` 2018-03-20T09:12:28Z ``` * `insightNames` (query, string) Optional. Comma-separated list of insight names to include in the response, with a maximum of 10 insights. _Example_ ``` top_performing_products ``` * `insightValueLimit` (query, integer) Optional. Specifies the maximum number of insight records to return. For instance, with an insightValueLimit of 3 for the top-performing products insight, the API returns 3 top-performing products. The maximum supported value is 10, and the default is 3 if not specified. _Example_ ``` 3 ``` #### Responses * **200** Success Media type: `application/json`. Schema: `KPIDataRepresentation`. * **400** Bad Request. Media type: `application/json`. Schema: `object`. * `apiErrorCode` (_string_) The error code. * `message` (_string_) The error message. _Example_ ``` { "Invalid endDateTime": { "$ref": "#/components/examples/InvalidEndDateTime" } } ``` _Example_ ``` { "Invalid previousEndDateTime duration": { "$ref": "#/components/examples/InvalidPreviousEndDateTimeDuration" } } ``` _Example_ ``` { "Invalid insightValueLimit": { "$ref": "#/components/examples/InvalidInsightValueLimit" } } ``` _Example_ ``` { "Invalid previousEndDateTime": { "$ref": "#/components/examples/InvalidPreviousEndDateTime" } } ``` _Example_ ``` { "Invalid previousStartDateTime": { "$ref": "#/components/examples/InvalidPreviousStartDateTime" } } ``` _Example_ ``` { "InsightNames limit exceeded": { "$ref": "#/components/examples/InputInsightNamesLimitExceeded" } } ``` * **404** KPI data resource not found. Media type: `application/json`. Schema: `object`. * `apiErrorCode` (_string_) The error code. * `message` (_string_) The error message. _Example_ ``` { "KPI name not found": { "$ref": "#/components/examples/KPINameNotFound" } } ``` _Example_ ``` { "InsightName name not found": { "$ref": "#/components/examples/InsightNameNotFound" } } ``` _Example_ ``` { "WebStore access denied": { "$ref": "#/components/examples/WebStoreAccessDenied" } } ``` _Example_ ``` { "Commerce Intelligence not configured": { "$ref": "#/components/examples/CommerceIntelligenceNotConfigured" } } ``` ## Schemas ### KPIMetaDataCollectionRepresentation * `kpis` (_array of KPIMetaDataRepresentation_) ### KPIDataRepresentation * `name` (_string_) API name of the KPI. Allowed values: `average_order_value`, `gross_sales`, `total_number_of_orders`, `site_conversion_rate`. _Example_ ``` average_order_value ``` * `value` (_number (double)_) KPI value for the specified time frame. _Example_ ``` 1000 ``` * `previousValue` (_number (double)_) KPI value for the previous time frame. _Example_ ``` 1001 ``` * `type` (_string_) Specifies the KPI value type. For example, for a KPI like gross\_sales, a "type" of CURRENCY means the "value" must be interpreted as currency. Allowed values: `CURRENCY`, `NUMBER`. _Example_ ``` CURRENCY ``` * `currencyISOCode` (_string_) Specifies the ISO currency code for the KPI data values. _Example_ ``` USD ``` * `startDateTime` (_string (date-time)_) Specifies the start date and time for the current timeframe of the KPI and insight. _Example_ ``` 2024-04-01T00:00:00Z ``` * `endDateTime` (_string (date-time)_) Specifies the end date and time for the current timeframe of the KPI and insight. _Example_ ``` 2024-05-01T00:00:00Z ``` * `previousStartDateTime` (_string (date-time)_) Specifies the start date and time for the previous timeframe of the KPI and insight. If specified in the request, it will be included in the response. _Example_ ``` 2024-03-01T00:00:00Z ``` * `previousEndDateTime` (_string (date-time)_) Specifies the end date and time for the previous timeframe of the KPI and insight. If specified in the request, it will be included in the response. _Example_ ``` 2024-04-01T00:00:00Z ``` * `dashboardUrl` (_string_) Specifies the relative URL of the dashboard where the KPI is visualized. _Example_ ``` /lightning/n/standard-CommerceStores?target=intelligence&channelId=0ZESG000000np9T4AQ ``` * `kpiSummary` (_string_) Localized, human-readable summary of the change in the KPI value. _Example_ ``` Average order value increased to $109.00 from $80.00 over the last month. ``` * `insights` (_array of InsightRepresentation_) ### KPIMetaDataRepresentation * `name` (_string_) API name of the KPI. Allowed values: `average_order_value`, `gross_sales`, `total_number_of_orders`, `site_conversion_rate`. _Example_ ``` average_order_value ``` * `label` (_string_) Localized label of the KPI. _Example_ ``` Average Order Value ``` * `description` (_string_) A localized description that defines what the KPI represents. _Example_ ``` Average order value (AOV) refers to the average amount spent by customers per transaction. ``` * `insights` (_array of InsightMetaDataRepresentation_) ### InsightRepresentation * `name` (_string_) API name of the insight. Allowed values: `top_performing_products`, `bottom_performing_products`, `top_performing_categories`, `bottom_performing_categories`, `top_contributing_locations`, `bottom_contributing_locations`, `top_converting_products`, `bottom_converting_products`. _Example_ ``` bottom_performing_category ``` * `insightSummary` (_string_) Localized, human-readable summary of the change in the insight value. _Example_ ``` Top-performing categories are iPod and MP3 Players and Women's Clothing, accounting for 10% of average order value (AOV). ``` * `dashboardUrl` (_string_) Specifies the relative URL of the dashboard where the insight is visualized. _Example_ ``` /lightning/n/standard-CommerceStores?target=intelligence&channelId=0ZESG000000np9T4AQ ``` * `values` (_array of InsightValueRepresentation_) ### InsightMetaDataRepresentation * `name` (_string_) API name of the insight. Allowed values: `top_performing_products`, `bottom_performing_products`, `top_performing_categories`, `bottom_performing_categories`, `top_contributing_locations`, `bottom_contributing_locations`, `top_converting_products`, `bottom_converting_products`. _Example_ ``` bottom_performing_products ``` * `label` (_string_) Localized label of the insight. _Example_ ``` Bottom Performing Products ``` * `description` (_string_) A localized description that defines what the insight data represents. _Example_ ``` Bottom-performing products refer to those with the lowest contribution to sales. ``` ### InsightValueRepresentation * `contextId` (_string_) Specifies the Salesforce ID of the record on which the insight is based. For example, for bottom\_performing\_category, contextId would be the product category ID. _Example_ ``` 0ZGSG00000099tq4AA ``` * `name` (_string_) Specifies the localized name of the record on which the insight is based. For example, for bottom\_performing\_category, name would be the localized category name. _Example_ ``` IPhone 15 ``` * `value` (_number (double)_) Specifies the value of the insight for the current timeframe based on the KPI. For example, if the KPI is gross\_sales and the insight is top\_performing\_product, the insight value would be the total gross sales of the top-performing product during the current timeframe. _Example_ ``` 1100.9 ``` * `previousValue` (_number (double)_) Specifies the value of the insight for the previous timeframe based on the KPI. For example, if the KPI is gross\_sales and the insight is top\_performing\_product, the previous value of the insight would be the total gross sales of the top-performing product during the previous timeframe. _Example_ ``` 1101.4 ```