MarketingEvent
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:
- GET /admin/api/2020-01/marketing_events.json Retrieves a list of all marketing events
- GET /admin/api/2020-01/marketing_events/count.json Retrieves a count of all marketing events
- GET /admin/api/2020-01/marketing_events/{marketing_event_id}.json Retrieves a single marketing event
- POST /admin/api/2020-01/marketing_events.json Creates a marketing event
- PUT /admin/api/2020-01/marketing_events/{marketing_event_id}.json Updates a marketing event
- DELETE /admin/api/2020-01/marketing_events/{marketing_event_id}.json Deletes a marketing event
- POST /admin/api/2020-01/marketing_events/{marketing_event_id}/engagements.json Creates marketing engagements on a marketing event
MarketingEvent properties
remote_id |
An optional remote identifier for a marketing event. The remote identifier lets Shopify validate engagement data. |
event_type
required |
The type of marketing event. Valid values: NoteIf 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 |
The channel that your marketing event will use. Valid values: |
paid
required |
Whether the event is paid or organic. |
referring_domain |
The destination domain of the marketing event. Required if the |
budget |
The budget of the ad campaign. |
currency |
The currency for the budget. Required if |
budget_type |
The type of the budget. Required if |
started_at
required |
The time when the marketing action was started. |
scheduled_to_end_at |
For events with a duration, the time when the event was scheduled to end. |
ended_at |
For events with a duration, the time when the event actually ended. |
UTM parameters |
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 |
description |
A description of the marketing event. |
manage_url |
A link to manage the marketing event. In most cases, this links to the app that created the event. |
preview_url |
A link to the live version of the event, or to a rendered preview in the app that created it. |
marketed_resources |
A list of the items that were marketed in the marketing event. Includes the
|
Endpoints
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-01/marketing_events.json
View Response
HTTP/1.1 200 OK
{
"marketing_events": [
{
"id": 998730532,
"event_type": "post",
"remote_id": "12345678",
"started_at": "2021-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": []
}
]
}
Retrieve a count all marketing events
GET /admin/api/2020-01/marketing_events/count.json
View Response
HTTP/1.1 200 OK
{
"count": 1
}
Retrieve a single marketing event by its ID
GET /admin/api/2020-01/marketing_events/998730532.json
View Response
HTTP/1.1 200 OK
{
"marketing_event": {
"id": 998730532,
"event_type": "post",
"remote_id": "12345678",
"started_at": "2021-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": []
}
}
Create a marketing event
POST /admin/api/2020-01/marketing_events.json
{
"marketing_event": {
"started_at": "2021-12-15",
"utm_campaign": "Christmas2021",
"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": 1056048233,
"event_type": "ad",
"remote_id": null,
"started_at": "2021-12-15T00:00:00-05:00",
"ended_at": null,
"scheduled_to_end_at": null,
"budget": null,
"currency": null,
"manage_url": null,
"preview_url": null,
"utm_campaign": "Christmas2021",
"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": 1063897334,
"admin_graphql_api_id": "gid://shopify/MarketingEvent/1056048233",
"marketed_resources": []
}
}
Update a marketing event. Can modify only timestamps, remote_id, and budget/currency.
PUT /admin/api/2020-01/marketing_events/998730532.json
{
"marketing_event": {
"id": 998730532,
"remote_id": "1000:2000",
"started_at": "2021-02-02T00:00 +00:00",
"ended_at": "2021-02-03T00:00 +00:00",
"scheduled_to_end_at": "2021-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": "2021-02-01T19:00:00-05:00",
"ended_at": "2021-02-02T19:00:00-05:00",
"scheduled_to_end_at": "2021-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 a marketing event
DELETE /admin/api/2020-01/marketing_events/998730532.json
View Response
HTTP/1.1 200 OK
{
}
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-01/marketing_events/998730532/engagements.json
{
"engagements": [
{
"occurred_on": "2021-01-15",
"views_count": 0,
"clicks_count": 0,
"favorites_count": 0,
"ad_spend": 10.0,
"is_cumulative": true
},
{
"occurred_on": "2021-01-16",
"views_count": 100,
"clicks_count": 50,
"is_cumulative": true
},
{
"occurred_on": "2021-01-17",
"views_count": 200,
"clicks_count": 100,
"is_cumulative": true
}
]
}
View Response
HTTP/1.1 201 Created
{
"engagements": [
{
"occurred_on": "2021-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": "2021-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": "2021-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
}
]
}
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:
- GET /admin/api/2020-04/marketing_events.json Retrieves a list of all marketing events
- GET /admin/api/2020-04/marketing_events/count.json Retrieves a count of all marketing events
- GET /admin/api/2020-04/marketing_events/{marketing_event_id}.json Retrieves a single marketing event
- POST /admin/api/2020-04/marketing_events.json Creates a marketing event
- PUT /admin/api/2020-04/marketing_events/{marketing_event_id}.json Updates a marketing event
- DELETE /admin/api/2020-04/marketing_events/{marketing_event_id}.json Deletes a marketing event
- POST /admin/api/2020-04/marketing_events/{marketing_event_id}/engagements.json Creates marketing engagements on a marketing event
MarketingEvent properties
remote_id |
An optional remote identifier for a marketing event. The remote identifier lets Shopify validate engagement data. |
event_type
required |
The type of marketing event. Valid values: NoteIf 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 |
The channel that your marketing event will use. Valid values: |
paid
required |
Whether the event is paid or organic. |
referring_domain |
The destination domain of the marketing event. Required if the |
budget |
The budget of the ad campaign. |
currency |
The currency for the budget. Required if |
budget_type |
The type of the budget. Required if |
started_at
required |
The time when the marketing action was started. |
scheduled_to_end_at |
For events with a duration, the time when the event was scheduled to end. |
ended_at |
For events with a duration, the time when the event actually ended. |
UTM parameters |
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 |
description |
A description of the marketing event. |
manage_url |
A link to manage the marketing event. In most cases, this links to the app that created the event. |
preview_url |
A link to the live version of the event, or to a rendered preview in the app that created it. |
marketed_resources |
A list of the items that were marketed in the marketing event. Includes the
|
Endpoints
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": "2021-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": []
}
]
}
Retrieve a count all marketing events
GET /admin/api/2020-04/marketing_events/count.json
View Response
HTTP/1.1 200 OK
{
"count": 1
}
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": "2021-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": []
}
}
Create a marketing event
POST /admin/api/2020-04/marketing_events.json
{
"marketing_event": {
"started_at": "2021-12-15",
"utm_campaign": "Christmas2021",
"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": 1056048233,
"event_type": "ad",
"remote_id": null,
"started_at": "2021-12-15T00:00:00-05:00",
"ended_at": null,
"scheduled_to_end_at": null,
"budget": null,
"currency": null,
"manage_url": null,
"preview_url": null,
"utm_campaign": "Christmas2021",
"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": 1063897334,
"admin_graphql_api_id": "gid://shopify/MarketingEvent/1056048233",
"marketed_resources": []
}
}
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": "2021-02-02T00:00 +00:00",
"ended_at": "2021-02-03T00:00 +00:00",
"scheduled_to_end_at": "2021-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": "2021-02-01T19:00:00-05:00",
"ended_at": "2021-02-02T19:00:00-05:00",
"scheduled_to_end_at": "2021-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 a marketing event
DELETE /admin/api/2020-04/marketing_events/998730532.json
View Response
HTTP/1.1 200 OK
{
}
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": "2021-01-15",
"views_count": 0,
"clicks_count": 0,
"favorites_count": 0,
"ad_spend": 10.0,
"is_cumulative": true
},
{
"occurred_on": "2021-01-16",
"views_count": 100,
"clicks_count": 50,
"is_cumulative": true
},
{
"occurred_on": "2021-01-17",
"views_count": 200,
"clicks_count": 100,
"is_cumulative": true
}
]
}
View Response
HTTP/1.1 201 Created
{
"engagements": [
{
"occurred_on": "2021-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": "2021-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": "2021-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
}
]
}
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:
- GET /admin/api/2020-07/marketing_events.json Retrieves a list of all marketing events
- GET /admin/api/2020-07/marketing_events/count.json Retrieves a count of all marketing events
- GET /admin/api/2020-07/marketing_events/{marketing_event_id}.json Retrieves a single marketing event
- POST /admin/api/2020-07/marketing_events.json Creates a marketing event
- PUT /admin/api/2020-07/marketing_events/{marketing_event_id}.json Updates a marketing event
- DELETE /admin/api/2020-07/marketing_events/{marketing_event_id}.json Deletes a marketing event
- POST /admin/api/2020-07/marketing_events/{marketing_event_id}/engagements.json Creates marketing engagements on a marketing event
MarketingEvent properties
remote_id |
An optional remote identifier for a marketing event. The remote identifier lets Shopify validate engagement data. |
event_type
required |
The type of marketing event. Valid values: NoteIf 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 |
The channel that your marketing event will use. Valid values: |
paid
required |
Whether the event is paid or organic. |
referring_domain |
The destination domain of the marketing event. Required if the |
budget |
The budget of the ad campaign. |
currency |
The currency for the budget. Required if |
budget_type |
The type of the budget. Required if |
started_at
required |
The time when the marketing action was started. |
scheduled_to_end_at |
For events with a duration, the time when the event was scheduled to end. |
ended_at |
For events with a duration, the time when the event actually ended. |
UTM parameters |
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 |
description |
A description of the marketing event. |
manage_url |
A link to manage the marketing event. In most cases, this links to the app that created the event. |
preview_url |
A link to the live version of the event, or to a rendered preview in the app that created it. |
marketed_resources |
A list of the items that were marketed in the marketing event. Includes the
|
Endpoints
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-07/marketing_events.json
View Response
HTTP/1.1 200 OK
{
"marketing_events": [
{
"id": 998730532,
"event_type": "post",
"remote_id": "12345678",
"started_at": "2021-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": []
}
]
}
Retrieve a count all marketing events
GET /admin/api/2020-07/marketing_events/count.json
View Response
HTTP/1.1 200 OK
{
"count": 1
}
Retrieve a single marketing event by its ID
GET /admin/api/2020-07/marketing_events/998730532.json
View Response
HTTP/1.1 200 OK
{
"marketing_event": {
"id": 998730532,
"event_type": "post",
"remote_id": "12345678",
"started_at": "2021-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": []
}
}
Create a marketing event
POST /admin/api/2020-07/marketing_events.json
{
"marketing_event": {
"started_at": "2021-12-15",
"utm_campaign": "Christmas2021",
"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": 1056048233,
"event_type": "ad",
"remote_id": null,
"started_at": "2021-12-15T00:00:00-05:00",
"ended_at": null,
"scheduled_to_end_at": null,
"budget": null,
"currency": null,
"manage_url": null,
"preview_url": null,
"utm_campaign": "Christmas2021",
"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": 1063897334,
"admin_graphql_api_id": "gid://shopify/MarketingEvent/1056048233",
"marketed_resources": []
}
}
Update a marketing event. Can modify only timestamps, remote_id, and budget/currency.
PUT /admin/api/2020-07/marketing_events/998730532.json
{
"marketing_event": {
"id": 998730532,
"remote_id": "1000:2000",
"started_at": "2021-02-02T00:00 +00:00",
"ended_at": "2021-02-03T00:00 +00:00",
"scheduled_to_end_at": "2021-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": "2021-02-01T19:00:00-05:00",
"ended_at": "2021-02-02T19:00:00-05:00",
"scheduled_to_end_at": "2021-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 a marketing event
DELETE /admin/api/2020-07/marketing_events/998730532.json
View Response
HTTP/1.1 200 OK
{
}
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-07/marketing_events/998730532/engagements.json
{
"engagements": [
{
"occurred_on": "2021-01-15",
"views_count": 0,
"clicks_count": 0,
"favorites_count": 0,
"ad_spend": 10.0,
"is_cumulative": true
},
{
"occurred_on": "2021-01-16",
"views_count": 100,
"clicks_count": 50,
"is_cumulative": true
},
{
"occurred_on": "2021-01-17",
"views_count": 200,
"clicks_count": 100,
"is_cumulative": true
}
]
}
View Response
HTTP/1.1 201 Created
{
"engagements": [
{
"occurred_on": "2021-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": "2021-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": "2021-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
}
]
}
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:
- GET /admin/api/2020-10/marketing_events.json Retrieves a list of all marketing events
- GET /admin/api/2020-10/marketing_events/count.json Retrieves a count of all marketing events
- GET /admin/api/2020-10/marketing_events/{marketing_event_id}.json Retrieves a single marketing event
- POST /admin/api/2020-10/marketing_events.json Creates a marketing event
- PUT /admin/api/2020-10/marketing_events/{marketing_event_id}.json Updates a marketing event
- DELETE /admin/api/2020-10/marketing_events/{marketing_event_id}.json Deletes a marketing event
- POST /admin/api/2020-10/marketing_events/{marketing_event_id}/engagements.json Creates marketing engagements on a marketing event
MarketingEvent properties
remote_id |
An optional remote identifier for a marketing event. The remote identifier lets Shopify validate engagement data. |
event_type
required |
The type of marketing event. Valid values: NoteIf 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 |
The channel that your marketing event will use. Valid values: |
paid
required |
Whether the event is paid or organic. |
referring_domain |
The destination domain of the marketing event. Required if the |
budget |
The budget of the ad campaign. |
currency |
The currency for the budget. Required if |
budget_type |
The type of the budget. Required if |
started_at
required |
The time when the marketing action was started. |
scheduled_to_end_at |
For events with a duration, the time when the event was scheduled to end. |
ended_at |
For events with a duration, the time when the event actually ended. |
UTM parameters |
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 |
description |
A description of the marketing event. |
manage_url |
A link to manage the marketing event. In most cases, this links to the app that created the event. |
preview_url |
A link to the live version of the event, or to a rendered preview in the app that created it. |
marketed_resources |
A list of the items that were marketed in the marketing event. Includes the
|
Endpoints
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-10/marketing_events.json
View Response
HTTP/1.1 200 OK
{
"marketing_events": [
{
"id": 998730532,
"event_type": "post",
"remote_id": "12345678",
"started_at": "2021-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": []
}
]
}
Retrieve a count all marketing events
GET /admin/api/2020-10/marketing_events/count.json
View Response
HTTP/1.1 200 OK
{
"count": 1
}
Retrieve a single marketing event by its ID
GET /admin/api/2020-10/marketing_events/998730532.json
View Response
HTTP/1.1 200 OK
{
"marketing_event": {
"id": 998730532,
"event_type": "post",
"remote_id": "12345678",
"started_at": "2021-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": []
}
}
Create a marketing event
POST /admin/api/2020-10/marketing_events.json
{
"marketing_event": {
"started_at": "2021-12-15",
"utm_campaign": "Christmas2021",
"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": 1056048233,
"event_type": "ad",
"remote_id": null,
"started_at": "2021-12-15T00:00:00-05:00",
"ended_at": null,
"scheduled_to_end_at": null,
"budget": null,
"currency": null,
"manage_url": null,
"preview_url": null,
"utm_campaign": "Christmas2021",
"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": 1063897334,
"admin_graphql_api_id": "gid://shopify/MarketingEvent/1056048233",
"marketed_resources": []
}
}
Update a marketing event. Can modify only timestamps, remote_id, and budget/currency.
PUT /admin/api/2020-10/marketing_events/998730532.json
{
"marketing_event": {
"id": 998730532,
"remote_id": "1000:2000",
"started_at": "2021-02-02T00:00 +00:00",
"ended_at": "2021-02-03T00:00 +00:00",
"scheduled_to_end_at": "2021-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": "2021-02-01T19:00:00-05:00",
"ended_at": "2021-02-02T19:00:00-05:00",
"scheduled_to_end_at": "2021-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 a marketing event
DELETE /admin/api/2020-10/marketing_events/998730532.json
View Response
HTTP/1.1 200 OK
{
}
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-10/marketing_events/998730532/engagements.json
{
"engagements": [
{
"occurred_on": "2021-01-15",
"views_count": 0,
"clicks_count": 0,
"favorites_count": 0,
"ad_spend": 10.0,
"is_cumulative": true
},
{
"occurred_on": "2021-01-16",
"views_count": 100,
"clicks_count": 50,
"is_cumulative": true
},
{
"occurred_on": "2021-01-17",
"views_count": 200,
"clicks_count": 100,
"is_cumulative": true
}
]
}
View Response
HTTP/1.1 201 Created
{
"engagements": [
{
"occurred_on": "2021-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": "2021-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": "2021-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
}
]
}
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:
- GET /admin/api/2021-01/marketing_events.json Retrieves a list of all marketing events
- GET /admin/api/2021-01/marketing_events/count.json Retrieves a count of all marketing events
- GET /admin/api/2021-01/marketing_events/{marketing_event_id}.json Retrieves a single marketing event
- POST /admin/api/2021-01/marketing_events.json Creates a marketing event
- PUT /admin/api/2021-01/marketing_events/{marketing_event_id}.json Updates a marketing event
- DELETE /admin/api/2021-01/marketing_events/{marketing_event_id}.json Deletes a marketing event
- POST /admin/api/2021-01/marketing_events/{marketing_event_id}/engagements.json Creates marketing engagements on a marketing event
MarketingEvent properties
remote_id |
An optional remote identifier for a marketing event. The remote identifier lets Shopify validate engagement data. |
event_type
required |
The type of marketing event. Valid values: NoteIf 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 |
The channel that your marketing event will use. Valid values: |
paid
required |
Whether the event is paid or organic. |
referring_domain |
The destination domain of the marketing event. Required if the |
budget |
The budget of the ad campaign. |
currency |
The currency for the budget. Required if |
budget_type |
The type of the budget. Required if |
started_at
required |
The time when the marketing action was started. |
scheduled_to_end_at |
For events with a duration, the time when the event was scheduled to end. |
ended_at |
For events with a duration, the time when the event actually ended. |
UTM parameters |
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 |
description |
A description of the marketing event. |
manage_url |
A link to manage the marketing event. In most cases, this links to the app that created the event. |
preview_url |
A link to the live version of the event, or to a rendered preview in the app that created it. |
marketed_resources |
A list of the items that were marketed in the marketing event. Includes the
|
Endpoints
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/2021-01/marketing_events.json
View Response
HTTP/1.1 200 OK
{
"marketing_events": [
{
"id": 998730532,
"event_type": "post",
"remote_id": "12345678",
"started_at": "2021-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": []
}
]
}
Retrieve a count all marketing events
GET /admin/api/2021-01/marketing_events/count.json
View Response
HTTP/1.1 200 OK
{
"count": 1
}
Retrieve a single marketing event by its ID
GET /admin/api/2021-01/marketing_events/998730532.json
View Response
HTTP/1.1 200 OK
{
"marketing_event": {
"id": 998730532,
"event_type": "post",
"remote_id": "12345678",
"started_at": "2021-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": []
}
}
Create a marketing event
POST /admin/api/2021-01/marketing_events.json
{
"marketing_event": {
"started_at": "2021-12-15",
"utm_campaign": "Christmas2021",
"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": 1056048233,
"event_type": "ad",
"remote_id": null,
"started_at": "2021-12-15T00:00:00-05:00",
"ended_at": null,
"scheduled_to_end_at": null,
"budget": null,
"currency": null,
"manage_url": null,
"preview_url": null,
"utm_campaign": "Christmas2021",
"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": 1063897334,
"admin_graphql_api_id": "gid://shopify/MarketingEvent/1056048233",
"marketed_resources": []
}
}
Update a marketing event. Can modify only timestamps, remote_id, and budget/currency.
PUT /admin/api/2021-01/marketing_events/998730532.json
{
"marketing_event": {
"id": 998730532,
"remote_id": "1000:2000",
"started_at": "2021-02-02T00:00 +00:00",
"ended_at": "2021-02-03T00:00 +00:00",
"scheduled_to_end_at": "2021-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": "2021-02-01T19:00:00-05:00",
"ended_at": "2021-02-02T19:00:00-05:00",
"scheduled_to_end_at": "2021-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 a marketing event
DELETE /admin/api/2021-01/marketing_events/998730532.json
View Response
HTTP/1.1 200 OK
{
}
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/2021-01/marketing_events/998730532/engagements.json
{
"engagements": [
{
"occurred_on": "2021-01-15",
"views_count": 0,
"clicks_count": 0,
"favorites_count": 0,
"ad_spend": 10.0,
"is_cumulative": true
},
{
"occurred_on": "2021-01-16",
"views_count": 100,
"clicks_count": 50,
"is_cumulative": true
},
{
"occurred_on": "2021-01-17",
"views_count": 200,
"clicks_count": 100,
"is_cumulative": true
}
]
}
View Response
HTTP/1.1 201 Created
{
"engagements": [
{
"occurred_on": "2021-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": "2021-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": "2021-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
}
]
}
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:
- GET /admin/api/2021-04/marketing_events.json Retrieves a list of all marketing events
- GET /admin/api/2021-04/marketing_events/count.json Retrieves a count of all marketing events
- GET /admin/api/2021-04/marketing_events/{marketing_event_id}.json Retrieves a single marketing event
- POST /admin/api/2021-04/marketing_events.json Creates a marketing event
- PUT /admin/api/2021-04/marketing_events/{marketing_event_id}.json Updates a marketing event
- DELETE /admin/api/2021-04/marketing_events/{marketing_event_id}.json Deletes a marketing event
- POST /admin/api/2021-04/marketing_events/{marketing_event_id}/engagements.json Creates marketing engagements on a marketing event
MarketingEvent properties
remote_id |
An optional remote identifier for a marketing event. The remote identifier lets Shopify validate engagement data. |
event_type
required |
The type of marketing event. Valid values: NoteIf 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 |
The channel that your marketing event will use. Valid values: |
paid
required |
Whether the event is paid or organic. |
referring_domain |
The destination domain of the marketing event. Required if the |
budget |
The budget of the ad campaign. |
currency |
The currency for the budget. Required if |
budget_type |
The type of the budget. Required if |
started_at
required |
The time when the marketing action was started. |
scheduled_to_end_at |
For events with a duration, the time when the event was scheduled to end. |
ended_at |
For events with a duration, the time when the event actually ended. |
UTM parameters |
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 |
description |
A description of the marketing event. |
manage_url |
A link to manage the marketing event. In most cases, this links to the app that created the event. |
preview_url |
A link to the live version of the event, or to a rendered preview in the app that created it. |
marketed_resources |
A list of the items that were marketed in the marketing event. Includes the
|
Endpoints
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/2021-04/marketing_events.json
View Response
HTTP/1.1 200 OK
{
"marketing_events": [
{
"id": 998730532,
"event_type": "post",
"remote_id": "12345678",
"started_at": "2021-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": []
}
]
}
Retrieve a count all marketing events
GET /admin/api/2021-04/marketing_events/count.json
View Response
HTTP/1.1 200 OK
{
"count": 1
}
Retrieve a single marketing event by its ID
GET /admin/api/2021-04/marketing_events/998730532.json
View Response
HTTP/1.1 200 OK
{
"marketing_event": {
"id": 998730532,
"event_type": "post",
"remote_id": "12345678",
"started_at": "2021-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": []
}
}
Create a marketing event
POST /admin/api/2021-04/marketing_events.json
{
"marketing_event": {
"started_at": "2021-12-15",
"utm_campaign": "Christmas2021",
"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": 1056048233,
"event_type": "ad",
"remote_id": null,
"started_at": "2021-12-15T00:00:00-05:00",
"ended_at": null,
"scheduled_to_end_at": null,
"budget": null,
"currency": null,
"manage_url": null,
"preview_url": null,
"utm_campaign": "Christmas2021",
"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": 1063897334,
"admin_graphql_api_id": "gid://shopify/MarketingEvent/1056048233",
"marketed_resources": []
}
}
Update a marketing event. Can modify only timestamps, remote_id, and budget/currency.
PUT /admin/api/2021-04/marketing_events/998730532.json
{
"marketing_event": {
"id": 998730532,
"remote_id": "1000:2000",
"started_at": "2021-02-02T00:00 +00:00",
"ended_at": "2021-02-03T00:00 +00:00",
"scheduled_to_end_at": "2021-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": "2021-02-01T19:00:00-05:00",
"ended_at": "2021-02-02T19:00:00-05:00",
"scheduled_to_end_at": "2021-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 a marketing event
DELETE /admin/api/2021-04/marketing_events/998730532.json
View Response
HTTP/1.1 200 OK
{
}
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/2021-04/marketing_events/998730532/engagements.json
{
"engagements": [
{
"occurred_on": "2021-01-15",
"views_count": 0,
"clicks_count": 0,
"favorites_count": 0,
"ad_spend": 10.0,
"is_cumulative": true
},
{
"occurred_on": "2021-01-16",
"views_count": 100,
"clicks_count": 50,
"is_cumulative": true
},
{
"occurred_on": "2021-01-17",
"views_count": 200,
"clicks_count": 100,
"is_cumulative": true
}
]
}
View Response
HTTP/1.1 201 Created
{
"engagements": [
{
"occurred_on": "2021-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": "2021-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": "2021-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
}
]
}
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:
- GET /admin/api/unstable/marketing_events.json Retrieves a list of all marketing events
- GET /admin/api/unstable/marketing_events/count.json Retrieves a count of all marketing events
- GET /admin/api/unstable/marketing_events/{marketing_event_id}.json Retrieves a single marketing event
- POST /admin/api/unstable/marketing_events.json Creates a marketing event
- PUT /admin/api/unstable/marketing_events/{marketing_event_id}.json Updates a marketing event
- DELETE /admin/api/unstable/marketing_events/{marketing_event_id}.json Deletes a marketing event
- POST /admin/api/unstable/marketing_events/{marketing_event_id}/engagements.json Creates marketing engagements on a marketing event
MarketingEvent properties
remote_id |
An optional remote identifier for a marketing event. The remote identifier lets Shopify validate engagement data. |
event_type
required |
The type of marketing event. Valid values: NoteIf 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 |
The channel that your marketing event will use. Valid values: |
paid
required |
Whether the event is paid or organic. |
referring_domain |
The destination domain of the marketing event. Required if the |
budget |
The budget of the ad campaign. |
currency |
The currency for the budget. Required if |
budget_type |
The type of the budget. Required if |
started_at
required |
The time when the marketing action was started. |
scheduled_to_end_at |
For events with a duration, the time when the event was scheduled to end. |
ended_at |
For events with a duration, the time when the event actually ended. |
UTM parameters |
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 |
description |
A description of the marketing event. |
manage_url |
A link to manage the marketing event. In most cases, this links to the app that created the event. |
preview_url |
A link to the live version of the event, or to a rendered preview in the app that created it. |
marketed_resources |
A list of the items that were marketed in the marketing event. Includes the
|
Endpoints
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/unstable/marketing_events.json
View Response
HTTP/1.1 200 OK
{
"marketing_events": [
{
"id": 998730532,
"event_type": "post",
"remote_id": "12345678",
"started_at": "2021-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": []
}
]
}
Retrieve a count all marketing events
GET /admin/api/unstable/marketing_events/count.json
View Response
HTTP/1.1 200 OK
{
"count": 1
}
Retrieve a single marketing event by its ID
GET /admin/api/unstable/marketing_events/998730532.json
View Response
HTTP/1.1 200 OK
{
"marketing_event": {
"id": 998730532,
"event_type": "post",
"remote_id": "12345678",
"started_at": "2021-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": []
}
}
Create a marketing event
POST /admin/api/unstable/marketing_events.json
{
"marketing_event": {
"started_at": "2021-12-15",
"utm_campaign": "Christmas2021",
"utm_source": "facebook",
"utm_medium": "cpc",
"event_type": "ad",
"referring_domain": "facebook.com",
"marketing_channel": "social",
"paid": true
}
}
Vi