MarketingEvent

Version 2019-04

Marketing events represent actions taken by your app, on behalf of the merchant, to market products, collections, discounts, pages, blog posts, and other features. Marketing events represent actions that 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.

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.

What you can do with MarketingEvent

The Shopify API lets you do the following with the MarketingEvent resource. More detailed versions of these general actions may be available:

MarketingEvent properties

remote_id 
"remote_id": "123abc"

An optional remote identifier for a marketing event. The remote identifier lets Shopify validate engagement data.

event_type
required 
"event_type": "ad"

The type of marketing event. Valid values: 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 post your request here. Our approach is to be more structured than using freeform text, but to still allow for categorization of most types of marketing actions.
marketing_channel
required 
"marketing_channel": "social"

The channel that your marketing event will use. Valid values: search, display, social, email, referral.

referring_domain 
"referring_domain": "facebook.com"

The destination domain of the marketing event. Required if the marketing_channel is set to search or social.

budget 
"budget": 10.75

The budget of the ad campaign.
currency 
"currency": "USD"

The currency for the budget. Required if budget is specified.
budget_type 
"budget_type": "lifetime"

The type of the budget. Required if budget is specified. Valid values: daily, lifetime.'

started_at
required 
"started_at": "2020-01-15T11:56:18-04:00"

The time when the marketing action was started.

scheduled_to_end_at 
"scheduled_to_end_at": "2020-01-22T11:56:18-04:00"

For events with a duration, the time when the event was scheduled to end.
ended_at 
"ended_at": "2020-01-20T11:56:18-04:00"

For events with a duration, the time when the event actually ended.

UTM parameters 
"marketing_event": {
  "utm_campaign": "CanadaDay2020",
  "utm_source": "facebook",
  "utm_medium": "cpc"
}

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.
description 
"description": "Facebook carousel ad #{Time.now.utc.year}"

A description of the marketing event.

manage_url 
"manage_url": "https://mymarketingapp.com/ad/1234"

A link to manage the marketing event. In most cases, this links to the app that created the event.

preview_url 
"preview_url": "https://www.facebook.com/123456/"

A link to the live version of the event, or to a rendered preview in the app that created it.

marketed_resources 
"marketed_resources": [
  {
    "type": "product",
    "id": 12345
  }
]

A list of the items that were marketed in the marketing event. Includes the type and id of each item. Valid values for type are:

  • product
  • collection
  • price_rule
  • discount (Will be replaced by price_rule after April 20, 2017.)
  • page
  • article
  • homepage (Doesn't have an id.)

Endpoints

GET /admin/api/2019-04/marketing_events.json
Retrieves a list of all marketing events.
limit

The amount of results to return.

(default: 50, maximum: 250)
page
deprecated

The page of results to show.

(default: 1)
offset

The number of marketing events to skip.

Retrieve all marketing events

GET /admin/api/2019-07/marketing_events.json
View Response 
HTTP/1.1 200 OK
{
  "marketing_events": [
    {
      "id": 998730532,
      "event_type": "post",
      "remote_id": "12345678",
      "started_at": "2020-01-15T10:56:18-05:00",
      "ended_at": null,
      "scheduled_to_end_at": null,
      "budget": "10.11",
      "currency": "GBP",
      "manage_url": null,
      "preview_url": null,
      "utm_campaign": "1234567890",
      "utm_source": "facebook",
      "utm_medium": "facebook-post",
      "budget_type": "daily",
      "description": null,
      "marketing_channel": "social",
      "paid": false,
      "referring_domain": "facebook.com",
      "breadcrumb_id": null,
      "marketing_activity_id": null,
      "admin_graphql_api_id": "gid://shopify/MarketingEvent/998730532",
      "marketed_resources": []
    }
  ]
}
GET /admin/api/2019-04/marketing_events/count.json
Retrieves a count of all marketing events

Retrieve a count all marketing events

GET /admin/api/2020-04/marketing_events/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 1
}
GET /admin/api/2019-04/marketing_events/{marketing_event_id}.json
Retrieves a single marketing event

Retrieve a single marketing event by its ID

GET /admin/api/2020-04/marketing_events/998730532.json
View Response 
HTTP/1.1 200 OK
{
  "marketing_event": {
    "id": 998730532,
    "event_type": "post",
    "remote_id": "12345678",
    "started_at": "2020-01-15T10:56:18-05:00",
    "ended_at": null,
    "scheduled_to_end_at": null,
    "budget": "10.11",
    "currency": "GBP",
    "manage_url": null,
    "preview_url": null,
    "utm_campaign": "1234567890",
    "utm_source": "facebook",
    "utm_medium": "facebook-post",
    "budget_type": "daily",
    "description": null,
    "marketing_channel": "social",
    "paid": false,
    "referring_domain": "facebook.com",
    "breadcrumb_id": null,
    "marketing_activity_id": null,
    "admin_graphql_api_id": "gid://shopify/MarketingEvent/998730532",
    "marketed_resources": []
  }
}
POST /admin/api/2019-04/marketing_events.json
Creates a marketing event

Create a marketing event

POST /admin/api/2020-04/marketing_events.json
{
  "marketing_event": {
    "started_at": "2020-12-15",
    "utm_campaign": "Christmas2020",
    "utm_source": "facebook",
    "utm_medium": "cpc",
    "event_type": "ad",
    "referring_domain": "facebook.com",
    "marketing_channel": "social",
    "paid": true
  }
}
View Response 
HTTP/1.1 201 Created
{
  "marketing_event": {
    "id": 1056048232,
    "event_type": "ad",
    "remote_id": null,
    "started_at": "2020-12-15T03:00:00-05:00",
    "ended_at": null,
    "scheduled_to_end_at": null,
    "budget": null,
    "currency": null,
    "manage_url": null,
    "preview_url": null,
    "utm_campaign": "Christmas2020",
    "utm_source": "facebook",
    "utm_medium": "cpc",
    "budget_type": null,
    "description": null,
    "marketing_channel": "social",
    "paid": true,
    "referring_domain": "facebook.com",
    "breadcrumb_id": null,
    "marketing_activity_id": 1063897333,
    "admin_graphql_api_id": "gid://shopify/MarketingEvent/1056048232",
    "marketed_resources": []
  }
}
PUT /admin/api/2019-04/marketing_events/{marketing_event_id}.json
Updates a marketing event

Update a marketing event. Can modify only timestamps, remote_id, and budget/currency.

