--- title: Analytics description: Model, query, embed, and enrich analytics on Shopify from your app, without running your own data infrastructure. source_url: html: https://shopify.dev/docs/apps/build/analytics md: https://shopify.dev/docs/apps/build/analytics.md --- # Analytics Shopify Analytics is a platform your app can build on to put your data in front of merchants, in the reports and dashboards they already use, without running your own data infrastructure. Model your data into it, query it with ShopifyQL, embed live charts in your app, and enrich it with merchant context. It's open to your app and to the AI agents that query it for merchants. Everything runs inside Shopify. ## How it works At the center is ShopifyQL, the query language behind Shopify Analytics. The metric cards, dashboards, and reports in the Shopify admin all run on it, and it's how your app reads analytics data. Your app builds on that one query layer with four building blocks you can combine. For example, here's how it could work for an email marketing app: * **Model your app's data**: add a `campaign_source` metafield to orders and send an `email_sent` App Event, so both are queryable alongside store data. * **Query it with ShopifyQL through the GraphQL Admin API**: run a query like `FROM app_events SHOW emails_sent GROUP BY app_name`. * **Embed it with a web component**: show the results on the app's dashboard with a metric card (``). * **Enrich it with an annotation**: mark an event, like a campaign launch, so its impact shows on the merchant's charts. ![Model, Query, Embed, and Enrich — four building blocks on ShopifyQL, the query layer behind Shopify Analytics.](https://shopify-assets.shopifycdn.com/shopifycloud/shopify-dev/production/assets/assets/images/apps/analytics/how-it-works-light-B0K73RSc.png) *** ## Model your app's data into Shopify Analytics Your app's data becomes queryable in Shopify Analytics without a separate analytics store, whether it comes from metafields on records you already use or from App Events you send. ### Metafields Mark a metafield definition as analytics-queryable and its values become a dimension in ShopifyQL, alongside store data. For example, add a `campaign_source` to an order or a `subscription_status` to a customer, and merchants can group, filter, and chart on it in reports. The values already live in Shopify. [Use metafield capabilities\ \ ](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities#analytics-queryable) [Enable the capability and see which metafield types and owners are eligible.](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities#analytics-queryable) ## ShopifyQL query ```shopifyql FROM sales SHOW total_sales GROUP BY order.metafields.my_app.campaign_source ``` ### App Events App Events makes the events your app already sends to Shopify queryable in analytics. Declare your events, send them through the [App Events API](https://shopify.dev/docs/api/app-events), and merchants can query them in ShopifyQL the same way they query store data. One query can compare the same event across every installed app. **Developer preview:** App Events in Analytics is in developer preview. The preview is available to approved apps and supports declared standard events. [Sign up for early access](https://forms.gle/2yLka2Ww3J3cNiGY8). [App Events\ \ ](https://shopify.dev/docs/apps/build/app-events/analytics) [Declare and send your app's events so merchants can query them in analytics.](https://shopify.dev/docs/apps/build/app-events/analytics) ## ShopifyQL query ```shopifyql FROM app_events SHOW emails_sent GROUP BY app_name ``` *** ## Query analytics with Shopify​QL Your app runs ShopifyQL through the GraphQL Admin API with the [`shopifyqlQuery`](https://shopify.dev/docs/api/admin-graphql/unstable/queries/shopifyqlQuery) field. Write a query once and run it in the Shopify admin or with the [Python SDK](https://shopify.dev/docs/apps/build/shopifyql/python-sdk-and-cli). Every metric and dimension is documented with its type and examples, so both developers and AI toolchains can build valid queries. [Query with ShopifyQL\ \ ](https://shopify.dev/docs/apps/build/shopifyql) [The three ways to run ShopifyQL, with setup and examples.](https://shopify.dev/docs/apps/build/shopifyql) [ShopifyQL syntax reference\ \ ](https://shopify.dev/docs/api/shopifyql) [The full ShopifyQL language: keywords, functions, and examples.](https://shopify.dev/docs/api/shopifyql) ## GraphQL Admin API ```graphql query { shopifyqlQuery( query: "FROM sales SHOW total_sales, orders TIMESERIES month DURING last_year" ) { tableData { columns { name dataType } rows } parseErrors } } ``` *** ## Embed analytics with web components Analytics web components render the same charts the Shopify admin uses, so you can show live analytics in your app without building your own charting, currency handling, or locale formatting. Each component runs a ShopifyQL query. [Analytics web components\ \ ](https://shopify.dev/docs/api/shopifyql/latest/web-components) [Component reference, required scripts, and access setup.](https://shopify.dev/docs/api/shopifyql/latest/web-components) ## Metric card ```html ``` ![A ShopifyQL metric card with the heading Total sales, showing the total with its percent change from the previous period above a line chart of daily total sales for the last month.](https://shopify-assets.shopifycdn.com/shopifycloud/shopify-dev/production/assets/assets/images/apps/analytics/shopifyql-metric-card-AO_tJCeK.png) *** ## Enrich analytics with annotations and targets Annotations mark why a metric moved, attributed to your app. A loyalty app can mark the day a program launched, an email app can mark a campaign, and a subscription app can mark a pricing change. Create annotations with the [`analyticsAnnotationCreate`](https://shopify.dev/docs/api/admin-graphql/2026-10/mutations/analyticsAnnotationCreate) mutation on the GraphQL Admin API, read them with [`analyticsAnnotations`](https://shopify.dev/docs/api/admin-graphql/2026-10/connections/AnalyticsAnnotationConnection#reference-Shop.analyticsAnnotations), and overlay them on a chart in ShopifyQL with [`ANNOTATE`](https://shopify.dev/docs/api/shopifyql/latest/syntax/annotate). Metric targets let merchants set a goal for a metric, such as total sales for the quarter, and track progress in reports and dashboards. Create targets with the [`analyticsTargetCreate`](https://shopify.dev/docs/api/admin-graphql/2026-10/mutations/analyticsTargetCreate) mutation on the GraphQL Admin API, read them with [`analyticsTargets`](https://shopify.dev/docs/api/admin-graphql/2026-10/queries/analyticsTargets), and compare against them in ShopifyQL with [`COMPARE TO TARGETS`](https://shopify.dev/docs/api/shopifyql/latest/syntax/compare-to). [Annotations\ \ ](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/AnalyticsAnnotation) [Create, read, and manage annotations through the GraphQL Admin API.](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/AnalyticsAnnotation) [Metric targets\ \ ](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/AnalyticsTarget) [Create and read metric targets through the GraphQL Admin API.](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/AnalyticsTarget) #### Create an annotation ## GraphQL Admin API ```graphql mutation { analyticsAnnotationCreate(input: { type: "campaign" title: "Email campaign sent" startedAt: "2026-02-06T09:00:00Z" }) { analyticsAnnotation { id type title } userErrors { field message } } } ``` #### Overlay on a chart ## ShopifyQL ```shopifyql FROM sales SHOW gross_sales GROUP BY day WITH PERCENT_CHANGE, TOTALS TIMESERIES day SINCE 2026-02-01 UNTIL 2026-02-28 COMPARE TO previous_period VISUALIZE gross_sales TYPE line ANNOTATE ALL ``` ![A gross sales line chart with a comparison line and annotation markers along the timeline. A tooltip for February 6, 2026 shows three annotations at that date: an email campaign, a program change, and a theme edit.](https://shopify-assets.shopifycdn.com/shopifycloud/shopify-dev/production/assets/assets/images/apps/analytics/annotations-overlay-B0lIPJmq.png) #### Create a target ## GraphQL Admin API ```graphql mutation { analyticsTargetCreate(input: { metric: "total_sales" name: "Q3 sales target" startDate: "2026-07-01" endDate: "2026-09-30" expectedValue: "50000.00" }) { analyticsTarget { id name metric expectedValue } userErrors { field message } } } ``` #### Compare to targets ## ShopifyQL ```shopifyql FROM sales SHOW total_sales DURING this_year COMPARE TO TARGETS ``` ***