Choose a version:

marketing_engagements

The marketing_engagements schema captures engagement metrics for your marketing activity as reported by each marketing channel or app, including ad spend, impressions, clicks, sends, orders, and sales. It's the channel's own view of performance, keyed by marketing event and API client, rather than Shopify's attributed results.

Anchor to Use casesUse cases

Spend and return: Group engagements_ad_spend and engagements_total_sales by marketing_api_client to see which channels cost the most and which report the most revenue back.
Engagement funnel: Compare engagements_impressions, engagements_clicks, and engagements_unique_clicks for a marketing event to see how reach narrows to engaged clicks.
Messaging health: Track engagements_sends against engagements_fails, engagements_complaints, and engagements_unsubscribes to monitor deliverability and list health for email and SMS channels.
New vs. returning: Show engagements_orders alongside engagements_first_time_customers and engagements_returning_customers to see whether a channel reports winning new or repeat buyers.

Examples

ShopifyQL

View in adminView query results in the ShopifyQL editor

FROM marketing_engagements

SHOW engagements_total_sales, engagements_orders, engagements_ad_spend,

engagements_clicks, engagements_impressions

GROUP BY marketing_api_client WITH TOTALS

DURING this_quarter

COMPARE TO previous_period

ORDER BY engagements_total_sales DESC

LIMIT 50

VISUALIZE engagements_total_sales TYPE horizontal_bar

Examples

Description

Rank the top 50 marketing channels this quarter by `engagements_total_sales`. This example uses [`COMPARE TO previous_period`](/docs/api/shopifyql/latest/syntax/compare-to) to add a prior-quarter benchmark, channel by channel.

ShopifyQL

FROM marketing_engagements
  SHOW engagements_total_sales, engagements_orders, engagements_ad_spend,
    engagements_clicks, engagements_impressions
  GROUP BY marketing_api_client WITH TOTALS
  DURING this_quarter
  COMPARE TO previous_period
  ORDER BY engagements_total_sales DESC
  LIMIT 50
VISUALIZE engagements_total_sales TYPE horizontal_bar

Description

