App Events in Analytics

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. 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:

For the syntax and available fields, refer to the ShopifyQL reference.

Anchor to How analytics eligibility worksHow 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.

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.

Anchor to RequirementsRequirements

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 includes an event that matches the activity that your app reports.
• You can deploy an analytics_app_events configuration in shopify.extension.toml.

Anchor to Step 1: Choose a standard eventStep 1: Choose a standard event

Choose an event from the 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.

Anchor to Step 2: Declare the standard eventStep 2: Declare the standard event

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

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.

Anchor to Step 3: Deploy the configurationStep 3: Deploy the configuration

Deploy your app configuration with the Shopify CLI app deploy command:

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.

Anchor to Step 4: Send the matching eventStep 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. The following example shows the request body for an analytics event:

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.

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.

Anchor to Step 5: Query the eventStep 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:

The event also appears in the Dev Dashboard, 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.

Anchor to TroubleshootingTroubleshooting

Anchor to An event appears in the Dev Dashboard but not in Shopify AnalyticsAn 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.

Anchor to A ShopifyQL field isn't availableA ShopifyQL 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.

Anchor to Limits and data requirementsLimits 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.

Anchor to Next stepsNext steps

• Review the standard event registry.
• Learn how to configure Analytics App Events.
• Review the App Events API reference.
• Review the ShopifyQL reference.
• Explore other ways to build on Shopify Analytics.