To access the Analytics API, a shop must have the advanced report builder feature, included in the Advanced Shopify plan and up. In the API, this feature is called
To start using the Analytics API in your app, include the
app.js at the top of your app's
<head> element. It has no dependencies and plays well with other libraries like jQuery.
The SDK should be initialized with the API key and shop's origin immediately after including the
This makes the
ShopifyApp object available and ready for use.
Now that the Embedded App SDK is configured, we can make a request to the Analytics API:
Valid responses from the Analytics API are returned in JSON. Given the following ShopifyQL query
SHOW sum(pageview_count) OVER day(timestamp) FROM visits SINCE -1d UNTIL today string, we would expect a response of the form:
|field||column name eg: day|
|type||column type (property or measure*)|
|format||the data type|
- A property is an attribute of an object, useful for defining groups (e.g. id, name, location).
- A measure is a reference to the value of a property or what's being aggregated (e.g., count of people from location, average name length).
The API will return errors for invalid ShopifyQL statements. It could also return two specific errors you should be aware of:
"Application is missing 'read_analytics' scope"
This error means that your app was not set up with the
read_analytics OAuth scope. You will need to add the scope and have the merchant log in.
"Shop is missing 'reports' feature"
This error should be handled by your app for the best user experience. This means that the store running your app does not have privileges to run the Analytics API. You can choose to use to a different datasource, not display the data you were requesting, or let the user know the reason they cannot see data.