Track weekly `engagements_unique_clicks` and seven other engagement metrics through this quarter. This example uses [`PERCENT_CHANGE`](/docs/api/shopifyql/latest/syntax/with#percent-change-columns) against the previous quarter to flag quarter-over-quarter shifts in each metric.

ShopifyQL

FROM marketing_engagements
  SHOW engagements_sends, engagements_unique_views, engagements_unique_clicks,
    engagements_unsubscribes, engagements_complaints, engagements_fails,
    engagements_first_time_customers, engagements_returning_customers
  TIMESERIES week WITH PERCENT_CHANGE
  DURING this_quarter
  COMPARE TO previous_period
VISUALIZE engagements_unique_clicks TYPE line

Description
Track weekly `engagements_total_sales`, `engagements_orders`, and `engagements_ad_spend` across this quarter. This example uses [`WITH TOTALS`](/docs/api/shopifyql/latest/syntax/with#total-columns) to add a quarter-to-date total beside the weekly rows.
ShopifyQL
```
FROM marketing_engagements
  SHOW engagements_total_sales, engagements_orders, engagements_ad_spend
  TIMESERIES week WITH TOTALS
  DURING this_quarter
  ORDER BY week ASC
VISUALIZE engagements_total_sales TYPE line
```
Description
Rank the top 10 marketing channels last month by `engagements_unique_clicks`, grouped by `marketing_api_client`. This example uses [`GROUP BY`](/docs/api/shopifyql/latest/syntax/group-by) `marketing_api_client` to collapse engagements into one row per channel before `LIMIT 10` trims the result.
ShopifyQL
```
FROM marketing_engagements
  SHOW engagements_unique_clicks
  GROUP BY marketing_api_client WITH TOTALS
  DURING last_month
  ORDER BY engagements_unique_clicks DESC
  LIMIT 10
VISUALIZE engagements_unique_clicks TYPE horizontal_bar
```

Anchor to MetricsMetrics

Counts and calculations that let you track key business indicators. Metrics show up as the columns when queried.

Metrics you can use when querying FROM marketing_engagements.

Anchor to engagements_ad_spend engagements_ad_spend: Amounts are in your store's currency.
Anchor to engagements_clicks engagements_clicks: Number of clicks on marketing content, including multiple clicks from the same person, as reported by the marketing channel
Anchor to engagements_complaints engagements_complaints: Number of emails marked as spam, as reported by the marketing channel
Anchor to engagements_fails engagements_fails: Number of failed message deliveries, as reported by the marketing channel
Anchor to engagements_first_time_customers engagements_first_time_customers: Number of first-time customers from marketing campaigns, as reported by the marketing channel
Anchor to engagements_impressions engagements_impressions: Number of times marketing content was displayed, as reported by the marketing channel
Anchor to engagements_orders engagements_orders: Number of orders, as reported by the marketing channel
Anchor to engagements_returning_customers engagements_returning_customers: Number of returning customers from marketing campaigns, as reported by the marketing channel
Anchor to engagements_sends engagements_sends: Number of marketing messages you've sent, as reported by the marketing channel
Anchor to engagements_total_sales engagements_total_sales: Amounts are in your store's currency.
Anchor to engagements_unique_clicks engagements_unique_clicks: Number of unique people who clicked on marketing content, as reported by the marketing channel
Anchor to engagements_unique_views engagements_unique_views: Number of times a unique individual viewed the marketing content, as reported by the marketing channel
Anchor to engagements_unsubscribes engagements_unsubscribes: Number of unsubscriptions from marketing messages, as reported by the marketing channel

MONEY

A monetary amount representing currency values such as prices, revenue, costs, and discounts.

INTEGER

A whole number without decimal places, used for counts, quantities, and other discrete numeric values.

FLOAT

A floating-point number used for measurements, rates, and other continuous numeric values.

Anchor to DimensionsDimensions

Attributes of your data that let you look more granularly at aspects of the data. Group and filter by dimensions to shape the rows your query returns.

Dimensions you can use when querying FROM marketing_engagements.

Anchor to marketing_api_client marketing_api_client: Unique identifier in Shopify for the API client
Anchor to marketing_event_id marketing_event_id: Unique identifier in Shopify for the marketing event
Anchor to shop_id shop_id: The unique Shopify identifier for your store. Use shop_id with shop_name to show readable store labels.
Anchor to channel_handle channel_handle: Name of the marketing channel or platform that drove the marketing engagement
Anchor to created_at created_at: Date and time the marketing activity was created
Anchor to ended_at ended_at: Date and time the marketing activity ended
Anchor to manage_url manage_url: URL for managing the marketing activity in the external marketing platform
Anchor to marketing_activity_channel marketing_activity_channel: The marketing channel category for the activity, such as social media, email, or search.
Anchor to marketing_activity_id marketing_activity_id: The unique Shopify identifier for the marketing activity. Use marketing_activity_id with marketing_activity_title to show readable activity labels.
Anchor to marketing_activity_status marketing_activity_status: Current status of the marketing activity (such as Active or Paused)
Anchor to marketing_activity_title marketing_activity_title: Name of the marketing activity
Anchor to marketing_automation_id marketing_automation_id: Unique ID that Shopify uses to identify the marketing automation
Anchor to marketing_budget marketing_budget: The budget allocated to the marketing activity, in your store's currency.
Anchor to marketing_budget_type marketing_budget_type: The type of budget allocated to the marketing activity, such as daily, lifetime, or monthly.
Anchor to marketing_delivery_channel marketing_delivery_channel: Channel through which the marketing activity is delivered
Anchor to marketing_platform marketing_platform: The marketing platform that created the marketing activity, shown as a platform name.
Anchor to preview_url preview_url: URL for previewing the marketing activity
Anchor to remote_id remote_id: External identifier of the marketing activity on the marketing channel
Anchor to scheduled_to_end_at scheduled_to_end_at: Date and time the marketing activity is scheduled to end
Anchor to started_at started_at: Date and time the marketing activity became active
Anchor to utm_campaign utm_campaign: The campaign name from the tracking parameter on the marketing link. Values are the campaign names you set in your links.
Anchor to utm_content utm_content: The tracking value used to tell different versions of the same ad or message apart. Values are the content labels you set in your links.
Anchor to utm_medium utm_medium: The tracking value for the type of marketing channel. Values are terms such as email, social, and paid search.
Anchor to utm_source utm_source: The tracking value for where the traffic came from. Values are sources such as Google, Facebook, and newsletter.
Anchor to utm_term utm_term: The tracking value for paid search keywords. Values are the keyword terms you set in your links.
Anchor to shop_name shop_name: Name of your store

IDENTITY

A unique identifier for a Shopify resource such as a customer, product, or order.

STRING

A sequence of characters representing text data.

TIMESTAMP

A full-precision timestamp including date and time.

Anchor to Related schemasRelated schemas

campaign_sales: Shopify-attributed order revenue for your marketing, when you want attributed results rather than channel-reported numbers.
campaign_sessions: On-store session and funnel behavior for campaign traffic, rather than channel-reported engagement.
campaign_products: Product-level attribution for the same marketing activity when you want unit volume per product.

Was this page helpful?