--- title: marketing_engagements description: >- Reference for the ShopifyQL `marketing_engagements` table. Every metric and dimension, paired with worked example queries. api_version: 2026-07 source_url: html: >- https://shopify.dev/docs/api/shopifyql/latest/schemas/marketing/marketing_engagements md: >- https://shopify.dev/docs/api/shopifyql/latest/schemas/marketing/marketing_engagements.md api_name: shopifyql --- # marketing\_​engagements The `marketing_engagements` [schema](https://shopify.dev/docs/api/shopifyql/latest/schemas) 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. ### Use cases * **Spend and return**: Group [`engagements_ad_spend`](#marketingengagementsmetric-propertydetail-engagementsadspend) and [`engagements_total_sales`](#marketingengagementsmetric-propertydetail-engagementstotalsales) by [`marketing_api_client`](#marketingengagementsdimension-propertydetail-marketingapiclient) to see which channels cost the most and which report the most revenue back. * **Engagement funnel**: Compare [`engagements_impressions`](#marketingengagementsmetric-propertydetail-engagementsimpressions), [`engagements_clicks`](#marketingengagementsmetric-propertydetail-engagementsclicks), and [`engagements_unique_clicks`](#marketingengagementsmetric-propertydetail-engagementsuniqueclicks) for a marketing event to see how reach narrows to engaged clicks. * **Messaging health**: Track [`engagements_sends`](#marketingengagementsmetric-propertydetail-engagementssends) against [`engagements_fails`](#marketingengagementsmetric-propertydetail-engagementsfails), [`engagements_complaints`](#marketingengagementsmetric-propertydetail-engagementscomplaints), and [`engagements_unsubscribes`](#marketingengagementsmetric-propertydetail-engagementsunsubscribes) to monitor deliverability and list health for email and SMS channels. * **New vs. returning**: Show [`engagements_orders`](#marketingengagementsmetric-propertydetail-engagementsorders) alongside [`engagements_first_time_customers`](#marketingengagementsmetric-propertydetail-engagementsfirsttimecustomers) and [`engagements_returning_customers`](#marketingengagementsmetric-propertydetail-engagementsreturningcustomers) to see whether a channel reports winning new or repeat buyers. Examples ### 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 ```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 ```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 ```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 ```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 ``` *** ## Metrics 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`. * **engagements\_​ad\_​spend** **MONEY** Amounts are in your store's currency. * **engagements\_​clicks** **INTEGER** Number of clicks on marketing content, including multiple clicks from the same person, as reported by the marketing channel * **engagements\_​complaints** **INTEGER** Number of emails marked as spam, as reported by the marketing channel * **engagements\_​fails** **INTEGER** Number of failed message deliveries, as reported by the marketing channel * **engagements\_​first\_​time\_​customers** **FLOAT** Number of first-time customers from marketing campaigns, as reported by the marketing channel * **engagements\_​impressions** **INTEGER** Number of times marketing content was displayed, as reported by the marketing channel * **engagements\_​orders** **FLOAT** Number of orders, as reported by the marketing channel * **engagements\_​returning\_​customers** **FLOAT** Number of returning customers from marketing campaigns, as reported by the marketing channel * **engagements\_​sends** **INTEGER** Number of marketing messages you've sent, as reported by the marketing channel * **engagements\_​total\_​sales** **MONEY** Amounts are in your store's currency. * **engagements\_​unique\_​clicks** **INTEGER** Number of unique people who clicked on marketing content, as reported by the marketing channel * **engagements\_​unique\_​views** **INTEGER** Number of times a unique individual viewed the marketing content, as reported by the marketing channel * **engagements\_​unsubscribes** **INTEGER** 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. ```ts ``` ### INTEGER A whole number without decimal places, used for counts, quantities, and other discrete numeric values. ```ts ``` ### FLOAT A floating-point number used for measurements, rates, and other continuous numeric values. ```ts ``` *** ## Dimensions 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`. * **marketing\_​api\_​client** **IDENTITY** Unique identifier in Shopify for the API client * **marketing\_​event\_​id** **IDENTITY** Unique identifier in Shopify for the marketing event * **shop\_​id** **IDENTITY** The unique Shopify identifier for your store. Use [`shop_id`](#marketingengagementsdimension-propertydetail-shopid) with [`shop_name`](#marketingengagementsdimension-propertydetail-shopname) to show readable store labels. * **channel\_​handle** **STRING** Name of the marketing channel or platform that drove the marketing engagement * **created\_​at** **TIMESTAMP** Date and time the marketing activity was created * **ended\_​at** **TIMESTAMP** Date and time the marketing activity ended * **manage\_​url** **STRING** URL for managing the marketing activity in the external marketing platform * **marketing\_​activity\_​channel** **STRING** The marketing channel category for the activity, such as social media, email, or search. * **marketing\_​activity\_​id** **IDENTITY** The unique Shopify identifier for the marketing activity. Use [`marketing_activity_id`](#marketingengagementsdimension-propertydetail-marketingactivityid) with [`marketing_activity_title`](#marketingengagementsdimension-propertydetail-marketingactivitytitle) to show readable activity labels. * **marketing\_​activity\_​status** **STRING** Current status of the marketing activity (such as Active or Paused) * **marketing\_​activity\_​title** **STRING** Name of the marketing activity * **marketing\_​automation\_​id** **IDENTITY** Unique ID that Shopify uses to identify the marketing automation * **marketing\_​budget** **MONEY** The budget allocated to the marketing activity, in your store's currency. * **marketing\_​budget\_​type** **STRING** The type of budget allocated to the marketing activity, such as daily, lifetime, or monthly. * **marketing\_​delivery\_​channel** **STRING** Channel through which the marketing activity is delivered * **marketing\_​platform** **STRING** The marketing platform that created the marketing activity, shown as a platform name. * **preview\_​url** **STRING** URL for previewing the marketing activity * **remote\_​id** **STRING** External identifier of the marketing activity on the marketing channel * **scheduled\_​to\_​end\_​at** **TIMESTAMP** Date and time the marketing activity is scheduled to end * **started\_​at** **TIMESTAMP** Date and time the marketing activity became active * **utm\_​campaign** **STRING** The campaign name from the tracking parameter on the marketing link. Values are the campaign names you set in your links. * **utm\_​content** **STRING** 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. * **utm\_​medium** **STRING** The tracking value for the type of marketing channel. Values are terms such as email, social, and paid search. * **utm\_​source** **STRING** The tracking value for where the traffic came from. Values are sources such as Google, Facebook, and newsletter. * **utm\_​term** **STRING** The tracking value for paid search keywords. Values are the keyword terms you set in your links. * **shop\_​name** **STRING** Name of your store ### IDENTITY A unique identifier for a Shopify resource such as a customer, product, or order. ```ts ``` ### STRING A sequence of characters representing text data. ```ts ``` ### TIMESTAMP A full-precision timestamp including date and time. ```ts ``` *** ## Related schemas * [`campaign_sales`](https://shopify.dev/docs/api/shopifyql/latest/schemas/marketing/campaign_sales): Shopify-attributed order revenue for your marketing, when you want attributed results rather than channel-reported numbers. * [`campaign_sessions`](https://shopify.dev/docs/api/shopifyql/latest/schemas/marketing/campaign_sessions): On-store session and funnel behavior for campaign traffic, rather than channel-reported engagement. * [`campaign_products`](https://shopify.dev/docs/api/shopifyql/latest/schemas/marketing/campaign_products): Product-level attribution for the same marketing activity when you want unit volume per product. ***