---
title: App Events in Analytics
description: >-
  Declare and send standard app events to make app-reported activity available
  in Shopify Analytics.
source_url:
  html: 'https://shopify.dev/docs/apps/build/app-events/analytics'
  md: 'https://shopify.dev/docs/apps/build/app-events/analytics.md'
---

# App Events in Analytics

**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 in Analytics lets merchants query supported app-reported activity in Shopify Analytics. Your app declares a standard event in its configuration and sends the matching event through the [App Events API](https://shopify.dev/docs/api/app-events). Merchants can then use ShopifyQL to report on the activity through `FROM app_events`.

For example, a merchant can query the number of marketing emails that installed apps reported as sent:

## ShopifyQL

```shopifyql
FROM app_events
  SHOW emails_sent
  GROUP BY app_name
  TIMESERIES day
```

For the syntax and available fields, refer to the [ShopifyQL reference](https://shopify.dev/docs/api/shopifyql/latest).

***

## How analytics eligibility works

An event can appear in the Dev Dashboard without being available in Shopify Analytics. To be eligible for analytics, the event must match an accepted Analytics App Events declaration.

A standard event has a single handle that you use in both places. Use the full standard registry handle, including the `shopify.` prefix, in your `shopify.extension.toml` declaration and as the App Events API `event_handle`.

| Where the handle is used | Handle |
| - | - |
| `shopify.extension.toml` declaration (`name`) | `shopify.marketing.email_sent` |
| App Events API `event_handle` | `shopify.marketing.email_sent` |

The `shopify.` prefix identifies the Shopify-owned standard event. Custom and billing events can't use this reserved prefix, but standard analytics events use the full prefixed handle in both the declaration and the API request.

***

## Requirements

Before you begin, make sure that:

* Your app has access to App Events in Analytics.
* Your app can send events through the App Events API.
* The [standard event registry](https://shopify.dev/docs/apps/build/app-events/analytics/standard-event-registry) includes an event that matches the activity that your app reports.
* You can deploy an [`analytics_app_events` configuration](https://shopify.dev/docs/apps/build/app-events/analytics/toml-configuration) in `shopify.extension.toml`.

***

## Step 1: Choose a standard event

Choose an event from the [standard event registry](https://shopify.dev/docs/apps/build/app-events/analytics/standard-event-registry) that accurately describes the activity that your app reports.

For example, if your app sends marketing emails on behalf of merchants, then use `shopify.marketing.email_sent`.

Standard events use the same definitions across apps. Only choose a standard event when your app's activity matches the event definition and attribute requirements.

***

## Step 2: Declare the standard event

Add an Analytics App Events extension to `shopify.extension.toml`, and declare the standard registry handle:

```toml
[[extensions]]
type = "analytics_app_events"
name = "App Events"


namespace = "example-app"


[[extensions.events]]
name = "shopify.marketing.email_sent"
kind = "standard"
```

Shopify supplies the label, dimensions, and metrics for standard events. Don't redefine these fields in your app configuration.

For more information about the fields and validation rules, refer to [Configure Analytics App Events](https://shopify.dev/docs/apps/build/app-events/analytics/toml-configuration).

***

## Step 3: Deploy the configuration

Deploy your app configuration with the Shopify CLI [`app deploy`](https://shopify.dev/docs/api/shopify-cli/app/app-deploy) command:

```terminal
shopify app deploy
```

Shopify validates the declaration during deployment. If validation fails, then update the configuration based on the returned error and deploy it again.

Common validation errors include:

* The standard registry handle isn't recognized.
* The namespace is missing or empty.
* The namespace doesn't start with a lowercase letter.
* The namespace contains characters other than lowercase letters, numbers, and hyphens, such as uppercase letters, underscores, dots, or spaces.
* The namespace is longer than 64 characters.
* The configuration changes the namespace of a released Analytics App Events configuration.
* The configuration contains fields that aren't supported.
* The configuration removes or changes a previously released event.

***

## Step 4: Send the matching event

After Shopify accepts the declaration, send the event with the same handle that you declared. For the declaration `shopify.marketing.email_sent`, set the App Events API `event_handle` to `shopify.marketing.email_sent`.

For authentication, request headers, and the complete request flow, refer to [Using App Events](https://shopify.dev/docs/apps/build/app-events/send-events). The following example shows the request body for an analytics event:

```json
{
  "shop_id": "gid://shopify/Shop/23423423",
  "event_handle": "shopify.marketing.email_sent",
  "timestamp": "2026-01-27T14:30:00Z",
  "idempotency_key": "email_sent_23423423_55667788",
  "attributes": {
    "campaign_id": 100472895,
    "message_type": "campaign"
  }
}
```

Include every required attribute from the registry. Attribute names, value types, and limits must match both the standard event definition and the App Events API requirements.

**Caution:**

Don't include any data that, alone or in combination with other data, could identify an individual. This includes any merchant or buyer information, such as name, email address, phone number, and other identifiable data points. Use anonymized identifiers and aggregated metrics instead.

A `202 Accepted` response confirms that Shopify received the request. Analytics processing occurs asynchronously, so the response doesn't confirm that the event is available in Shopify Analytics.

***

## Step 5: Query the event

After Shopify accepts events for analytics, merchants can query them through `FROM app_events`.

For example, the following query returns daily email counts by app:

## ShopifyQL

```shopifyql
FROM app_events
  SHOW emails_sent
  GROUP BY app_name
  TIMESERIES day
```

The event also appears in the [Dev Dashboard](https://shopify.dev/docs/apps/build/dev-dashboard/monitoring-and-logs), where you can confirm delivery and troubleshoot your app's event requests.

For the complete list of queryable fields and metrics, refer to the [ShopifyQL reference](https://shopify.dev/docs/api/shopifyql/latest).

***

## Troubleshooting

### An event appears in the Dev Dashboard but not in Shopify Analytics

Confirm that:

* Your app and the shop have access to App Events in Analytics.
* Your app has deployed an accepted `analytics_app_events` configuration.
* The declaration uses the registry handle, such as `shopify.marketing.email_sent`.
* The API request uses the same handle as the declaration, such as `shopify.marketing.email_sent`.
* The request includes the required attributes with the expected value types.

### A Shopify​QL field isn't available

Confirm that:

* The merchant has your app installed.
* Your app declared the standard event.
* The merchant is querying `FROM app_events`.
* The field is supported for the declared standard event.

***

## Limits and data requirements

App Events in Analytics follows the App Events API requirements:

* Each request contains one event. Batch requests aren't supported.
* `shop_id`, `event_handle`, `timestamp`, `idempotency_key`, and `attributes` are required.
* `attributes` can contain up to 15 keys.
* Attribute values must be strings, numbers, or booleans. Arrays and nested objects aren't supported.
* Events must not include personal data or data that can identify a natural person.

Standard events must be declared before they can be available in Shopify Analytics.

***

## Next steps

* Review the [standard event registry](https://shopify.dev/docs/apps/build/app-events/analytics/standard-event-registry).
* Learn how to [configure Analytics App Events](https://shopify.dev/docs/apps/build/app-events/analytics/toml-configuration).
* Review the [App Events API reference](https://shopify.dev/docs/api/app-events).
* Review the [ShopifyQL reference](https://shopify.dev/docs/api/shopifyql/latest).
* Explore other ways to [build on Shopify Analytics](https://shopify.dev/docs/apps/build/analytics).

***