Marketing Events API

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.

Getting Started

  1. Request the “write_marketing_events” authorization scope.

  2. Send us marketing events. Make sure to store the marketing event id, for use with the engagement API.

  3. Send us engagement details for the marketing event.

Marketing events

You can use the marketing_events endpoint to create a marketing event that will be returned with a unique id. You can use the id to read, update and delete specific marketing events.

Sample Request

You can send the following data in the body of a POST request to the /admin/marketing_events.json endpoint to create a marketing event.

{
  "marketing_event": {
    "event_type": "ad",
    "budget": "10.00",
    "currency": "USD",
    "budget_type": "lifetime",
    "utm_campaign": "CanadaDay2016",
    "utm_source": "facebook",
    "utm_medium": "cpc",
    "manage_url": "https://mymarketingapp.com/ad/1234",
    "preview_url": "https://www.facebook.com/123456/",
    "started_at": "2016-06-20T11:56:18-04:00",
    "ended_at": "2016-06-26T11:56:18-04:00",
    "scheduled_to_end_at": "2016-06-27T11:56:18-04:00",
    "description": "Facebook carousel ad",
    "marketing_channel": "social",
    "paid": "true",
    "referring_domain": "facebook.com",
    "marketed_resources": [
      {
        "type": "homepage"
      },
      {
        "type": "product",
        "id": 12345
      }
    ]
  }
}

Marketing events properties

For a complete list of marketing events properties, see the API Reference.

Engagements

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.

Note

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.

Sample Request

You can send the following data in the body of a POST request to the /admin/marketing_events/1/engagements.json endpoint to create marketing engagements.

{
  "engagements": [
    {
      "occurred_on": "2016-06-29",
      "impressions_count": 100,
      "clicks_count": 50,
      "shares_count": 10,
      "favorites_count": 20,
      "comments_count": 2,
      "ad_spend": "7.00",
      "is_cumulative": false
    },
    {
      "occurred_on": "2016-06-30",
      "impressions_count": 200,
      "clicks_count": 100,
      "shares_count": 20,
      "favorites_count": 40,
      "comments_count": 4,
      "ad_spend": "6.50",
      "is_cumulative": true
    }
  ]
}

Engagement properties

For a complete list of engagement properties, see the API Reference.