--- title: marketing_engagements description: >- Reference for the ShopifyQL `marketing_engagements` schema. Every metric and dimension, paired with worked example queries. api_version: 2026-10 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 * #### Compare channel spend with reported sales this quarter ##### Description Rank the top 50 marketing channels this quarter by \`engagements\_total\_sales\`, with \`engagements\_ad\_spend\` alongside to show what each channel costs against what it reports back. 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 ``` * #### Rank marketing channels by unique clicks last month ##### 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 ``` * #### Track weekly marketing sales this quarter ##### 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 ``` * #### Track weekly messaging engagement this quarter ##### Description Track weekly \`engagements\_unique\_clicks\` and \`engagements\_unique\_views\` across this quarter, each week compared to the quarter before. This example uses \[\`COMPARE TO previous\_period\`]\(/docs/api/shopifyql/latest/syntax/compare-to) to derive the comparison window from the reporting range, so its length always matches the period you query. ##### 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 ``` *** ## 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 Currency amount such as a price, revenue, cost, or discount ```ts ``` ### INTEGER Whole number without decimal places, used for counts and quantities ```ts ``` ### FLOAT Number stored as an approximation, used for measurements and rates ```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\_​campaign** **STRING** The campaign-level detail for the engagement: the marketing activity title when available, otherwise the UTM campaign. * **marketing\_​channel** **STRING** The normalized marketing channel for the engagement. Integrated ad activities use their marketing product, such as Google Ads or Meta Ads. Other activities use the integration's app name. * **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. * **traffic\_​type** **STRING** Type of traffic associated with the marketing engagement * **activation\_​platform** **STRING** Marketing platform that activated this marketing activity * **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\_​app\_​name** **STRING** The app that created 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 Unique identifier for a Shopify resource such as a customer or order ```ts ``` ### STRING Text made of letters, numbers, or symbols ```ts ``` ### TIMESTAMP Date and time recorded at the most detailed available level ```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. ***