PUT /admin/api/2020-04/marketing_events/998730532.json
{
  "marketing_event": {
    "id": 998730532,
    "remote_id": "1000:2000",
    "started_at": "2020-02-02T00:00 +00:00",
    "ended_at": "2020-02-03T00:00 +00:00",
    "scheduled_to_end_at": "2020-02-04T00:00 +00:00",
    "budget": "11.1",
    "budget_type": "daily",
    "currency": "CAD",
    "utm_campaign": "other",
    "utm_source": "other",
    "utm_medium": "other",
    "event_type": "ad",
    "referring_domain": "instagram.com"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "marketing_event": {
    "id": 998730532,
    "event_type": "post",
    "remote_id": "1000:2000",
    "started_at": "2020-02-01T19:00:00-05:00",
    "ended_at": "2020-02-02T19:00:00-05:00",
    "scheduled_to_end_at": "2020-02-03T19:00:00-05:00",
    "budget": "11.1",
    "currency": "CAD",
    "manage_url": null,
    "preview_url": null,
    "utm_campaign": "1234567890",
    "utm_source": "facebook",
    "utm_medium": "facebook-post",
    "budget_type": "daily",
    "description": null,
    "marketing_channel": "social",
    "paid": false,
    "referring_domain": "facebook.com",
    "breadcrumb_id": null,
    "marketing_activity_id": null,
    "admin_graphql_api_id": "gid://shopify/MarketingEvent/998730532",
    "marketed_resources": []
  }
}
DELETE /admin/api/2019-04/marketing_events/{marketing_event_id}.json
Deletes a marketing event

Delete a marketing event

DELETE /admin/api/2020-04/marketing_events/998730532.json
View Response 
HTTP/1.1 200 OK
{
}
POST /admin/api/2019-04/marketing_events/{marketing_event_id}/engagements.json

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.

occurred_on
required

The date that these engagements occurred on, in the format “YYYY-MM-DD”.
impressions_count

The total number of impressions for the day. An impression occurs when the marketing event is served to a customer, either as a email or through a marketing channel.

views_count

The total number of views for the day. A view occurs when a customer reads the marketing event that was served to them, for example, if the customer opens the email or spends time looking at a Facebook post.

clicks_count

The total number of clicks on the marketing event for the day.
shares_count

The total number of shares for the day.
favorites_count

The total number of favorites for the day.
comments_count

The total number of comments for the day.
ad_spend

The total ad spend for the day, if the marketing event is a paid ad with a daily spend.

is_cumulative

Whether the engagements are reported as lifetime values rather than daily totals.

Add engagements to a marketing engagement

POST /admin/api/2020-04/marketing_events/998730532/engagements.json
{
  "engagements": [
    {
      "occurred_on": "2020-01-15",
      "views_count": 0,
      "clicks_count": 0,
      "favorites_count": 0,
      "ad_spend": 10.0,
      "is_cumulative": true
    },
    {
      "occurred_on": "2020-01-16",
      "views_count": 100,
      "clicks_count": 50,
      "is_cumulative": true
    },
    {
      "occurred_on": "2020-01-17",
      "views_count": 200,
      "clicks_count": 100,
      "is_cumulative": true
    }
  ]
}
View Response 
HTTP/1.1 201 Created
{
  "engagements": [
    {
      "occurred_on": "2020-01-15",
      "fetched_at": null,
      "views_count": 0,
      "impressions_count": null,
      "clicks_count": 0,
      "favorites_count": 0,
      "comments_count": null,
      "shares_count": null,
      "ad_spend": "10.0",
      "currency_code": null,
      "is_cumulative": true,
      "unsubscribes_count": null,
      "complaints_count": null,
      "fails_count": null,
      "sends_count": null,
      "unique_views_count": null,
      "unique_clicks_count": null,
      "utc_offset": null
    },
    {
      "occurred_on": "2020-01-16",
      "fetched_at": null,
      "views_count": 100,
      "impressions_count": null,
      "clicks_count": 50,
      "favorites_count": null,
      "comments_count": null,
      "shares_count": null,
      "ad_spend": null,
      "currency_code": null,
      "is_cumulative": true,
      "unsubscribes_count": null,
      "complaints_count": null,
      "fails_count": null,
      "sends_count": null,
      "unique_views_count": null,
      "unique_clicks_count": null,
      "utc_offset": null
    },
    {
      "occurred_on": "2020-01-17",
      "fetched_at": null,
      "views_count": 200,
      "impressions_count": null,
      "clicks_count": 100,
      "favorites_count": null,
      "comments_count": null,
      "shares_count": null,
      "ad_spend": null,
      "currency_code": null,
      "is_cumulative": true,
      "unsubscribes_count": null,
      "complaints_count": null,
      "fails_count": null,
      "sends_count": null,
      "unique_views_count": null,
      "unique_clicks_count": null,
      "utc_offset": null
    }
  ]
}
Version 2019-07

Marketing events represent actions taken by your app, on behalf of the merchant, to market products, collections, discounts, pages, blog posts, and other features. Marketing events represent actions that 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.

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.

What you can do with MarketingEvent

The Shopify API lets you do the following with the MarketingEvent resource. More detailed versions of these general actions may be available:

MarketingEvent properties

remote_id 
"remote_id": "123abc"

An optional remote identifier for a marketing event. The remote identifier lets Shopify validate engagement data.

event_type
required 
"event_type": "ad"

The type of marketing event. Valid values: 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 post your request here. Our approach is to be more structured than using freeform text, but to still allow for categorization of most types of marketing actions.
marketing_channel
required 
"marketing_channel": "social"

The channel that your marketing event will use. Valid values: search, display, social, email, referral.

referring_domain 
"referring_domain": "facebook.com"

The destination domain of the marketing event. Required if the marketing_channel is set to search or social.

budget 
"budget": 10.75

The budget of the ad campaign.
currency 
"currency": "USD"

The currency for the budget. Required if budget is specified.
budget_type 
"budget_type": "lifetime"

The type of the budget. Required if budget is specified. Valid values: daily, lifetime.'

started_at
required 
"started_at": "2020-01-15T11:56:18-04:00"

The time when the marketing action was started.

scheduled_to_end_at 
"scheduled_to_end_at": "2020-01-22T11:56:18-04:00"

For events with a duration, the time when the event was scheduled to end.
ended_at 
"ended_at": "2020-01-20T11:56:18-04:00"

For events with a duration, the time when the event actually ended.

UTM parameters 
"marketing_event": {
  "utm_campaign": "CanadaDay2020",
  "utm_source": "facebook",
  "utm_medium": "cpc"
}

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.
description 
"description": "Facebook carousel ad #{Time.now.utc.year}"

A description of the marketing event.

manage_url 
"manage_url": "https://mymarketingapp.com/ad/1234"

A link to manage the marketing event. In most cases, this links to the app that created the event.

preview_url 
"preview_url": "https://www.facebook.com/123456/"

A link to the live version of the event, or to a rendered preview in the app that created it.

marketed_resources 
"marketed_resources": [
  {
    "type": "product",
    "id": 12345
  }
]

A list of the items that were marketed in the marketing event. Includes the type and id of each item. Valid values for type are:

  • product
  • collection
  • price_rule
  • discount (Will be replaced by price_rule after April 20, 2017.)
  • page
  • article
  • homepage (Doesn't have an id.)

Endpoints

GET /admin/api/2019-07/marketing_events.json
Retrieves a list of all marketing events.
limit

The amount of results to return.

(default: 50, maximum: 250)
page
deprecated

The page of results to show.

(default: 1)
offset

The number of marketing events to skip.

Retrieve all marketing events

GET /admin/api/2019-07/marketing_events.json
View Response 
HTTP/1.1 200 OK
{
  "marketing_events": [
    {
      "id": 998730532,
      "event_type": "post",
      "remote_id": "12345678",
      "started_at": "2020-01-15T10:56:18-05:00",
      "ended_at": null,
      "scheduled_to_end_at": null,
      "budget": "10.11",
      "currency": "GBP",
      "manage_url": null,
      "preview_url": null,
      "utm_campaign": "1234567890",
      "utm_source": "facebook",
      "utm_medium": "facebook-post",
      "budget_type": "daily",
      "description": null,
      "marketing_channel": "social",
      "paid": false,
      "referring_domain": "facebook.com",
      "breadcrumb_id": null,
      "marketing_activity_id": null,
      "admin_graphql_api_id": "gid://shopify/MarketingEvent/998730532",
      "marketed_resources": []
    }
  ]
}
GET /admin/api/2019-07/marketing_events/count.json
Retrieves a count of all marketing events

Retrieve a count all marketing events

GET /admin/api/2020-04/marketing_events/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 1
}
GET /admin/api/2019-07/marketing_events/{marketing_event_id}.json
Retrieves a single marketing event

Retrieve a single marketing event by its ID

GET /admin/api/2020-04/marketing_events/998730532.json
View Response 
HTTP/1.1 200 OK
{
  "marketing_event": {
    "id": 998730532,
    "event_type": "post",
    "remote_id": "12345678",
    "started_at": "2020-01-15T10:56:18-05:00",
    "ended_at": null,
    "scheduled_to_end_at": null,
    "budget": "10.11",
    "currency": "GBP",
    "manage_url": null,
    "preview_url": null,
    "utm_campaign": "1234567890",
    "utm_source": "facebook",
    "utm_medium": "facebook-post",
    "budget_type": "daily",
    "description": null,
    "marketing_channel": "social",
    "paid": false,
    "referring_domain": "facebook.com",
    "breadcrumb_id": null,
    "marketing_activity_id": null,
    "admin_graphql_api_id": "gid://shopify/MarketingEvent/998730532",
    "marketed_resources": []
  }
}
POST /admin/api/2019-07/marketing_events.json
Creates a marketing event

Create a marketing event

POST /admin/api/2020-04/marketing_events.json
{
  "marketing_event": {
    "started_at": "2020-12-15",
    "utm_campaign": "Christmas2020",
    "utm_source": "facebook",
    "utm_medium": "cpc",
    "event_type": "ad",
    "referring_domain": "facebook.com",
    "marketing_channel": "social",
    "paid": true
  }
}
View Response 
HTTP/1.1 201 Created
{
  "marketing_event": {
    "id": 1056048232,
    "event_type": "ad",
    "remote_id": null,
    "started_at": "2020-12-15T03:00:00-05:00",
    "ended_at": null,
    "scheduled_to_end_at": null,
    "budget": null,
    "currency": null,
    "manage_url": null,
    "preview_url": null,
    "utm_campaign": "Christmas2020",
    "utm_source": "facebook",
    "utm_medium": "cpc",
    "budget_type": null,
    "description": null,
    "marketing_channel": "social",
    "paid": true,
    "referring_domain": "facebook.com",
    "breadcrumb_id": null,
    "marketing_activity_id": 1063897333,
    "admin_graphql_api_id": "gid://shopify/MarketingEvent/1056048232",
    "marketed_resources": []
  }
}
PUT /admin/api/2019-07/marketing_events/{marketing_event_id}.json
Updates a marketing event

Update a marketing event. Can modify only timestamps, remote_id, and budget/currency.

PUT /admin/api/2020-04/marketing_events/998730532.json
{
  "marketing_event": {
    "id": 998730532,
    "remote_id": "1000:2000",
    "started_at": "2020-02-02T00:00 +00:00",
    "ended_at": "2020-02-03T00:00 +00:00",
    "scheduled_to_end_at": "2020-02-04T00:00 +00:00",
    "budget": "11.1",
    "budget_type": "daily",
    "currency": "CAD",
    "utm_campaign": "other",
    "utm_source": "other",
    "utm_medium": "other",
    "event_type": "ad",
    "referring_domain": "instagram.com"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "marketing_event": {
    "id": 998730532,
    "event_type": "post",
    "remote_id": "1000:2000",
    "started_at": "2020-02-01T19:00:00-05:00",
    "ended_at": "2020-02-02T19:00:00-05:00",
    "scheduled_to_end_at": "2020-02-03T19:00:00-05:00",
    "budget": "11.1",
    "currency": "CAD",
    "manage_url": null,
    "preview_url": null,
    "utm_campaign": "1234567890",
    "utm_source": "facebook",
    "utm_medium": "facebook-post",
    "budget_type": "daily",
    "description": null,
    "marketing_channel": "social",
    "paid": false,
    "referring_domain": "facebook.com",
    "breadcrumb_id": null,
    "marketing_activity_id": null,
    "admin_graphql_api_id": "gid://shopify/MarketingEvent/998730532",
    "marketed_resources": []
  }
}
DELETE /admin/api/2019-07/marketing_events/{marketing_event_id}.json
Deletes a marketing event

Delete a marketing event

DELETE /admin/api/2020-04/marketing_events/998730532.json
View Response 
HTTP/1.1 200 OK
{
}
POST /admin/api/2019-07/marketing_events/{marketing_event_id}/engagements.json

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.

occurred_on
required

The date that these engagements occurred on, in the format “YYYY-MM-DD”.
impressions_count

The total number of impressions for the day. An impression occurs when the marketing event is served to a customer, either as a email or through a marketing channel.

views_count

The total number of views for the day. A view occurs when a customer reads the marketing event that was served to them, for example, if the customer opens the email or spends time looking at a Facebook post.

clicks_count

The total number of clicks on the marketing event for the day.
shares_count

The total number of shares for the day.
favorites_count

The total number of favorites for the day.
comments_count

The total number of comments for the day.
ad_spend

The total ad spend for the day, if the marketing event is a paid ad with a daily spend.

is_cumulative

Whether the engagements are reported as lifetime values rather than daily totals.

Add engagements to a marketing engagement

POST /admin/api/2020-04/marketing_events/998730532/engagements.json
{
  "engagements": [
    {
      "occurred_on": "2020-01-15",
      "views_count": 0,
      "clicks_count": 0,
      "favorites_count": 0,
      "ad_spend": 10.0,
      "is_cumulative": true
    },
    {
      "occurred_on": "2020-01-16",
      "views_count": 100,
      "clicks_count": 50,
      "is_cumulative": true
    },
    {
      "occurred_on": "2020-01-17",
      "views_count": 200,
      "clicks_count": 100,
      "is_cumulative": true
    }
  ]
}
View Response 
HTTP/1.1 201 Created
{
  "engagements": [
    {
      "occurred_on": "2020-01-15",
      "fetched_at": null,
      "views_count": 0,
      "impressions_count": null,
      "clicks_count": 0,
      "favorites_count": 0,
      "comments_count": null,
      "shares_count": null,
      "ad_spend": "10.0",
      "currency_code": null,
      "is_cumulative": true,
      "unsubscribes_count": null,
      "complaints_count": null,
      "fails_count": null,
      "sends_count": null,
      "unique_views_count": null,
      "unique_clicks_count": null,
      "utc_offset": null
    },
    {
      "occurred_on": "2020-01-16",
      "fetched_at": null,
      "views_count": 100,
      "impressions_count": null,
      "clicks_count": 50,
      "favorites_count": null,
      "comments_count": null,
      "shares_count": null,
      "ad_spend": null,
      "currency_code": null,
      "is_cumulative": true,
      "unsubscribes_count": null,
      "complaints_count": null,
      "fails_count": null,
      "sends_count": null,
      "unique_views_count": null,
      "unique_clicks_count": null,
      "utc_offset": null
    },
    {
      "occurred_on": "2020-01-17",
      "fetched_at": null,
      "views_count": 200,
      "impressions_count": null,
      "clicks_count": 100,
      "favorites_count": null,
      "comments_count": null,
      "shares_count": null,
      "ad_spend": null,
      "currency_code": null,
      "is_cumulative": true,
      "unsubscribes_count": null,
      "complaints_count": null,
      "fails_count": null,
      "sends_count": null,
      "unique_views_count": null,
      "unique_clicks_count": null,
      "utc_offset": null
    }
  ]
}
Version 2019-10

Marketing events represent actions taken by your app, on behalf of the merchant, to market products, collections, discounts, pages, blog posts, and other features. Marketing events represent actions that 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.

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.

What you can do with MarketingEvent

The Shopify API lets you do the following with the MarketingEvent resource. More detailed versions of these general actions may be available:

MarketingEvent properties

remote_id 
"remote_id": "123abc"

An optional remote identifier for a marketing event. The remote identifier lets Shopify validate engagement data.

event_type
required 
"event_type": "ad"

The type of marketing event. Valid values: 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 post your request here. Our approach is to be more structured than using freeform text, but to still allow for categorization of most types of marketing actions.
marketing_channel
required 
"marketing_channel": "social"

The channel that your marketing event will use. Valid values: search, display, social, email, referral.

referring_domain 
"referring_domain": "facebook.com"

The destination domain of the marketing event. Required if the marketing_channel is set to search or social.

budget 
"budget": 10.75

The budget of the ad campaign.
currency 
"currency": "USD"

The currency for the budget. Required if budget is specified.
budget_type 
"budget_type": "lifetime"

The type of the budget. Required if budget is specified. Valid values: daily, lifetime.'

started_at
required 
"started_at": "2020-01-15T11:56:18-04:00"

The time when the marketing action was started.

scheduled_to_end_at 
"scheduled_to_end_at": "2020-01-22T11:56:18-04:00"

For events with a duration, the time when the event was scheduled to end.
ended_at 
"ended_at": "2020-01-20T11:56:18-04:00"

For events with a duration, the time when the event actually ended.

UTM parameters 
"marketing_event": {
  "utm_campaign": "CanadaDay2020",
  "utm_source": "facebook",
  "utm_medium": "cpc"
}

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.
description 
"description": "Facebook carousel ad #{Time.now.utc.year}"

A description of the marketing event.

manage_url 
"manage_url": "https://mymarketingapp.com/ad/1234"

A link to manage the marketing event. In most cases, this links to the app that created the event.

preview_url 
"preview_url": "https://www.facebook.com/123456/"

A link to the live version of the event, or to a rendered preview in the app that created it.

marketed_resources 
"marketed_resources": [
  {
    "type": "product",
    "id": 12345
  }
]

A list of the items that were marketed in the marketing event. Includes the type and id of each item. Valid values for type are:

  • product
  • collection
  • price_rule
  • discount (Will be replaced by price_rule after April 20, 2017.)
  • page
  • article
  • homepage (Doesn't have an id.)

Endpoints

GET /admin/api/2019-10/marketing_events.json
Retrieves a list of all marketing events. Note: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

The amount of results to return.

(default: 50, maximum: 250)
offset

The number of marketing events to skip.

Retrieve all marketing events

GET /admin/api/2020-04/marketing_events.json
View Response 
HTTP/1.1 200 OK
{
  "marketing_events": [
    {
      "id": 998730532,
      "event_type": "post",
      "remote_id": "12345678",
      "started_at": "2020-01-15T10:56:18-05:00",
      "ended_at": null,
      "scheduled_to_end_at": null,
      "budget": "10.11",
      "currency": "GBP",
      "manage_url": null,
      "preview_url": null,
      "utm_campaign": "1234567890",
      "utm_source": "facebook",
      "utm_medium": "facebook-post",
      "budget_type": "daily",
      "description": null,
      "marketing_channel": "social",
      "paid": false,
      "referring_domain": "facebook.com",
      "breadcrumb_id": null,
      "marketing_activity_id": null,
      "admin_graphql_api_id": "gid://shopify/MarketingEvent/998730532",
      "marketed_resources": []
    }
  ]
}
GET /admin/api/2019-10/marketing_events/count.json
Retrieves a count of all marketing events

Retrieve a count all marketing events

GET /admin/api/2020-04/marketing_events/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 1
}
GET /admin/api/2019-10/marketing_events/{marketing_event_id}.json
Retrieves a single marketing event

Retrieve a single marketing event by its ID

GET /admin/api/2020-04/marketing_events/998730532.json
View Response 
HTTP/1.1 200 OK
{
  "marketing_event": {
    "id": 998730532,
    "event_type": "post",
    "remote_id": "12345678",
    "started_at": "2020-01-15T10:56:18-05:00",
    "ended_at": null,
    "scheduled_to_end_at": null,
    "budget": "10.11",
    "currency": "GBP",
    "manage_url": null,
    "preview_url": null,
    "utm_campaign": "1234567890",
    "utm_source": "facebook",
    "utm_medium": "facebook-post",
    "budget_type": "daily",
    "description": null,
    "marketing_channel": "social",
    "paid": false,
    "referring_domain": "facebook.com",
    "breadcrumb_id": null,
    "marketing_activity_id": null,
    "admin_graphql_api_id": "gid://shopify/MarketingEvent/998730532",
    "marketed_resources": []
  }
}
POST /admin/api/2019-10/marketing_events.json
Creates a marketing event

Create a marketing event

POST /admin/api/2020-04/marketing_events.json
{
  "marketing_event": {
    "started_at": "2020-12-15",
    "utm_campaign": "Christmas2020",
    "utm_source": "facebook",
    "utm_medium": "cpc",
    "event_type": "ad",
    "referring_domain": "facebook.com",
    "marketing_channel": "social",
    "paid": true
  }
}
View Response 
HTTP/1.1 201 Created
{
  "marketing_event": {
    "id": 1056048232,
    "event_type": "ad",
    "remote_id": null,
    "started_at": "2020-12-15T03:00:00-05:00",
    "ended_at": null,
    "scheduled_to_end_at": null,
    "budget": null,
    "currency": null,
    "manage_url": null,
    "preview_url": null,
    "utm_campaign": "Christmas2020",
    "utm_source": "facebook",
    "utm_medium": "cpc",
    "budget_type": null,
    "description": null,
    "marketing_channel": "social",
    "paid": true,
    "referring_domain": "facebook.com",
    "breadcrumb_id": null,
    "marketing_activity_id": 1063897333,
    "admin_graphql_api_id": "gid://shopify/MarketingEvent/1056048232",
    "marketed_resources": []
  }
}
PUT /admin/api/2019-10/marketing_events/{marketing_event_id}.json
Updates a marketing event

Update a marketing event. Can modify only timestamps, remote_id, and budget/currency.

PUT /admin/api/2020-04/marketing_events/998730532.json
{
  "marketing_event": {
    "id": 998730532,
    "remote_id": "1000:2000",
    "started_at": "2020-02-02T00:00 +00:00",
    "ended_at": "2020-02-03T00:00 +00:00",
    "scheduled_to_end_at": "2020-02-04T00:00 +00:00",
    "budget": "11.1",
    "budget_type": "daily",
    "currency": "CAD",
    "utm_campaign": "other",
    "utm_source": "other",
    "utm_medium": "other",
    "event_type": "ad",
    "referring_domain": "instagram.com"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "marketing_event": {
    "id": 998730532,
    "event_type": "post",
    "remote_id": "1000:2000",
    "started_at": "2020-02-01T19:00:00-05:00",
    "ended_at": "2020-02-02T19:00:00-05:00",
    "scheduled_to_end_at": "2020-02-03T19:00:00-05:00",
    "budget": "11.1",
    "currency": "CAD",
    "manage_url": null,
    "preview_url": null,
    "utm_campaign": "1234567890",
    "utm_source": "facebook",
    "utm_medium": "facebook-post",
    "budget_type": "daily",
    "description": null,
    "marketing_channel": "social",
    "paid": false,
    "referring_domain": "facebook.com",
    "breadcrumb_id": null,
    "marketing_activity_id": null,
    "admin_graphql_api_id": "gid://shopify/MarketingEvent/998730532",
    "marketed_resources": []
  }
}
DELETE /admin/api/2019-10/marketing_events/{marketing_event_id}.json
Deletes a marketing event

Delete a marketing event

DELETE /admin/api/2020-04/marketing_events/998730532.json
View Response 
HTTP/1.1 200 OK
{
}
POST /admin/api/2019-10/marketing_events/{marketing_event_id}/engagements.json

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.

occurred_on
required

The date that these engagements occurred on, in the format “YYYY-MM-DD”.
impressions_count

The total number of impressions for the day. An impression occurs when the marketing event is served to a customer, either as a email or through a marketing channel.

views_count

The total number of views for the day. A view occurs when a customer reads the marketing event that was served to them, for example, if the customer opens the email or spends time looking at a Facebook post.

clicks_count

The total number of clicks on the marketing event for the day.
shares_count

The total number of shares for the day.
favorites_count

The total number of favorites for the day.
comments_count

The total number of comments for the day.
ad_spend

The total ad spend for the day, if the marketing event is a paid ad with a daily spend.

is_cumulative

Whether the engagements are reported as lifetime values rather than daily totals.

Add engagements to a marketing engagement

POST /admin/api/2020-04/marketing_events/998730532/engagements.json
{
  "engagements": [
    {
      "occurred_on": "2020-01-15",
      "views_count": 0,
      "clicks_count": 0,
      "favorites_count": 0,
      "ad_spend": 10.0,
      "is_cumulative": true
    },
    {
      "occurred_on": "2020-01-16",
      "views_count": 100,
      "clicks_count": 50,
      "is_cumulative": true
    },
    {
      "occurred_on": "2020-01-17",
      "views_count": 200,
      "clicks_count": 100,
      "is_cumulative": true
    }
  ]
}
View Response 
HTTP/1.1 201 Created
{
  "engagements": [
    {
      "occurred_on": "2020-01-15",
      "fetched_at": null,
      "views_count": 0,
      "impressions_count": null,
      "clicks_count": 0,
      "favorites_count": 0,
      "comments_count": null,
      "shares_count": null,
      "ad_spend": "10.0",
      "currency_code": null,
      "is_cumulative": true,
      "unsubscribes_count": null,
      "complaints_count": null,
      "fails_count": null,
      "sends_count": null,
      "unique_views_count": null,
      "unique_clicks_count": null,
      "utc_offset": null
    },
    {
      "occurred_on": "2020-01-16",
      "fetched_at": null,
      "views_count": 100,
      "impressions_count": null,
      "clicks_count": 50,
      "favorites_count": null,
      "comments_count": null,
      "shares_count": null,
      "ad_spend": null,
      "currency_code": null,
      "is_cumulative": true,
      "unsubscribes_count": null,
      "complaints_count": null,
      "fails_count": null,
      "sends_count": null,
      "unique_views_count": null,
      "unique_clicks_count": null,
      "utc_offset": null
    },
    {
      "occurred_on": "2020-01-17",
      "fetched_at": null,
      "views_count": 200,
      "impressions_count": null,
      "clicks_count": 100,
      "favorites_count": null,
      "comments_count": null,
      "shares_count": null,
      "ad_spend": null,
      "currency_code": null,
      "is_cumulative": true,
      "unsubscribes_count": null,
      "complaints_count": null,
      "fails_count": null,
      "sends_count": null,
      "unique_views_count": null,
      "unique_clicks_count": null,
      "utc_offset": null
    }
  ]
}
Version 2020-01

Marketing events represent actions taken by your app, on behalf of the merchant, to market products, collections, discounts, pages, blog posts, and other features. Marketing events represent actions that 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.

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.

What you can do with MarketingEvent

The Shopify API lets you do the following with the MarketingEvent resource. More detailed versions of these general actions may be available:

MarketingEvent properties

remote_id 
"remote_id": "123abc"

An optional remote identifier for a marketing event. The remote identifier lets Shopify validate engagement data.

event_type
required 
"event_type": "ad"

The type of marketing event. Valid values: 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 post your request here. Our approach is to be more structured than using freeform text, but to still allow for categorization of most types of marketing actions.
marketing_channel
required 
"marketing_channel": "social"

The channel that your marketing event will use. Valid values: search, display, social, email, referral.

referring_domain 
"referring_domain": "facebook.com"

The destination domain of the marketing event. Required if the marketing_channel is set to search or social.

budget 
"budget": 10.75

The budget of the ad campaign.
currency 
"currency": "USD"

The currency for the budget. Required if budget is specified.
budget_type 
"budget_type": "lifetime"

The type of the budget. Required if budget is specified. Valid values: daily, lifetime.'

started_at
required 
"started_at": "2020-01-15T11:56:18-04:00"

The time when the marketing action was started.

scheduled_to_end_at 
"scheduled_to_end_at": "2020-01-22T11:56:18-04:00"

For events with a duration, the time when the event was scheduled to end.
ended_at 
"ended_at": "2020-01-20T11:56:18-04:00"

For events with a duration, the time when the event actually ended.

UTM parameters 
"marketing_event": {
  "utm_campaign": "CanadaDay2020",
  "utm_source": "facebook",
  "utm_medium": "cpc"
}

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.
description 
"description": "Facebook carousel ad #{Time.now.utc.year}"

A description of the marketing event.

manage_url 
"manage_url": "https://mymarketingapp.com/ad/1234"

A link to manage the marketing event. In most cases, this links to the app that created the event.

preview_url 
"preview_url": "https://www.facebook.com/123456/"

A link to the live version of the event, or to a rendered preview in the app that created it.

marketed_resources 
"marketed_resources": [
  {
    "type": "product",
    "id": 12345
  }
]

A list of the items that were marketed in the marketing event. Includes the type and id of each item. Valid values for type are:

  • product
  • collection
  • price_rule
  • discount (Will be replaced by price_rule after April 20, 2017.)
  • page
  • article
  • homepage (Doesn't have an id.)

Endpoints

GET /admin/api/2020-01/marketing_events.json
Retrieves a list of all marketing events. Note: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

The amount of results to return.

(default: 50, maximum: 250)
offset

The number of marketing events to skip.

Retrieve all marketing events

GET /admin/api/2020-04/marketing_events.json
View Response 
HTTP/1.1 200 OK
{
  "marketing_events": [
    {
      "id": 998730532,
      "event_type": "post",
      "remote_id": "12345678",
      "started_at": "2020-01-15T10:56:18-05:00",
      "ended_at": null,
      "scheduled_to_end_at": null,
      "budget": "10.11",
      "currency": "GBP",
      "manage_url": null,
      "preview_url": null,
      "utm_campaign": "1234567890",
      "utm_source": "facebook",
      "utm_medium": "facebook-post",
      "budget_type": "daily",
      "description": null,
      "marketing_channel": "social",
      "paid": false,
      "referring_domain": "facebook.com",
      "breadcrumb_id": null,
      "marketing_activity_id": null,
      "admin_graphql_api_id": "gid://shopify/MarketingEvent/998730532",
      "marketed_resources": []
    }
  ]
}
GET /admin/api/2020-01/marketing_events/count.json
Retrieves a count of all marketing events

Retrieve a count all marketing events

GET /admin/api/2020-04/marketing_events/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 1
}
GET /admin/api/2020-01/marketing_events/{marketing_event_id}.json
Retrieves a single marketing event

Retrieve a single marketing event by its ID

GET /admin/api/2020-04/marketing_events/998730532.json
View Response 
HTTP/1.1 200 OK
{
  "marketing_event": {
    "id": 998730532,
    "event_type": "post",
    "remote_id": "12345678",
    "started_at": "2020-01-15T10:56:18-05:00",
    "ended_at": null,
    "scheduled_to_end_at": null,
    "budget": "10.11",
    "currency": "GBP",
    "manage_url": null,
    "preview_url": null,
    "utm_campaign": "1234567890",
    "utm_source": "facebook",
    "utm_medium": "facebook-post",
    "budget_type": "daily",
    "description": null,
    "marketing_channel": "social",
    "paid": false,
    "referring_domain": "facebook.com",
    "breadcrumb_id": null,
    "marketing_activity_id": null,
    "admin_graphql_api_id": "gid://shopify/MarketingEvent/998730532",
    "marketed_resources": []
  }
}
POST /admin/api/2020-01/marketing_events.json
Creates a marketing event

Create a marketing event

POST /admin/api/2020-04/marketing_events.json
{
  "marketing_event": {
    "started_at": "2020-12-15",
    "utm_campaign": "Christmas2020",
    "utm_source": "facebook",
    "utm_medium": "cpc",
    "event_type": "ad",
    "referring_domain": "facebook.com",
    "marketing_channel": "social",
    "paid": true
  }
}
View Response 
HTTP/1.1 201 Created
{
  "marketing_event": {
    "id": 1056048232,
    "event_type": "ad",
    "remote_id": null,
    "started_at": "2020-12-15T03:00:00-05:00",
    "ended_at": null,
    "scheduled_to_end_at": null,
    "budget": null,
    "currency": null,
    "manage_url": null,
    "preview_url": null,
    "utm_campaign": "Christmas2020",
    "utm_source": "facebook",
    "utm_medium": "cpc",
    "budget_type": null,
    "description": null,
    "marketing_channel": "social",
    "paid": true,
    "referring_domain": "facebook.com",
    "breadcrumb_id": null,
    "marketing_activity_id": 1063897333,
    "admin_graphql_api_id": "gid://shopify/MarketingEvent/1056048232",
    "marketed_resources": []
  }
}
PUT /admin/api/2020-01/marketing_events/{marketing_event_id}.json
Updates a marketing event

Update a marketing event. Can modify only timestamps, remote_id, and budget/currency.

PUT /admin/api/2020-04/marketing_events/998730532.json
{
  "marketing_event": {
    "id": 998730532,
    "remote_id": "1000:2000",
    "started_at": "2020-02-02T00:00 +00:00",
    "ended_at": "2020-02-03T00:00 +00:00",
    "scheduled_to_end_at": "2020-02-04T00:00 +00:00",
    "budget": "11.1",
    "budget_type": "daily",
    "currency": "CAD",
    "utm_campaign": "other",
    "utm_source": "other",
    "utm_medium": "other",
    "event_type": "ad",
    "referring_domain": "instagram.com"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "marketing_event": {
    "id": 998730532,
    "event_type": "post",
    "remote_id": "1000:2000",
    "started_at": "2020-02-01T19:00:00-05:00",
    "ended_at": "2020-02-02T19:00:00-05:00",
    "scheduled_to_end_at": "2020-02-03T19:00:00-05:00",
    "budget": "11.1",
    "currency": "CAD",
    "manage_url": null,
    "preview_url": null,
    "utm_campaign": "1234567890",
    "utm_source": "facebook",
    "utm_medium": "facebook-post",
    "budget_type": "daily",
    "description": null,
    "marketing_channel": "social",
    "paid": false,
    "referring_domain": "facebook.com",
    "breadcrumb_id": null,
    "marketing_activity_id": null,
    "admin_graphql_api_id": "gid://shopify/MarketingEvent/998730532",
    "marketed_resources": []
  }
}
DELETE /admin/api/2020-01/marketing_events/{marketing_event_id}.json
Deletes a marketing event

Delete a marketing event

DELETE /admin/api/2020-04/marketing_events/998730532.json
View Response 
HTTP/1.1 200 OK
{
}
POST /admin/api/2020-01/marketing_events/{marketing_event_id}/engagements.json

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.

occurred_on
required

The date that these engagements occurred on, in the format “YYYY-MM-DD”.
impressions_count

The total number of impressions for the day. An impression occurs when the marketing event is served to a customer, either as a email or through a marketing channel.

views_count

The total number of views for the day. A view occurs when a customer reads the marketing event that was served to them, for example, if the customer opens the email or spends time looking at a Facebook post.

clicks_count

The total number of clicks on the marketing event for the day.
shares_count

The total number of shares for the day.
favorites_count

The total number of favorites for the day.
comments_count

The total number of comments for the day.
ad_spend

The total ad spend for the day, if the marketing event is a paid ad with a daily spend.

is_cumulative

Whether the engagements are reported as lifetime values rather than daily totals.

Add engagements to a marketing engagement

POST /admin/api/2020-04/marketing_events/998730532/engagements.json
{
  "engagements": [
    {
      "occurred_on": "2020-01-15",
      "views_count": 0,
      "clicks_count": 0,
      "favorites_count": 0,
      "ad_spend": 10.0,
      "is_cumulative": true
    },
    {
      "occurred_on": "2020-01-16",
      "views_count": 100,
      "clicks_count": 50,
      "is_cumulative": true
    },
    {
      "occurred_on": "2020-01-17",
      "views_count": 200,
      "clicks_count": 100,
      "is_cumulative": true
    }
  ]
}
View Response 
HTTP/1.1 201 Created
{
  "engagements": [
    {
      "occurred_on": "2020-01-15",
      "fetched_at": null,
      "views_count": 0,
      "impressions_count": null,
      "clicks_count": 0,
      "favorites_count": 0,
      "comments_count": null,
      "shares_count": null,
      "ad_spend": "10.0",
      "currency_code": null,
      "is_cumulative": true,
      "unsubscribes_count": null,
      "complaints_count": null,
      "fails_count": null,
      "sends_count": null,
      "unique_views_count": null,
      "unique_clicks_count": null,
      "utc_offset": null
    },
    {
      "occurred_on": "2020-01-16",
      "fetched_at": null,
      "views_count": 100,
      "impressions_count": null,
      "clicks_count": 50,
      "favorites_count": null,
      "comments_count": null,
      "shares_count": null,
      "ad_spend": null,
      "currency_code": null,
      "is_cumulative": true,
      "unsubscribes_count": null,
      "complaints_count": null,
      "fails_count": null,
      "sends_count": null,
      "unique_views_count": null,
      "unique_clicks_count": null,
      "utc_offset": null
    },
    {
      "occurred_on": "2020-01-17",
      "fetched_at": null,
      "views_count": 200,
      "impressions_count": null,
      "clicks_count": 100,
      "favorites_count": null,
      "comments_count": null,
      "shares_count": null,
      "ad_spend": null,
      "currency_code": null,
      "is_cumulative": true,
      "unsubscribes_count": null,
      "complaints_count": null,
      "fails_count": null,
      "sends_count": null,
      "unique_views_count": null,
      "unique_clicks_count": null,
      "utc_offset": null
    }
  ]
}
Version 2020-04 (Latest)

Marketing events represent actions taken by your app, on behalf of the merchant, to market products, collections, discounts, pages, blog posts, and other features. Marketing events represent actions that 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.

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.

What you can do with MarketingEvent

The Shopify API lets you do the following with the MarketingEvent resource. More detailed versions of these general actions may be available:

MarketingEvent properties

remote_id 
"remote_id": "123abc"

An optional remote identifier for a marketing event. The remote identifier lets Shopify validate engagement data.

event_type
required 
"event_type": "ad"

The type of marketing event. Valid values: 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 post your request here. Our approach is to be more structured than using freeform text, but to still allow for categorization of most types of marketing actions.
marketing_channel
required 
"marketing_channel": "social"

The channel that your marketing event will use. Valid values: search, display, social, email, referral.

referring_domain 
"referring_domain": "facebook.com"

The destination domain of the marketing event. Required if the marketing_channel is set to search or social.

budget 
"budget": 10.75

The budget of the ad campaign.
currency 
"currency": "USD"

The currency for the budget. Required if budget is specified.
budget_type 
"budget_type": "lifetime"

The type of the budget. Required if budget is specified. Valid values: daily, lifetime.'

started_at
required 
"started_at": "2020-01-15T11:56:18-04:00"

The time when the marketing action was started.

scheduled_to_end_at 
"scheduled_to_end_at": "2020-01-22T11:56:18-04:00"

For events with a duration, the time when the event was scheduled to end.
ended_at 
"ended_at": "2020-01-20T11:56:18-04:00"

For events with a duration, the time when the event actually ended.

UTM parameters 
"marketing_event": {
  "utm_campaign": "CanadaDay2020",
  "utm_source": "facebook",
  "utm_medium": "cpc"
}

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.
description 
"description": "Facebook carousel ad #{Time.now.utc.year}"

A description of the marketing event.

manage_url 
"manage_url": "https://mymarketingapp.com/ad/1234"

A link to manage the marketing event. In most cases, this links to the app that created the event.

preview_url 
"preview_url": "https://www.facebook.com/123456/"

A link to the live version of the event, or to a rendered preview in the app that created it.

marketed_resources 
"marketed_resources": [
  {
    "type": "product",
    "id": 12345
  }
]

A list of the items that were marketed in the marketing event. Includes the type and id of each item. Valid values for type are:

  • product
  • collection
  • price_rule
  • discount (Will be replaced by price_rule after April 20, 2017.)
  • page
  • article
  • homepage (Doesn't have an id.)

Endpoints

GET /admin/api/2020-04/marketing_events.json
Retrieves a list of all marketing events. Note: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

The amount of results to return.

(default: 50, maximum: 250)
offset

The number of marketing events to skip.

Retrieve all marketing events

GET /admin/api/2020-04/marketing_events.json
View Response 
HTTP/1.1 200 OK
{
  "marketing_events": [
    {
      "id": 998730532,
      "event_type": "post",
      "remote_id": "12345678",
      "started_at": "2020-01-15T10:56:18-05:00",
      "ended_at": null,
      "scheduled_to_end_at": null,
      "budget": "10.11",
      "currency": "GBP",
      "manage_url": null,
      "preview_url": null,
      "utm_campaign": "1234567890",
      "utm_source": "facebook",
      "utm_medium": "facebook-post",
      "budget_type": "daily",
      "description": null,
      "marketing_channel": "social",
      "paid": false,
      "referring_domain": "facebook.com",
      "breadcrumb_id": null,
      "marketing_activity_id": null,
      "admin_graphql_api_id": "gid://shopify/MarketingEvent/998730532",
      "marketed_resources": []
    }
  ]
}
GET /admin/api/2020-04/marketing_events/count.json
Retrieves a count of all marketing events

Retrieve a count all marketing events

GET /admin/api/2020-04/marketing_events/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 1
}
GET /admin/api/2020-04/marketing_events/{marketing_event_id}.json
Retrieves a single marketing event

Retrieve a single marketing event by its ID

GET /admin/api/2020-04/marketing_events/998730532.json
View Response 
HTTP/1.1 200 OK
{
  "marketing_event": {
    "id": 998730532,
    "event_type": "post",
    "remote_id": "12345678",
    "started_at": "2020-01-15T10:56:18-05:00",
    "ended_at": null,
    "scheduled_to_end_at": null,
    "budget": "10.11",
    "currency": "GBP",
    "manage_url": null,
    "preview_url": null,
    "utm_campaign": "1234567890",
    "utm_source": "facebook",
    "utm_medium": "facebook-post",
    "budget_type": "daily",
    "description": null,
    "marketing_channel": "social",
    "paid": false,
    "referring_domain": "facebook.com",
    "breadcrumb_id": null,
    "marketing_activity_id": null,
    "admin_graphql_api_id": "gid://shopify/MarketingEvent/998730532",
    "marketed_resources": []
  }
}
POST /admin/api/2020-04/marketing_events.json
Creates a marketing event

Create a marketing event

POST /admin/api/2020-04/marketing_events.json
{
  "marketing_event": {
    "started_at": "2020-12-15",
    "utm_campaign": "Christmas2020",
    "utm_source": "facebook",
    "utm_medium": "cpc",
    "event_type": "ad",
    "referring_domain": "facebook.com",
    "marketing_channel": "social",
    "paid": true
  }
}
View Response 
HTTP/1.1 201 Created
{
  "marketing_event": {
    "id": 1056048232,
    "event_type": "ad",
    "remote_id": null,
    "started_at": "2020-12-15T03:00:00-05:00",
    "ended_at": null,
    "scheduled_to_end_at": null,
    "budget": null,
    "currency": null,
    "manage_url": null,
    "preview_url": null,
    "utm_campaign": "Christmas2020",
    "utm_source": "facebook",
    "utm_medium": "cpc",
    "budget_type": null,
    "description": null,
    "marketing_channel": "social",
    "paid": true,
    "referring_domain": "facebook.com",
    "breadcrumb_id": null,
    "marketing_activity_id": 1063897333,
    "admin_graphql_api_id": "gid://shopify/MarketingEvent/1056048232",
    "marketed_resources": []
  }
}
PUT /admin/api/2020-04/marketing_events/{marketing_event_id}.json
Updates a marketing event

Update a marketing event. Can modify only timestamps, remote_id, and budget/currency.

PUT /admin/api/2020-04/marketing_events/998730532.json
{
  "marketing_event": {
    "id": 998730532,
    "remote_id": "1000:2000",
    "started_at": "2020-02-02T00:00 +00:00",
    "ended_at": "2020-02-03T00:00 +00:00",
    "scheduled_to_end_at": "2020-02-04T00:00 +00:00",
    "budget": "11.1",
    "budget_type": "daily",
    "currency": "CAD",
    "utm_campaign": "other",
    "utm_source": "other",
    "utm_medium": "other",
    "event_type": "ad",
    "referring_domain": "instagram.com"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "marketing_event": {
    "id": 998730532,
    "event_type": "post",
    "remote_id": "1000:2000",
    "started_at": "2020-02-01T19:00:00-05:00",
    "ended_at": "2020-02-02T19:00:00-05:00",
    "scheduled_to_end_at": "2020-02-03T19:00:00-05:00",
    "budget": "11.1",
    "currency": "CAD",
    "manage_url": null,
    "preview_url": null,
    "utm_campaign": "1234567890",
    "utm_source": "facebook",
    "utm_medium": "facebook-post",
    "budget_type": "daily",
    "description": null,
    "marketing_channel": "social",
    "paid": false,
    "referring_domain": "facebook.com",
    "breadcrumb_id": null,
    "marketing_activity_id": null,
    "admin_graphql_api_id": "gid://shopify/MarketingEvent/998730532",
    "marketed_resources": []
  }
}
DELETE /admin/api/2020-04/marketing_events/{marketing_event_id}.json
Deletes a marketing event

Delete a marketing event

DELETE /admin/api/2020-04/marketing_events/998730532.json
View Response 
HTTP/1.1 200 OK
{
}
POST /admin/api/2020-04/marketing_events/{marketing_event_id}/engagements.json

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.

occurred_on
required

The date that these engagements occurred on, in the format “YYYY-MM-DD”.
impressions_count

The total number of impressions for the day. An impression occurs when the marketing event is served to a customer, either as a email or through a marketing channel.

views_count

The total number of views for the day. A view occurs when a customer reads the marketing event that was served to them, for example, if the customer opens the email or spends time looking at a Facebook post.

clicks_count

The total number of clicks on the marketing event for the day.
shares_count

The total number of shares for the day.
favorites_count

The total number of favorites for the day.
comments_count

The total number of comments for the day.
ad_spend

The total ad spend for the day, if the marketing event is a paid ad with a daily spend.

is_cumulative

Whether the engagements are reported as lifetime values rather than daily totals.

Add engagements to a marketing engagement

POST /admin/api/2020-04/marketing_events/998730532/engagements.json
{
  "engagements": [
    {
      "occurred_on": "2020-01-15",
      "views_count": 0,
      "clicks_count": 0,
      "favorites_count": 0,
      "ad_spend": 10.0,
      "is_cumulative": true
    },
    {
      "occurred_on": "2020-01-16",
      "views_count": 100,
      "clicks_count": 50,
      "is_cumulative": true
    },
    {
      "occurred_on": "2020-01-17",
      "views_count": 200,
      "clicks_count": 100,
      "is_cumulative": true
    }
  ]
}
View Response 
HTTP/1.1 201 Created
{
  "engagements": [
    {
      "occurred_on": "2020-01-15",
      "fetched_at": null,
      "views_count": 0,
      "impressions_count": null,
      "clicks_count": 0,
      "favorites_count": 0,
      "comments_count": null,
      "shares_count": null,
      "ad_spend": "10.0",
      "currency_code": null,
      "is_cumulative": true,
      "unsubscribes_count": null,
      "complaints_count": null,
      "fails_count": null,
      "sends_count": null,
      "unique_views_count": null,
      "unique_clicks_count": null,
      "utc_offset": null
    },
    {
      "occurred_on": "2020-01-16",
      "fetched_at": null,
      "views_count": 100,
      "impressions_count": null,
      "clicks_count": 50,
      "favorites_count": null,
      "comments_count": null,
      "shares_count": null,
      "ad_spend": null,
      "currency_code": null,
      "is_cumulative": true,
      "unsubscribes_count": null,
      "complaints_count": null,
      "fails_count": null,
      "sends_count": null,
      "unique_views_count": null,
      "unique_clicks_count": null,
      "utc_offset": null
    },
    {
      "occurred_on": "2020-01-17",
      "fetched_at": null,
      "views_count": 200,
      "impressions_count": null,
      "clicks_count": 100,
      "favorites_count": null,
      "comments_count": null,
      "shares_count": null,
      "ad_spend": null,
      "currency_code": null,
      "is_cumulative": true,
      "unsubscribes_count": null,
      "complaints_count": null,
      "fails_count": null,
      "sends_count": null,
      "unique_views_count": null,
      "unique_clicks_count": null,
      "utc_offset": null
    }
  ]
}
Version 2020-07 (Release candidate)

Marketing events represent actions taken by your app, on behalf of the merchant, to market products, collections, discounts, pages, blog posts, and other features. Marketing events represent actions that 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.

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.

What you can do with MarketingEvent

The Shopify API lets you do the following with the MarketingEvent resource. More detailed versions of these general actions may be available:

MarketingEvent properties

remote_id 
"remote_id": "123abc"

An optional remote identifier for a marketing event. The remote identifier lets Shopify validate engagement data.

event_type
required 
"event_type": "ad"

The type of marketing event. Valid values: 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 post your request here. Our approach is to be more structured than using freeform text, but to still allow for categorization of most types of marketing actions.
marketing_channel
required 
"marketing_channel": "social"

The channel that your marketing event will use. Valid values: search, display, social, email, referral.

referring_domain 
"referring_domain": "facebook.com"

The destination domain of the marketing event. Required if the marketing_channel is set to search or social.

budget 
"budget": 10.75

The budget of the ad campaign.
currency 
"currency": "USD"

The currency for the budget. Required if budget is specified.
budget_type 
"budget_type": "lifetime"

The type of the budget. Required if budget is specified. Valid values: daily, lifetime.'

started_at
required 
"started_at": "2020-01-15T11:56:18-04:00"

The time when the marketing action was started.

scheduled_to_end_at 
"scheduled_to_end_at": "2020-01-22T11:56:18-04:00"

For events with a duration, the time when the event was scheduled to end.
ended_at 
"ended_at": "2020-01-20T11:56:18-04:00"

For events with a duration, the time when the event actually ended.

UTM parameters 
"marketing_event": {
  "utm_campaign": "CanadaDay2020",
  "utm_source": "facebook",
  "utm_medium": "cpc"
}

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.
description 
"description": "Facebook carousel ad #{Time.now.utc.year}"

A description of the marketing event.

manage_url 
"manage_url": "https://mymarketingapp.com/ad/1234"

A link to manage the marketing event. In most cases, this links to the app that created the event.

preview_url 
"preview_url": "https://www.facebook.com/123456/"

A link to the live version of the event, or to a rendered preview in the app that created it.

marketed_resources 
"marketed_resources": [
  {
    "type": "product",
    "id": 12345
  }
]

A list of the items that were marketed in the marketing event. Includes the type and id of each item. Valid values for type are:

  • product
  • collection
  • price_rule
  • discount (Will be replaced by price_rule after April 20, 2017.)
  • page
  • article
  • homepage (Doesn't have an id.)

Endpoints

GET /admin/api/2020-07/marketing_events.json
Retrieves a list of all marketing events. Note: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
limit

The amount of results to return.

(default: 50, maximum: 250)
offset

The number of marketing events to skip.

Retrieve all marketing events

GET /admin/api/2020-04/marketing_events.json
View Response 
HTTP/1.1 200 OK
{
  "marketing_events": [
    {
      "id": 998730532,
      "event_type": "post",
      "remote_id": "12345678",
      "started_at": "2020-01-15T10:56:18-05:00",
      "ended_at": null,
      "scheduled_to_end_at": null,
      "budget": "10.11",
      "currency": "GBP",
      "manage_url": null,
      "preview_url": null,
      "utm_campaign": "1234567890",
      "utm_source": "facebook",
      "utm_medium": "facebook-post",
      "budget_type": "daily",
      "description": null,
      "marketing_channel": "social",
      "paid": false,
      "referring_domain": "facebook.com",
      "breadcrumb_id": null,
      "marketing_activity_id": null,
      "admin_graphql_api_id": "gid://shopify/MarketingEvent/998730532",
      "marketed_resources": []
    }
  ]
}
GET /admin/api/2020-07/marketing_events/count.json
Retrieves a count of all marketing events

Retrieve a count all marketing events

GET /admin/api/2020-04/marketing_events/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 1
}
GET /admin/api/2020-07/marketing_events/{marketing_event_id}.json
Retrieves a single marketing event

Retrieve a single marketing event by its ID

GET /admin/api/2020-04/marketing_events/998730532.json
View Response 
HTTP/1.1 200 OK
{
  "marketing_event": {
    "id": 998730532,
    "event_type": "post",
    "remote_id": "12345678",
    "started_at": "2020-01-15T10:56:18-05:00",
    "ended_at": null,
    "scheduled_to_end_at": null,
    "budget": "10.11",
    "currency": "GBP",
    "manage_url": null,
    "preview_url": null,
    "utm_campaign": "1234567890",
    "utm_source": "facebook",
    "utm_medium": "facebook-post",
    "budget_type": "daily",
    "description": null,
    "marketing_channel": "social",
    "paid": false,
    "referring_domain": "facebook.com",
    "breadcrumb_id": null,
    "marketing_activity_id": null,
    "admin_graphql_api_id": "gid://shopify/MarketingEvent/998730532",
    "marketed_resources": []
  }
}
POST /admin/api/2020-07/marketing_events.json
Creates a marketing event

Create a marketing event

POST /admin/api/2020-04/marketing_events.json
{
  "marketing_event": {
    "started_at": "2020-12-15",
    "utm_campaign": "Christmas2020",
    "utm_source": "facebook",
    "utm_medium": "cpc",
    "event_type": "ad",
    "referring_domain": "facebook.com",
    "marketing_channel": "social",
    "paid": true
  }
}
View Response 
HTTP/1.1 201 Created
{
  "marketing_event": {
    "id": 1056048232,
    "event_type": "ad",
    "remote_id": null,
    "started_at": "2020-12-15T03:00:00-05:00",
    "ended_at": null,
    "scheduled_to_end_at": null,
    "budget": null,
    "currency": null,
    "manage_url": null,
    "preview_url": null,
    "utm_campaign": "Christmas2020",
    "utm_source": "facebook",
    "utm_medium": "cpc",
    "budget_type": null,
    "description": null,
    "marketing_channel": "social",
    "paid": true,
    "referring_domain": "facebook.com",
    "breadcrumb_id": null,
    "marketing_activity_id": 1063897333,
    "admin_graphql_api_id": "gid://shopify/MarketingEvent/1056048232",
    "marketed_resources": []
  }
}
PUT /admin/api/2020-07/marketing_events/{marketing_event_id}.json
Updates a marketing event

Update a marketing event. Can modify only timestamps, remote_id, and budget/currency.

PUT /admin/api/2020-04/marketing_events/998730532.json
{
  "marketing_event": {
    "id": 998730532,
    "remote_id": "1000:2000",
    "started_at": "2020-02-02T00:00 +00:00",
    "ended_at": "2020-02-03T00:00 +00:00",
    "scheduled_to_end_at": "2020-02-04T00:00 +00:00",
    "budget": "11.1",
    "budget_type": "daily",
    "currency": "CAD",
    "utm_campaign": "other",
    "utm_source": "other",
    "utm_medium": "other",
    "event_type": "ad",
    "referring_domain": "instagram.com"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "marketing_event": {
    "id": 998730532,
    "event_type": "post",
    "remote_id": "1000:2000",
    "started_at": "2020-02-01T19:00:00-05:00",
    "ended_at": "2020-02-02T19:00:00-05:00",
    "scheduled_to_end_at": "2020-02-03T19:00:00-05:00",
    "budget": "11.1",
    "currency": "CAD",
    "manage_url": null,
    "preview_url": null,
    "utm_campaign": "1234567890",
    "utm_source": "facebook",
    "utm_medium": "facebook-post",
    "budget_type": "daily",
    "description": null,
    "marketing_channel": "social",
    "paid": false,
    "referring_domain": "facebook.com",
    "breadcrumb_id": null,
    "marketing_activity_id": null,
    "admin_graphql_api_id": "gid://shopify/MarketingEvent/998730532",
    "marketed_resources": []
  }
}
DELETE /admin/api/2020-07/marketing_events/{marketing_event_id}.json
Deletes a marketing event

Delete a marketing event

DELETE /admin/api/2020-04/marketing_events/998730532.json
View Response 
HTTP/1.1 200 OK
{
}
POST /admin/api/2020-07/marketing_events/{marketing_event_id}/engagements.json

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.

occurred_on
required

The date that these engagements occurred on, in the format “YYYY-MM-DD”.
impressions_count

The total number of impressions for the day. An impression occurs when the marketing event is served to a customer, either as a email or through a marketing channel.

views_count

The total number of views for the day. A view occurs when a customer reads the marketing event that was served to them, for example, if the customer opens the email or spends time looking at a Facebook post.

clicks_count

The total number of clicks on the marketing event for the day.
shares_count

The total number of shares for the day.
favorites_count

The total number of favorites for the day.
comments_count

The total number of comments for the day.
ad_spend

The total ad spend for the day, if the marketing event is a paid ad with a daily spend.

is_cumulative

Whether the engagements are reported as lifetime values rather than daily totals.

Add engagements to a marketing engagement

POST /admin/api/2020-04/marketing_events/998730532/engagements.json
{
  "engagements": [
    {
      "occurred_on": "2020-01-15",
      "views_count": 0,
      "clicks_count": 0,
      "favorites_count": 0,
      "ad_spend": 10.0,
      "is_cumulative": true
    },
    {
      "occurred_on": "2020-01-16",
      "views_count": 100,
      "clicks_count": 50,
      "is_cumulative": true
    },
    {
      "occurred_on": "2020-01-17",
      "views_count": 200,
      "clicks_count": 100,
      "is_cumulative": true
    }
  ]
}
View Response 
HTTP/1.1 201 Created
{
  "engagements": [
    {
      "occurred_on": "2020-01-15",
      "fetched_at": null,
      "views_count": 0,
      "impressions_count": null,
      "clicks_count": 0,
      "favorites_count": 0,
      "comments_count": null,
      "shares_count": null,
      "ad_spend": "10.0",
      "currency_code": null,
      "is_cumulative": true,
      "unsubscribes_count": null,
      "complaints_count": null,
      "fails_count": null,
      "sends_count": null,
      "unique_views_count": null,
      "unique_clicks_count": null,
      "utc_offset": null
    },
    {
      "occurred_on": "2020-01-16",
      "fetched_at": null,
      "views_count": 100,
      "impressions_count": null,
      "clicks_count": 50,
      "favorites_count": null,
      "comments_count": null,
      "shares_count": null,
      "ad_spend": null,
      "currency_code": null,
      "is_cumulative": true,
      "unsubscribes_count": null,
      "complaints_count": null,
      "fails_count": null,
      "sends_count": null,
      "unique_views_count": null,
      "unique_clicks_count": null,
      "utc_offset": null
    },
    {
      "occurred_on": "2020-01-17",
      "fetched_at": null,
      "views_count": 200,
      "impressions_count": null,
      "clicks_count": 100,
      "favorites_count": null,
      "comments_count": null,
      "shares_count": null,
      "ad_spend": null,
      "currency_code": null,
      "is_cumulative": true,
      "unsubscribes_count": null,
      "complaints_count": null,
      "fails_count": null,
      "sends_count": null,
      "unique_views_count": null,
      "unique_clicks_count": null,
      "utc_offset": null
    }
  ]
}