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 app users 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.
Requirements
Anchor link to section titled "Requirements"- You've created a Partner account and a development store.
- You understand 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.
Step 1: Create a marketing activity
Anchor 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 activity
Anchor 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 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.
Step 3: Send engagement data
Anchor 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 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.
Engagement data
Anchor link to section titled "Engagement data"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 thatoccurredOn
date. - If the value is
false
, then each engagement is the total metrics for only thatoccurredOn
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: