Send events from Admin UI extensions
Send custom events to Shopify from Admin UI extensions.
Use shopify.appEvents.emit() to track how merchants use your extension, without a request to your app's backend.
Anchor to Send an eventSend an event
Admin UI extensions that use API version 2027-01 or later can send events with shopify.appEvents.emit(). Shopify adds your app and the shop to each event, so you don't need an access token or a shop ID. Extensions that you preview with shopify app dev can also send events.
Events don't identify the extension that sent them or the staff member who used it. If your app has more than one extension that sends the same event, then add an attribute that tells them apart, such as extension: "product-details-block".
Events that Shopify accepts are visible in the Dev Dashboard logs, together with the events that your app sends with Create an event. Events from UI extensions aren't processed for billing, so to report usage for Shopify App Pricing, send a billing event from your app's backend.
Anchor to ParametersParameters
eventHandle•stringRequiredThe name of the event. Use a descriptive name, such as description_generated or bulk_edit_saved. To send a standard event for Shopify Analytics, use the full standard registry handle that you declared, including the shopify. prefix.
The name has a maximum of 128 characters and can contain only alphanumeric ASCII characters, underscores, periods, hyphens, and forward slashes.
attributes•objectOptionalA JSON object of key/value pairs containing the event data. Don't include any data that, alone or in combination with other data, could identify an individual. The attributes object has the following restrictions:
- Maximum 15 keys in the attributes object
- Keys are limited to 64 characters and can contain only alphanumeric ASCII characters, underscores, periods, and hyphens
- String values are limited to 128 characters (UTF-8)
- Only scalar values are allowed (strings, numbers, booleans). Arrays and nested objects aren't supported.
Anchor to ReturnsReturns
A promise that resolves with an object:
{success: true}: The Shopify admin accepted the event. This doesn't confirm that Shopify received it.{success: false, error}: The Shopify admin didn't send the event.errordescribes why. For example:- The
eventHandleorattributesdon't meet the restrictions above. - The extension exceeded the rate limit.
- Events are turned off for the current session of the Shopify admin.
- The extension target can't send events. On
should-rendertargets and data targets, such asadmin.app.tools.data,emit()always resolves{success: false, error: 'Emit is unavailable.'}.
- The
The promise doesn't reject.
Shopify records the time that it receives each event. Events from UI extensions have no timestamp or idempotency_key, so each call to emit() creates a separate event. Call emit() once for each occurrence.
Tracking a generated description
Anchor to Rate limitsRate limits
Each Admin UI extension can send a burst of up to 20 events, then 2 events per second.
After the limit is exceeded, emit() returns {success: false} and the event isn't sent, until the rate falls below the limit.
Checking the result
Anchor to Dropped eventsDropped events
The Shopify admin checks each event when the extension calls emit(), and returns {success: false} if the event fails these checks. An accepted event can still go unsent.
Shopify validates each event again after it's sent. An event that fails this validation is dropped. Dropped events don't appear in the Dev Dashboard, and the extension isn't notified.
Shopify drops an event in the following cases:
- The
eventHandleorattributesdon't meet the restrictions in Send an event. - The
eventHandlestarts withshopify.but isn't in the standard event registry. - Your app isn't installed on the shop.
- Shopify can't verify the extension's session token.
To check that your events arrive, go to the Dev Dashboard and open Logs.
Don't include any data in attributes that, alone or in combination with other data, could identify an individual. This includes names, email addresses, phone numbers, and customer IDs.
Don't include any data in attributes that, alone or in combination with other data, could identify an individual. This includes names, email addresses, phone numbers, and customer IDs.