Show Merchants How Your App Drives Sales With Shopify’s New Marketing Events API

Show Merchants How Your App Drives Sales With Shopify’s New Marketing Events API

Shopify Marketing Events APIMarketing apps are wildly popular among merchants and app developers. These apps make up the most popular category on the Shopify App Store and are the most popular type of app for merchants to install.

Since merchants know they’ll need a variety of tactics to drive traffic to their store, your marketing app is likely not the only one merchants are using.

Since merchants know they’ll need a variety of tactics to drive traffic to their store, your marketing app is likely not the only one merchants are using. And since they’re often trying different campaigns and promotions at the same time, it can be difficult to distinguish which app drove what sale. If merchants have no clear way of identifying your app’s contribution, you’re putting your app at risk of being uninstalled, even if it is responsible for driving the most sales.

Want to watch more videos from Shopify Partners?

Subscribe to our YouTube for more Shopify development tutorials.

In a recent Partner Session webinar, Daniel Patricio — Product Manager on Shopify’s Merchant Marketing Team — outlined the importance of attributing sales to your app’s marketing efforts, and provided steps on how to address this by creating tracking with the Marketing Events API.

We know that merchants who track their marketing are 10 times more likely to be successful. By connecting your app to this API, both your app business and the merchant’s business are more likely to succeed.

Based on the knowledge Daniel shared in his webinar, we’ve put together some key insights into what you should know about, and how to optimize your use of, the Marketing Events API.

You might also like: How to Make the Most of Shopify's New Price Rules API.

Attribution, marketing events, and presenting data from a strategic standpoints

As Daniel Patricio shared at Unite, the average order occurs after four visits. Below is a sample of the journey your merchant’s customers might take:

Shopify Marketing Events API: Merchant order journey
An example of how on average, product orders happen after four visits to a merchant’ website.

In this common scenario, multiple site visits are driven by a marketing event (e.g. opening an email, being served a retargeting ad). Tracking these actions helps showcase that your app’s marketing event did indeed help drive traffic to an online store. Even if it didn’t provide the final click to the site, it’s important to demonstrate that it played an important role in encouraging customers towards that final sale.

To help map this customer journey, the Marketing Events API tracks marketing events that occur outside of the storefront experience, such as:

  • Email
  • Social media posts
  • Retargeting
  • Affiliate links

It doesn’t matter if your marketing event is based around a product, collection, or discount code; as long as your app makes an action on behalf of a merchant, targets multiple current or potential customers, and helps encourage visits to the merchant’s store, it can make use of marketing event tracking within the API.

Once connected, merchants will see reports such as the one below within the Shopify Admin.

Shopify Marketing Events API: Popular marketing campaign report
The Marketing Events API let’s merchants view reports that display valuable stats on which apps made the biggest impact that week.

Focus on campaigns and not individual actions

This API works best with one-to-many marketing actions. We know that a merchant’s time is best spent analyzing different strategies, instead of individual events. While there may be satisfaction in knowing that sending a coupon code influenced a single upsell, knowing that sending a coupon code three days after the first purchase generally increases conversion rates, helps provide the merchant with a continuous strategy and use-case for using your app.

Now that you have more context around how we think of marketing events and attribution, we’ll take you into the code to show you how to get tracking — and proper credit for your app’s work — set-up.  

You might also like: What is Affiliate Marketing? The Myth vs. Reality.

Creating tracking for campaigns 

To get your app connected to the Marketing events API and fully set up with tracking, there are four steps you’ll need to go through. In the example below, we’ll show you how to do this for an email marketing app, however, the same steps apply for all marketing apps.

Step 1 - Create ability to write marketing events

Now that you’re ready to enable the API, the first step is simple but crucial. Go into your scopes, and give yourself the ability to write marketing events.  

Input: write_marketing_events

Step 2 - Defining the marketing event

When you create your marketing events, you’ll need to define the variable that you’ll want to track. The two most important ones are event_type and marketing_channel.

Some examples of event_type are:

  • Newsletter
  • Ad
  • Post
  • Message
  • Sem
  • Transaction
  • Affiliate
  • Loyalty

Some examples of marketing_channel are:

  • Search
  • Display
  • Social
  • Email
  • Referral

