Skip to main content

App Events API

The App Events API sends app events from your extension to Shopify. Shopify adds your app and the shop to each event, so your extension doesn't need network access, an access token, or a shop ID. Events appear in the Dev Dashboard with the events that your app backend sends.

Anchor to Use casesUse cases

  • Measure extension engagement: Send a custom event when a customer interacts with your extension, such as reordering or opening a loyalty reward.
  • Report standard events for Shopify Analytics: Send a standard event that your app has declared, so merchants can query it with ShopifyQL.
  • Skip a backend round trip: Report what happened in the customer account without sending a request from the extension to your app's backend.
Support
Targets (24)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides the app events interface for customer account extensions. Call shopify.appEvents.emit() with an event handle and optional attributes. The promise resolves with {success: true} when the host accepts the event, or {success: false, error} when it doesn't send it. The promise doesn't reject.

Anchor to appEvents
appEvents
required

Reports events to Shopify for this app.

Examples

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
render(<Extension />, document.body);
};

function Extension() {
async function handleClick() {
const result = await shopify.appEvents.emit(
'reorder_clicked',
{
item_count: 2,
},
);

if (!result.success) {
console.warn(result.error);
}
}

return (
<s-button onClick={handleClick}>
Reorder
</s-button>
);
}

Anchor to Best practicesBest practices

  • Call emit() once for each occurrence: Events from UI extensions have no timestamp or idempotency_key. Shopify records the time that it receives each event, and each call creates a separate event.
  • Check the result: When success is false, error describes why the event wasn't sent, such as invalid attributes or an exceeded rate limit.
  • Don't send personal data: 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.
  • Use the full handle for standard events: To send a standard event, use the handle that you declared in your app's Analytics App Events configuration, including the shopify. prefix, and include every required attribute.

Anchor to LimitationsLimitations

  • Events are sent only when the customer has allowed analytics processing.
  • Each extension can send a burst of up to 20 events, then 2 events per second. Over the limit, emit() returns {success: false}.
  • Event handles have a maximum of 128 characters. attributes has a maximum of 15 keys, and values must be strings, numbers, or booleans.
  • Events from UI extensions aren't processed for billing. To report usage for Shopify App Pricing, send a billing event from your app backend through the App Events API.
  • Events aren't sent from the checkout and customer accounts editor.
Was this page helpful?