Connect a marketing app to Shopify

• You've created a Partner account and a development store.
• You understand how apps fit into Shopify and the different ways of distributing your app.
• You've created an app that uses Shopify CLI 3.0 or higher.
• Your app can make authenticated requests to the GraphQL Admin API.
• Your app has the write_marketing_events access scope. Learn how to configure your access scopes using Shopify CLI.
• You're using API version 2022-10 or higher.

When you create a marketing activity, Shopify measures how marketing efforts are performing in the following ways:

• Collecting engagement metrics from apps: Engagement metrics include impressions, likes, shares, and clicks. The engagement metrics are sent in aggregate to Shopify using APIs.

• Analyzing storefront traffic: Shopify provides metrics such as sessions, visitors, add to cart events, orders, and sales, and is able to attribute these metrics to marketing campaigns through the use of UTM parameters.

You can use the marketingActivityCreateExternal mutation to create a marketing activity so that Shopify can track engagements. The following example shows how to send a marketing activity created in your platform to Shopify:

You can use the marketingActivityUpdateExternal mutation to keep metadata about marketing activities up to date in Shopify.

The marketing activity id, remoteId, and UTM parameters can all be used to select the activity to update, as they're considered static and unique values. If the UTM parameters of a marketing activity have changed, then you need to create a new marketing activity.

After you've created marketing events, you can use the marketingEngagementCreate mutation to create a periodic job that sends incremental engagement data about active marketing activities. Engagement data can be sent using any of the previously provided unique identifiers, including the marketingActivityId or remoteId fields, or UTM parameters.

Engagements are currently tracked on a daily resolution. You need to supply the date the engagements occurred, and the daily totals for each value. These can be sent incrementally multiple times per day. The most recent value overwrites previously sent values.

For each marketing activity, the value of the cumulative field (true or false) should remain the same across all of its engagement data. The cumulative boolean indicates whether each engagement sent is a lifetime value of all metrics or just a daily total for that day.

• If the value is true, then each engagement is a lifetime value for all metrics up to that occurredOn date.
• If the value is false, then each engagement is the total metrics for only that occurredOn date.

For a full list of metrics that you can send in an engagement, refer to the MarketingEngagementInput input object in the GraphQL Admin API.

The following example shows how to use the marketingEngagementCreate mutation to send engagement data for a marketing activity:

Consult the GraphQL Admin API reference to learn more about the mutations mentioned in this guide:

• marketingActivityCreateExternal
• marketingActivityUpdateExternal
• marketingEngagementCreate