Another line item you can add is a human-readable description. This will be rendered within the report, and can help clarify for the merchant what campaign is being tracked.  

Put all together, your code may look like this for a newsletter campaign:

"event_type": "newsletter",
"marketing_channel": “email",
"description": “Spring fling newsletter"

For apps that use referral links, another important line of code is referring_domain. The coding for that would look like this:

"event_type": "affiliate",
"marketing_channel": "referral",
"referring_domain": "",
"description": "Spring Listicle"

Another consideration is that for social media ads, you may want to specify tracking for which social network is referring traffic to the merchant’s store, as well as if it’s a paid campaign or not. For this you’ll want to also specify paid.

"event_type": "ad",
"marketing_channel": "social",
"paid": true,
"referring_domain": "",
"description": "Facebook carousel ad"

Note that while these are the events and channels currently recognized by the API, if you have any use-cases outside of this, we encourage you to post a feature request in the forums.

Step 3 - Defining URL parameters

After the marketing event type is defined, you’ll need to set-up your URL parameters to add a UTM (a tracking monitor recognized by Google Analytics) to the URLs associated with the marketing event. The three parameters we recommend are:




Here’s an example of what these parameters may look like defined for a summer sale:

"utm_campaign": "Summer2017" +,
 "utm_source": "email",
 "utm_medium": "newsletter"

Translated into URL, it would appear like this: 

An app that does a good job of allowing merchants to choose exactly what they’d like to track, is MailChimp. After the merchant creates a campaign, and before they deploy to customers, they’re taken to a screen where they can specify what type of tracking they’re interested in. This helps ensure that merchants are getting the information they want, and have an understanding of the data that will be served to them.

Shopify Marketing Events API: MailChimp
MailChimp does a good job of helping merchant’s understand what kinds of tracking they can access with email campaigns.

Step 4 - Define resources

To further enrich the reporting, and better showcase what specific types of products your app is especially good at driving conversions for, you can add in meta data under marketed_resources.

Several different types of resources can be imputed here, such as products, discounts, or pages. Using products as an example, the code may look like this:

"marketed_resources": [
		    type: 'product',
		    id: '12345'

The merchant view

With MailChimp for example, after you’ve enabled the above four steps, and the merchant has deployed the newsletter, they will receive the conversion report pictured below.

Shopify Marketing Events API: Conversion report

In this report, merchants can see where the site visitor was referred from (e.g. email, website, social channel), what page they visited, what type of device they used (mobile, desktop), and the date they visited the store.  

You might also like: How to Improve Your App’s Design and Gain More Users.

Bonus! Increase your chance of being a recommended app by using the Engagement API

To help merchants in marketing their businesses, the Shopify team often provides app recommendations. When the team is trying to determine which apps to recommend, they often look towards the additional layer of information that’s provided through the Engagement API.  

Although this data is currently not displayed to merchants in the admin, it’s important to helping both you and the people who recommend apps, better understand your app’s strength.

The Engagement API is embedded within the Marketing Events API. This interface is well suited for top of funnel metrics, and can provide more in-depth interaction data for social network ads, such as:

  • Impressions
  • Clicks
  • Shares
  • Favourites/likes
  • Comments

As you can imagine, this API helps track some of the higher funnel metrics collected from apps that commonly run campaigns on social channels, such as Shoelace and Kit.

An example of how the code may be set-up:

Final considerations for using the Marketing Events API

As you’ve seen, tapping into this API is relatively straightforward and can have a major impact on how merchants use your app.

After setting up the scope, marketing event, URL parameters, and what to track within resources, you can use the same information that you serve merchants to gain insights into what products and verticals your app works best with.  

Once you know which merchants benefit most, you can better invest your own marketing time and dollars into targeting the write types of merchants, and focus on making the updates that will retain them as users. 

Access the Marketing Events API today

What types of campaigns are you excited to create tracking for? Share with us in the comments below.

About the Author

Liz Couto is a Product Marketer on the Shopify App and Partner Platform Team, whose professional background looks like an odd mash-up of Mad Men and Silicon Valley. She can often be found with a cat in her lap, and a coffee in hand.

Grow your business with the Shopify Partner Program

Learn more