Skip to main content

Send events from Customer Account UI extensions

Send custom events to Shopify from Customer Account UI extensions.

Use shopify.appEvents.emit() to track how customers use your extension, without a request to your app's backend.

Anchor to Send an eventSend an event

Customer Account 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.

Events don't identify the extension that sent them. If your app has more than one extension that sends the same event, then add an attribute that tells them apart, such as extension: "order-status-reorder".

All events 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•stringRequired

The name of the event. Use a descriptive name, such as reorder_clicked or loyalty_points_redeemed. 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 only contain alphanumeric ASCII characters, underscores, periods, hyphens, and forward slashes.

attributes•objectOptional

A 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 only contain 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}: Customer accounts accepted the event. This doesn't confirm that Shopify received it.
  • {success: false, error}: Customer accounts didn't send the event. error describes why. For example:
    • The eventHandle or attributes don't meet the restrictions above.
    • The extension exceeded the rate limit.
    • The extension can access protected customer data, and an attribute value matches the customer's email address.
    • Events are turned off, such as in the checkout and customer accounts editor.

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 reorder

// Send an event when the customer reorders.
// Shopify adds the app and shop,
// so the event needs only a handle and attributes.
shopify.appEvents.emit("reorder_clicked", {
item_count: 2,
placement: "order_status",
});

Anchor to Customer consentCustomer consent

Customer accounts send events only when analytics processing is allowed for the customer. This depends on the shop's customer privacy settings and on the customer's consent choice.

  • If the customer hasn't allowed analytics processing yet, then events are held on the page and sent after it's allowed. If too many events are held, then the oldest are dropped.
  • If the customer declines analytics processing, then held events and new events aren't sent.
  • If the customer leaves the page, then held events are discarded.

Events aren't sent from the checkout and customer accounts editor.

Anchor to Rate limitsRate limits

Each Customer Account 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

const result = await shopify.appEvents.emit("reorder_clicked", {
item_count: 2,
});

if (!result.success) {
// For example, "Exceeded emission rate limit."
console.warn(result.error);
}

Anchor to Dropped eventsDropped events

Customer accounts check each event when the extension calls emit(), and return {success: false} if the event fails these checks. An accepted event can still go unsent, for example when it's held for customer consent and the customer leaves the page.

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 eventHandle or attributes don't meet the restrictions in Send an event.
  • The eventHandle starts with shopify. 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.

Caution

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.

Was this page helpful?