Skip to main content

Send events from Checkout UI extensions

Send custom events to Shopify from Checkout UI extensions.

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

Anchor to Send an eventSend an event

Checkout 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-summary-offer".

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 offer_viewed 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}: Checkout accepted the event. This doesn't confirm that Shopify received it.
  • {success: false, error}: Checkout 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 buyer's email address, phone number, or postal code.
    • Events are turned off, such as in the checkout 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 an offer view

// Send an event when the buyer sees an offer.
// Shopify adds the app and shop,
// so the event needs only a handle and attributes.
shopify.appEvents.emit("offer_viewed", {
offer_id: "summer_bundle",
placement: "order_summary",
});

Anchor to Buyer consentBuyer consent

Checkout sends events only when analytics processing is allowed for the buyer. This depends on the shop's customer privacy settings and on the buyer's consent choice.

  • If the buyer 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 buyer declines analytics processing, then held events and new events aren't sent.
  • If the buyer leaves the page, then held events are discarded.

Events aren't sent from the checkout editor, or from checkouts in the Shop app. The Shop app doesn't pass on the merchant's consent, so events there are held until the buyer leaves the page, and emit() still returns {success: true}. To test events, use a web checkout.

Anchor to Rate limitsRate limits

Each Checkout 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("offer_viewed", {
offer_id: "summer_bundle",
});

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

Anchor to Dropped eventsDropped events

Checkout 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, for example when it's held for buyer consent and the buyer 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?