Marketing Event

Marketing events represent actions taken by your app, on behalf of a merchant, to market products, collections, discounts, pages, blog posts, the homepage, etc.

Marketing events should represent actions that target multiple potential customers, because they’re intended to aggregate traffic, etc. For example, if your app sends emails to customers, do not create a different marketing event for each individual who is emailed; create a marketing event for a related set of emails.

It’s okay for marketing events to be long-lived. For some apps, there might only be a single marketing event that lasts for the entire duration of the app’s involvement with the shop.

What you can do with Marketing Event

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

Marketing Event properties

remote_id (recommended)
"remote_id": "123abc"

An optional remote identifier for a marketing event. We recommend including a remote identifier for social marketing posts so that Shopify can validate engagement data.

event_type (required)
"event_type": "ad"

The specific type of marketing event. Must be one of the allowed values ('ad', 'post', 'message', 'retargeting', 'sem', 'transactional', 'affiliate', 'loyalty', 'newsletter', 'abandoned_cart', 'receipt').

Note

If there are values that you’d like to use for event_type that are not in the list above, please contact us. 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"

A broader marketing event type that is focused only on the channel. Must be one of the allowed values ("search", "display", "social", "email", "referral").

referring_domain (required)
"referring_domain": "facebook.com"

The destination domain of the marketing event. Required unless marketing_channel is one of email/referral/display.

budget (optional)
"budget": 10.75

The budget of the ad campaign.

currency (required if budget is specified)
"currency": "USD"

The currency for the budget.

budget_type (required if budget is specified)
"budget_type": "lifetime"

The type of the budget; must be either “daily” or “lifetime”.

started_at (required)
"started_at": "2017-01-15T11:56:18-04:00"

The timestamp when the marketing action was started, or when the email was sent, or when the Facebook post was made live, etc.

scheduled_to_end_at (optional)
"scheduled_to_end_at": "2017-01-22T11:56:18-04:00"

For events with a duration, when the event was supposed to end.

ended_at (optional)
"ended_at": "2017-01-20T11:56:18-04:00"

For events with a duration, when the event actually ended. This may differ from “scheduled_to_end_at”, if the ad was stopped early, etc.

UTM parameters (recommended)
"utm_campaign": "CanadaDay2017"
"utm_source": "facebook"
"utm_medium": "cpc"

The UTM parameters used in the links provided in the marketing event. These are optional, but we won’t be able to do any automatic association of Online Store traffic, or order attribution if these values are not provided. The minimum set that should be provided is utm_campaign, utm_source, and utm_medium – all of these must match, in order to do traffic or order attribution. Note that the values should not be url encoded.

description (recommended)
"description": "Facebook carousel ad"

A human-readable description of the marketing event. (e.g. "Thanksgiving newsletter 2017", "Facebook carousel ad", etc.).

manage_url (optional)
"manage_url": "https://mymarketingapp.com/ad/1234"

A link to manage the marketing event, generally in the Shopify app’s interface.

preview_url (optional)
"preview_url": "https://www.facebook.com/123456/"

A link to view the live version of the post/ad, or to view a rendered preview of the post/ad/email in the Shopify app.

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

A list of the items that were marketed in the marketing event. It’s a list of dictionaries with type keys and id keys. Valid values for type are:

  • product
  • collection
  • price_rule
  • discount (will be replaced by price_rule after April 20, 2017)
  • page
  • article
  • shop
All types, other than shop, also require an id.

Endpoints

GET /admin/marketing_events.json
Get a list of all marketing events
limit

Amount of results

(default: 50) (maximum: 250)
offset

Number of marketing events to skip

Get all marketing events

GET /admin/marketing_events.json
View Response
HTTP/1.1 200 OK
{
  "marketing_events": [
    {
      "id": 998730532,
      "event_target": "",
      "event_type": "post",
      "remote_id": "12345678",
      "started_at": "2017-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",
      "utm_content": null,
      "utm_term": null,
      "budget_type": "daily",
      "description": null,
      "marketing_channel": "social",
      "paid": false,
      "referring_domain": "facebook.com",
      "breadcrumb_id": null,
      "marketed_resources": [
      ]
    }
  ]
}
GET /admin/marketing_events/count.json
Get a count of all marketing events

Count all marketing events

GET /admin/marketing_events/count.json
View Response
HTTP/1.1 200 OK
{
  "count": 1
}
GET /admin/marketing_events/998730532.json
Show marketing event

Show marketing event

GET /admin/marketing_events/#{id}.json
View Response
HTTP/1.1 200 OK
{
  "marketing_event": {
    "id": 998730532,
    "event_target": "",
    "event_type": "post",
    "remote_id": "12345678",
    "started_at": "2017-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",
    "utm_content": null,
    "utm_term": null,
    "budget_type": "daily",
    "description": null,
    "marketing_channel": "social",
    "paid": false,
    "referring_domain": "facebook.com",
    "breadcrumb_id": null,
    "marketed_resources": [
    ]
  }
}
POST /admin/marketing_events.json
Create a marketing event

