Developer Changelog / Apps × Analytics

App Events in Analytics
App activity data now appears in Shopify Analytics reports

When an app declares events in an analytics_app_events extension and sends them via the App Events API, merchants can use the report builder or ShopifyQL (FROM app_events) to analyze the app's metrics and dimensions.

On this page
  1. What's changing (30-second overview)
  2. How it works: Declare → Send → Report
  3. 3 patterns for declaring events
  4. Who's affected / What happens to existing integrations
  5. Getting started (3 steps)
  6. Code examples: TOML declaration and ShopifyQL
  7. 5 key points for developers
  8. 3 business use cases
  9. One-line summary for proposals

1What's changing

Until now, app activity data (e.g., number of emails sent) could only be viewed in the app's own admin or a separate dashboard.
Starting now, events declared and sent by apps can be reported on by merchants directly in Shopify Analytics .

Before: Fragmented analytics

Viewing app metrics required opening a separate dashboard. App developers had to build and host their own analytics screens.

Now: Integrated into Shopify Analytics

Merchants analyze app metrics without leaving Shopify, using either the report builder or ShopifyQL. Developers no longer need to build or host their own analytics infrastructure.

2How it works: Declare → Send → Report

① Declare shopify.extension.toml analytics_app_events standard / custom Developer ② Release shopify app deploy Declaration becomes "released" Shopify CLI ③ Send App Events API Events matching the declaration (for stores with the app installed) App backend ④ Report Report builder ShopifyQL: FROM app_events Merchant
The key point: both declaring and sending are required . Sending alone or declaring alone won't make data appear in reports.Only events that match a released declaration appear in Shopify Analytics after processing.

3Three types of events you can declare

standard

Shopify-defined standard events

For common event types such as "email sent," use the standard events defined by Shopify. Example: shopify.marketing.email_sent. The full list is in the Standard event registry.

custom

Custom events

You can define your own events with app-specific attributes and metrics .

standard + extension

Extend a standard event

Start from a standard event and add your app's own attributes and metrics.

4Who's affected / How existing integrations are handled

SituationHandlingRequired action
Developers who want to surface app activity in Shopify Analytics Eligible Can use this new feature Declare in an extension → deploy → send via API
Already sending App Events for Dev Dashboard logs or billing Not shown automatically Not reflected in Analytics Only if you want them in Analytics:match them to a released Analytics App Events declaration
Don't want to change your existing App Events integration No change needed None (act only if you want them shown in Analytics)
Pricing, supported plans, and data retention Not stated Check the guide and API reference
No action required. Only get started if you want to show your app's activity in Shopify Analytics (opt-in).

5Getting started (3 steps)

1

Declare events in an extension

shopify.extension.toml : add a analytics_app_events extension and declare standard or custom events.

2

shopify app deploy to release

Release the configuration to make the declarations active.

3

Send via the App Events API

Send events matching your declarations for stores where the app is installed. They become reportable once processed.

6Code example: TOML declaration and ShopifyQL

① Declaration (shopify.extension.toml)

Example of an email marketing app declaring the standard "email sent" event.

[[extensions]]
type = "analytics_app_events"
handle = "app-events"

[[extensions.events]]
name = "shopify.marketing.email_sent"
kind = "standard"
② Merchant-side query (ShopifyQL)

Example of aggregating emails sent as a daily time series after events are processed.

FROM app_events
 SHOW emails_sent
 TIMESERIES day

The same data can also be explored in the report builder (GUI).

The App Events API payload format, the TOML syntax for custom event attributes/metrics, and processing time are not coveredin this article. See the "App Events in Analytics" guide, "Configure Analytics App Events", and the "App Events API reference".

75 key points for developers

Declare Send

1. Declaring and sending go together

Events must be declared in an analytics_app_events extension and released viashopify app deploy beforehand. Events that don't match a declaration won't appear in Analytics.

2. Existing App Events aren't included automatically

Events you already send for Dev Dashboard logs or billing won't show up in Analytics as-is. To include them, you need to align your declarations accordingly.

std

3. Look for a standard event first

Common types (such as email sent) have standard events. It's easiest to work in this order: use a standard event, then extend a standard event, and only then create a custom one.

FROM app_events

4. Metric names become the query vocabulary

Merchants write ShopifyQL using FROM app_events and metric names (e.g., emails_sent). The metrics and attributes you declare become merchants' analytics vocabulary, so name them with that in mind.

5. No need to build your own analytics stack

The article states that you don't need to build or host your own analytics. You may be able to offload building and maintaining in-app reporting screens to Shopify Analytics.Differences from existing dashboards (granularity, retention, etc.) are not stated , so verify before deciding to replace them.

83 practical use cases

USE CASE 1

Show email marketing app results inside Shopify

Problem
Merchants check send volume in the app and sales in Shopify Analytics separately, so they can't compare them side by side.
Solution
Declare and deploy the standard event shopify.marketing.email_sent , then send an event to the App Events API for each email sent.
Impact
Merchants can track emails_sent daily without leaving Shopify. The app stays visible right where merchants analyze performance.
Tech note
This is the article's own official example. Events are sent per installed store.
USE CASE 2

Move your app's in-app report screens into Shopify Analytics

Challenge
The app builds and hosts its own analytics screens to show app-specific metrics, which adds development and maintenance costs.
Approach
Declare app-specific attributes and metrics as custom events (or extensions of standard events) and surface them in Shopify Analytics.
Impact
You avoid building new analytics UI, and merchants can slice the data however they like with the report builder or ShopifyQL.
Tech note
Before fully replacing existing screens, check how well attributes and metrics can be represented and how quickly data shows up (not stated in the article).
Existing events Declare Match
USE CASE 3

Audit existing App Events integrations and open them up to Analytics

Challenge
You already send App Events for Dev Dashboard logs or billing, but that data isn't used in merchant analytics.
Approach
Audit the events you send → pick the ones valuable to merchants → create matching Analytics App Events declarations and deploy.
Impact
Add merchant-facing reports while reusing your existing event pipeline.
Tech note
Existing integrations need no changes. You only align declarations for the events you want in Analytics, so you can migrate incrementally.

9One-line summary for proposals

"Get your app's activity datainto Shopify Analytics reports with just a declaration (TOML) + sending (App Events API) — a new feature.
Merchants can analyze without leaving Shopify, and developers don't need to build their own analytics stack."