Choose a version:

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 buyer interacts with your extension, such as accepting an offer or choosing a delivery option.
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 checkout without sending a request from the extension to your app's backend.

Support

Targets (33)

Supported targets

Anchor to Properties and methodsProperties and methods

The shopify global object provides the app events interface for the current checkout. Call shopify.appEvents.emit() with an event handle and optional attributes. The promise resolves with {success: true} when checkout 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.

AppEvents

Reports events to Shopify for this app.

emit

Reports one occurrence of an app-defined event.

(eventHandle: string, attributes?: AppEventAttributes) => Promise<AppEventEmitResult>

AppEventAttributes

Attributes related to an app event.

AppEventAttributeValue

A value attached to an app event.

string | number | boolean

AppEventEmitResult

The outcome of an `emit` call. `success: true` means the host accepted the event. It does not confirm delivery. `success: false` means the event was not sent. `error` describes why.

{readonly success: true} | {readonly success: false; readonly error: string}

Examples

jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default function extension() {

render(<Extension />, document.body);

}

function Extension() {

async function handleClick() {

const result = await shopify.appEvents.emit(

'bundle_added',

{

bundle_id: 'summer_bundle',

placement: 'order_summary',

},

);

if (!result.success) {

console.warn(result.error);

}

return (

<s-button onClick={handleClick}>

Add the summer bundle

</s-button>

);

}

Examples

Send a custom event

Description

Send a custom event when the buyer adds a bundle. This example checks the result and logs the reason when checkout doesn't send the event.

jsx

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

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

function Extension() {
  async function handleClick() {
    const result = await shopify.appEvents.emit(
      'bundle_added',
      {
        bundle_id: 'summer_bundle',
        placement: 'order_summary',
      },
    );

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

  return (
    <s-button onClick={handleClick}>
      Add the summer bundle
    </s-button>
  );
}

Send a declared standard event

Description

Send a standard event for Shopify Analytics. This example sends `shopify.checkout.offer_shown` with its required attributes when the offer renders. Your app must declare the event first.

jsx

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

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

function Extension() {
  useEffect(() => {
    // Declare shopify.checkout.offer_shown in your app's
    // Analytics App Events configuration first. Use the
    // full handle and include every required attribute.
    shopify.appEvents.emit('shopify.checkout.offer_shown', {
      offer_id: 1234,
      offer_type: 'upsell',
      placement: 'order_summary',
    });
  }, []);

  return (
    <s-banner heading="Add a gift box for $5" />
  );
}

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

Checkout sends events only when the buyer has allowed analytics processing. Events wait on the page until consent is given, and are discarded if the buyer declines or leaves the page.
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 editor or from checkouts in the Shop app.

Was this page helpful?