create_marketing_engagement
Create a marketing engagement to track customer interactions for a marketing activity or channel, recording clicks, impressions, conversions, sales, and orders to measure performance.
Instructions
Create a marketing engagement for a marketing activity or channel. Tracks customer interactions like clicks, impressions, conversions, sales, and orders. Requires write_marketing_events scope.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| orders | No | Number of orders generated | |
| remoteId | No | A custom unique identifier for the marketing activity. Either this or marketingActivityId should be set for activity-level engagements. | |
| utcOffset | Yes | The UTC offset for the time zone in which the metrics are being reported (format: '+HH:MM' or '-HH:MM', e.g., '-07:00') | |
| failsCount | No | Total number of fails (bounced emails/messages) | |
| occurredOn | Yes | The calendar date for which the metrics are being reported (ISO 8601 format, e.g., '2018-06-29') | |
| sendsCount | No | Total number of marketing emails or messages sent | |
| viewsCount | No | Total number of views (email opens, video plays) | |
| clicksCount | No | Total number of interactions/clicks on the marketing content | |
| salesAmount | No | Amount of sales generated from the marketing content | |
| sharesCount | No | Total number of times content was shared or reposted | |
| isCumulative | Yes | Whether metrics have been aggregated from the first day of reporting up to occurredOn (true) or aggregated over a single day (false). Non-cumulative is preferred. | |
| adSpendAmount | No | The total ad spend amount for the marketing content | |
| channelHandle | No | The unique string identifier of the channel for channel-level engagements. Set when providing channel-level engagements only. | |
| commentsCount | No | Total number of comments on the marketing content | |
| sessionsCount | No | Number of online store sessions generated | |
| favoritesCount | No | Total number of favorites, likes, saves, or bookmarks | |
| complaintsCount | No | Total number of complaints (spam reports, dislikes) | |
| impressionsCount | No | Total number of times content was displayed | |
| uniqueViewsCount | No | Total number of unique users who saw the content | |
| salesCurrencyCode | No | Currency code for sales amount | |
| uniqueClicksCount | No | Total number of unique clicks | |
| unsubscribesCount | No | Total number of unsubscribes/unfollows | |
| firstTimeCustomers | No | Number of first-time customers who placed orders | |
| returningCustomers | No | Number of returning customers who placed orders | |
| adSpendCurrencyCode | No | The currency code for ad spend (e.g., 'USD', 'CAD', 'EUR') | |
| marketingActivityId | No | The ID of the marketing activity for activity-level engagements (e.g., 'gid://shopify/MarketingActivity/123456'). Either this or remoteId should be set for activity-level, not both. |