Create a marketing event

POST /admin/marketing_events.json
{
  "marketing_event": {
    "started_at": "2017-12-15",
    "utm_campaign": "Christmas2017",
    "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_target": "",
    "event_type": "ad",
    "remote_id": null,
    "started_at": "2017-12-14T19:00:00-05:00",
    "ended_at": null,
    "scheduled_to_end_at": null,
    "budget": null,
    "currency": null,
    "manage_url": null,
    "preview_url": null,
    "utm_campaign": "Christmas2017",
    "utm_source": "facebook",
    "utm_medium": "cpc",
    "utm_content": null,
    "utm_term": null,
    "budget_type": null,
    "description": null,
    "marketing_channel": "social",
    "paid": true,
    "referring_domain": "facebook.com",
    "breadcrumb_id": null,
    "marketed_resources": [
    ]
  }
}
PUT /admin/marketing_events/998730532.json
Update a marketing event (can only modify timestamps, remote_id, and budget/currency)

Update the marketing event

PUT /admin/marketing_events/#{id}.json
{
  "marketing_event": {
    "id": 998730532,
    "remote_id": "1000:2000",
    "started_at": "2017-02-02T00:00 +00:00",
    "ended_at": "2017-02-03T00:00 +00:00",
    "scheduled_to_end_at": "2017-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_target": "",
    "event_type": "post",
    "remote_id": "1000:2000",
    "started_at": "2017-02-01T19:00:00-05:00",
    "ended_at": "2017-02-02T19:00:00-05:00",
    "scheduled_to_end_at": "2017-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",
    "utm_content": null,
    "utm_term": null,
    "budget_type": "daily",
    "description": null,
    "marketing_channel": "social",
    "paid": false,
    "referring_domain": "facebook.com",
    "breadcrumb_id": null,
    "marketed_resources": [
    ]
  }
}
DELETE /admin/marketing_events/998730532.json
Delete a marketing event

Delete a marketing event

DELETE /admin/marketing_events/#{id}.json
View Response
HTTP/1.1 200 OK
{}
POST /admin/marketing_events/998730532/engagements.json

Engagements on marketing events:

  • represent customer activity taken on the marketing event before customers reach the shop’s website
  • can be thought of as the top-level of the conversion funnel
  • are aggregated on a daily basis. However, the data can be sent more often than once a day if the information is available. An engagement with the same value for occurred_on will overwrite any previous engagement with the same date.
  • 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. Send whatever data is relevant for the type of marketing event
occurred_on (required)

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

impressions_count (optional)

The total number of impressions for the day. “Impressions” are considered to be a lightweight “view”, like a Facebook post that appears in the timeline, or a Pinterest pin that gets rendered in the list view, or the number of emails sent.

views_count (optional)

The total number of views for the day. A view is considered to be a more heavyweight view, like stopping to read a Facebook post, or viewing a closeup of a Pinterest pin, or opening and reading an email.

clicks_count (optional)

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

shares_count (optional)

The total number of shares/reposts for the day.

favorites_count (optional)

The total number of favorites/likes/hearts for the day.

comments_count (optional)

The total number of comments/replies for the day.

ad_spend (optional)

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

is_cumulative (optional)

A boolean field to specify if engagements are reported as their lifetime values rather than daily totals.

Create or Update a marketing engagement

POST /admin/marketing_events/#{id}/engagements.json
{
  "engagements": [
    {
      "occurred_on": "2017-01-15",
      "views_count": 0,
      "clicks_count": 0,
      "favorites_count": 0,
      "ad_spend": 10.0,
      "is_cumulative": true
    },
    {
      "occurred_on": "2017-01-16",
      "views_count": 100,
      "clicks_count": 50,
      "is_cumulative": true
    },
    {
      "occurred_on": "2017-01-17",
      "views_count": 200,
      "clicks_count": 100,
      "is_cumulative": true
    }
  ]
}
View Response
HTTP/1.1 201 Created
{
  "engagements": [
    {
      "occurred_on": "2017-01-15",
      "views_count": 0,
      "impressions_count": null,
      "clicks_count": 0,
      "favorites_count": 0,
      "comments_count": null,
      "shares_count": null,
      "ad_spend": "10.00",
      "is_cumulative": true
    },
    {
      "occurred_on": "2017-01-16",
      "views_count": 100,
      "impressions_count": null,
      "clicks_count": 50,
      "favorites_count": null,
      "comments_count": null,
      "shares_count": null,
      "ad_spend": null,
      "is_cumulative": true
    },
    {
      "occurred_on": "2017-01-17",
      "views_count": 200,
      "impressions_count": null,
      "clicks_count": 100,
      "favorites_count": null,
      "comments_count": null,
      "shares_count": null,
      "ad_spend": null,
      "is_cumulative": true
    }
  ]
}