Skip to main content

App Events: Send events from Checkout and Customer Account UI extensions

Starting with API version 2027-01, Checkout and Customer Account UI extensions can send App Events to Shopify with shopify.appEvents.emit(). Extensions don't need network access or an app backend to send events. This is a new, optional API, so no action is required.

What changed

The new shopify.appEvents.emit() method sends a custom event with an event handle and optional attributes. Shopify adds your app and the shop to each event, so you don't need an access token or a shop ID. Events appear in your Dev Dashboard logs, together with the events that your app sends with the App Events API. For parameters, return values, and rate limits, refer to the API reference for Checkout UI extensions and Customer Account UI extensions.

Your extensions can also send the standard events that you declared for Shopify Analytics. Merchants see these events in their analytics.

Checkout and Customer Account send events only after the buyer allows analytics processing. Until then, events are held on the page. If the buyer declines or leaves the page, then the held events aren't sent.

Each extension can send a burst of 20 events, and then 2 events per second. When emit() doesn't send an event, it returns {success: false, error}. For example, this happens when the event is invalid or the extension exceeds the rate limit. Don't include personal information in event attributes.

Events from UI extensions aren't processed for billing. To report usage for Shopify App Pricing, continue to send billing events from your app's backend.

Who's affected

This change applies to Checkout UI extensions and Customer Account UI extensions that use API version 2027-01 or later. Extensions on earlier API versions don't have shopify.appEvents.

The server App Events API doesn't change, and apps without these extensions aren't affected. Checkouts in the Shop app don't send events from extensions.

Why this matters

Before this change, an extension needed network access and an app backend to send app events. Now an extension can send events directly, so you can see how buyers use your extension next to the rest of your app activity.

What to do

No action is required. To send events from an extension, follow these steps:

  1. Set api_version to 2027-01 in your extension's shopify.extension.toml file.
  2. Call shopify.appEvents.emit() where the event happens in your extension.
  3. In a development store, add the extension to checkout or customer account pages.
  4. If necessary, allow analytics processing as a buyer and make a test purchase. Confirm that the event appears in your Dev Dashboard logs. If you sent a declared standard event, then you can also find it in Analytics in your development store's Shopify admin.
shopify.appEvents.emit("offer_viewed", {
  offer_id: "summer_bundle",
  placement: "order_summary",
});

Related docs

Was this page helpful?