Skip to content

Shopify Dude Release Breakdown

Shopify App Events Missing From Analytics? Declare Them Before Sending the API Payload

Shopify’s new App Events in Analytics requires a released analytics_app_events declaration and matching API events. Here’s the TOML, payload, ShopifyQL query, and debugging sequence.

Quick answer: An App Events API request being accepted does not automatically make that event reportable in Shopify Analytics. To appear in reports, the app must have a released analytics_app_events declaration, send an event with the exact declared handle and valid attributes, and pass Shopify’s asynchronous analytics validation. Merchants can then query the data with FROM app_events in ShopifyQL.
On this page

Why an event can exist in one place but not another

Shopify’s Fall ’26 Edition adds a useful reporting bridge: apps can expose operational activity to the merchant’s own Shopify Analytics. An email app can report messages sent; an inventory app can report completed sync jobs; a loyalty app can report redemptions.

But this is not a universal export of every app log or webhook. Shopify’s October 28, 2026 release explicitly distinguishes existing App Events activity from Analytics App Events. Events already used for Dev Dashboard logs or billing do not become merchant-reportable just because they were sent. They need a matching, released analytics declaration.

Declare the event in the app extension

For a Shopify-defined standard event, use the exact handle from Shopify’s registry. This example declares the standard email-sent event in shopify.extension.toml:

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

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

Deploy the app configuration:

shopify app deploy

By default, deployment creates and releases an app version. If you deploy with --no-release, you must release that version before its analytics declaration becomes active. Shopify validates the declaration at deployment, including event names, metrics, and field compatibility.

Use a custom event only when the standard registry does not describe the activity. Custom event handles must begin with your app handle, such as example-app.workflow_completed, not with Shopify’s reserved shopify. prefix. Custom dimensions and metrics must be declared before they can be queried.

Send exactly the event you declared

For the standard email-sent event, an API payload follows this shape. Replace the example IDs, timestamp, and attributes with valid data from your app and the standard event registry:

{
  "shop_id": "gid://shopify/Shop/23423423",
  "event_handle": "shopify.marketing.email_sent",
  "timestamp": "2026-10-28T18:00:00Z",
  "idempotency_key": "email_message_55667788_sent",
  "attributes": {
    "campaign_id": 100472895,
    "message_type": "campaign"
  }
}

For server-side App Events requests, shop_id, event_handle, timestamp, idempotency_key, and attributes are required. Shopify accepts one event per request, not a batch. The attributes object can have up to 15 keys and only scalar string, numeric, or boolean values. Do not send names, emails, phone numbers, customer IDs, or other identifying data.

A 202 Accepted response means Shopify received the event. It does not prove the event passed analytics validation or has appeared in a report yet. That second stage is asynchronous.

Query the event from Shopify Analytics

After processing, merchants can open the Analytics report builder or use ShopifyQL. For a standard email event:

FROM app_events
SHOW emails_sent
GROUP BY app_name
TIMESERIES day
SINCE -7d
UNTIL today

The app name is provided by Shopify; it does not need to be in the event payload. Custom event metrics use a namespaced field name such as event."example-app".workflow_completed.workflows_completed. The exact spelling matters, including quotes around app handles containing hyphens.

Use the report to answer a merchant question, not merely to prove the API works. For example, compare daily campaign messages sent with the operational activity the merchant already reviews. Shopify’s app-events dataset is separate: you cannot join app_events to another dataset in a single ShopifyQL query.

Retention affects report design

App Events dimensions remain available for filtering and grouping for 30 days. Count and sum metrics remain in hourly summaries for up to 365 days without those dimension breakdowns. A report that groups by a custom workflow type may work for the last week and fail for older periods. Design the report around those limits instead of assuming indefinite row-level event history.

App Events are not Next Gen Events or webhooks

These names sound similar but solve different problems. Next Gen Events and webhooks notify an app about changes in Shopify resources. Analytics App Events let an app report its own activity back to Shopify for merchant reporting. If your objective is an inventory price-sync trigger, read the Next Gen Events guide for price-only syncs. If your objective is showing how many syncs your app completed, Analytics App Events are the relevant surface.

Common misunderstanding: “My App Events API request returned 202, so the event must be in Shopify Analytics.” Receipt and analytics availability are separate. A released declaration, matching handle and attributes, privacy compliance, and asynchronous validation all matter.

How to test this

  1. Confirm the app is installed on the test store and authenticated for the App Events API.
  2. Add one standard event declaration to shopify.extension.toml and deploy a released app version.
  3. Send one valid event with a unique idempotency key and all required attributes.
  4. Confirm the API returns 202 Accepted, then wait for analytics processing before querying.
  5. Run FROM app_events with the appropriate metric and a recent date range. Verify the event is counted once.
  6. Check a deliberately mismatched event handle in a test environment and confirm your monitoring surfaces the validation problem.
  7. Test a custom event’s metric and dimension names, including quoted app-handle segments in ShopifyQL.
  8. Check a date range beyond 30 days and confirm your report does not depend on expired dimension breakdowns.
  9. Audit event attributes for personal information and verify that retries use stable idempotency keys.