The REST Admin API is a legacy API as of October 1, 2024. All apps and integrations should be built with the GraphQL Admin API. For details and migration steps, visit our migration guide.
Multiple access scopes needed — refer to each endpoint for access scope requirements.
Marketing events represent actions taken by your app, on behalf of the merchant, to market products, collections, discounts, pages, blog posts, and other features. These actions target multiple potential customers, rather than specific individuals. For example, you should model your marketing event at the email campaign level, rather than on a per-email basis.
Merchants get value from marketing events because they help them understand sales and traffic attribution. Implementing marketing events for your app is beneficial because it enables Shopify to surface your app in the Shopify admin in ways that are helpful to merchants. Examples of marketing events include an ad campaign that drives multiple potential customers to a product page, or an email marketing campaign advertising a discount code.
Marketing events can be created for email campaigns, affiliate links, advertisements, and other common marketing tactics.
Marketing events include the event_type and marketing_channel
properties that help Shopify to rank your app and surface it in the Shopify admin in ways that are useful to merchants. Traffic and
order attribution for your app is handled by providing UTM parameters with your marketing events.
The same UTM parameters are also used in the links provided in the marketing event.
Engagements can also be added to marketing events to give merchants more insight into how potential customers interact with your marketing events. For example, engagements for ad campaigns can include clicks, shares, and comments. Creating engagements is optional, and not all marketing events include engagements.
ad, post, message, retargeting, transactional, affiliate, loyalty, newsletter, abandoned_cart.
Note
If there are values that you’d like to use for event_type that are not in the list above, then please share your request in the Shopify Community APIs and SDKs discussion board providing as much detail as possible. Our approach is to be more structured than using freeform text, but to still allow for categorization of most types of marketing actions.
search, display, social, email, referral.marketing_channel is set to search or social.budget is specified.budget is specified. Valid values: daily, lifetime.'The UTM parameters used in the links provided in the marketing event. Values must be unique and should not be url-encoded.
To do traffic or order attribution you must at least define utm_campaign, utm_source, and utm_medium.
Requires access scope.
Marketing events can be created to track ad campaigns that target a specific time of year. For example, a marketing event can be created to track a Facebook ad campaign
for Christmas 2022. When creating the marketing event, the body of the request includes the UTM parameters that must be included in the links provided in the marketing event.
Each marketing event also includes the event_type and marketing_channel properties that help Shopify to rank your app and surface it within
Shopify admin.
After a marketing event is created in Shopify, you can start to drive traffic to Shopify. Make sure that the links for the marketing event contain the same UTM parameters that were defined in the marketing event. For example, marketing activities for the Christmas 2022 ad campaign would use the following URL convention:
https://storename.com/product?utm_source=facebook&utm_medium=cpc&utm_campaign=Christmas2022-12142018
Engagements on marketing events represent customer activity taken on the marketing event before customers reach the shop’s website. Not all types of marketing events will necessarily have engagement, and most types of marketing events will only use a subset of the possible engagement types.
Engagements are aggregated on a daily basis. However, the data can be sent more often than once a day if the information is available. If you create an engagement with the same value for occurred_on as an existing engagement, then the new engagement will overwrite the previous one.
Requires access scope.
Requires access scope.
Requires access scope.
Requires access scope.
Requires access scope.