Connect a marketing app to Shopify
You can use the GraphQL Admin API to create and manage marketing efforts in your app or on a platform outside of Shopify. By integrating with Shopify, apps can connect their data, and merchants can access a complete picture of how their marketing efforts are performing.
This guide shows you how to connect a marketing app to the Shopify platform using the GraphQL Admin API.
RequirementsAnchor link to section titled "Requirements"
- 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, or you've migrated your existing app so that it's compatible with Shopify CLI 3.0 or higher.
- Your app can make authenticated requests to the GraphQL Admin API.
- Your app has the
write_marketing_eventsaccess scope. For more information on requesting access scopes when your app is installed, refer to Getting started with OAuth.
- You're using API version 2022-10 or higher.
Step 1: Create a marketing activityAnchor link to section titled "Step 1: Create a marketing activity"
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:
Step 2: Update a marketing activityAnchor link to section titled "Step 2: Update a marketing activity"
You can use the
marketingActivityUpdateExternal mutation to keep metadata about marketing activities up to date in Shopify.
The marketing activity
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.
Step 3: Send engagement dataAnchor link to section titled "Step 3: Send engagement data"
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
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.
Engagement dataAnchor link to section titled "Engagement data"
For each marketing activity, the value of the cumulative field (
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
- If the value is
false, then each engagement is the total metrics for only that
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: