# marketingEngagementCreate - admin-graphql - MUTATION Version: 2025-01 ## Description Creates a new marketing engagement for a marketing activity or a marketing channel. ### Access Scopes `write_marketing_events` access scope. ## Arguments * [channelHandle](/docs/api/admin-graphql/2025-01/scalars/String): String - The unique string identifier of the channel to which the engagement metrics are being provided. This should be set when and only when providing channel-level engagements. This should be nil when providing activity-level engagements. For the correct handle for your channel, contact your partner manager. * [marketingActivityId](/docs/api/admin-graphql/2025-01/scalars/ID): ID - The identifier of the marketing activity for which the engagement metrics are being provided. This or the remoteId should be set when and only when providing activity-level engagements. This should be nil when providing channel-level engagements. * [marketingEngagement](/docs/api/admin-graphql/2025-01/input-objects/MarketingEngagementInput): MarketingEngagementInput! - The marketing engagement's attributes. * [remoteId](/docs/api/admin-graphql/2025-01/scalars/String): String - The ID of an activity that's hosted outside of Shopify. This or the marketingActivityId should be set when and only when providing activity-level engagements. This should be nil when providing channel-level engagements. ## Returns * [marketingEngagement](/docs/api/admin-graphql/2025-01/objects/MarketingEngagement): MarketingEngagement The marketing engagement that was created. This represents customer activity taken on a marketing activity or a marketing channel. * [userErrors](/docs/api/admin-graphql/2025-01/objects/MarketingActivityUserError): MarketingActivityUserError! The list of errors that occurred from executing the mutation. ## Examples ### Create activity-level engagement for a marketing activity ID Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2025-01/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation M($marketingEngagement: MarketingEngagementInput!, $marketingActivityId: ID, $channelHandle: String, $remoteId: String) { marketingEngagementCreate(marketingEngagement: $marketingEngagement, marketingActivityId: $marketingActivityId, channelHandle: $channelHandle, remoteId: $remoteId) { marketingEngagement { occurredOn utcOffset isCumulative adSpend { amount currencyCode } clicksCount impressionsCount commentsCount favoritesCount unsubscribesCount complaintsCount failsCount sendsCount uniqueViewsCount uniqueClicksCount sharesCount viewsCount sessionsCount sales { amount currencyCode } orders firstTimeCustomers returningCustomers marketingActivity { id } channelHandle } userErrors { field message } } }\",\n \"variables\": {\n \"marketingEngagement\": {\n \"occurredOn\": \"2018-06-29\",\n \"utcOffset\": \"-07:00\",\n \"isCumulative\": false,\n \"adSpend\": {\n \"currencyCode\": \"CAD\",\n \"amount\": \"19.90\"\n },\n \"impressionsCount\": 100,\n \"clicksCount\": 40,\n \"commentsCount\": 1,\n \"unsubscribesCount\": 1,\n \"complaintsCount\": 1,\n \"failsCount\": 1,\n \"sendsCount\": 1,\n \"uniqueViewsCount\": 1,\n \"uniqueClicksCount\": 1,\n \"sharesCount\": 5,\n \"viewsCount\": 10,\n \"favoritesCount\": 0,\n \"sessionsCount\": 40,\n \"sales\": {\n \"amount\": \"304.50\",\n \"currencyCode\": \"CAD\"\n },\n \"orders\": 8,\n \"firstTimeCustomers\": 5.0,\n \"returningCustomers\": 3.0\n },\n \"marketingActivityId\": \"gid://shopify/MarketingActivity/794355127\",\n \"channelHandle\": null,\n \"remoteId\": null\n }\n}'\n" Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n data: {\n \"query\": `mutation M($marketingEngagement: MarketingEngagementInput!, $marketingActivityId: ID, $channelHandle: String, $remoteId: String) {\n marketingEngagementCreate(marketingEngagement: $marketingEngagement, marketingActivityId: $marketingActivityId, channelHandle: $channelHandle, remoteId: $remoteId) {\n marketingEngagement {\n occurredOn\n utcOffset\n isCumulative\n adSpend {\n amount\n currencyCode\n }\n clicksCount\n impressionsCount\n commentsCount\n favoritesCount\n unsubscribesCount\n complaintsCount\n failsCount\n sendsCount\n uniqueViewsCount\n uniqueClicksCount\n sharesCount\n viewsCount\n sessionsCount\n sales {\n amount\n currencyCode\n }\n orders\n firstTimeCustomers\n returningCustomers\n marketingActivity {\n id\n }\n channelHandle\n }\n userErrors {\n field\n message\n }\n }\n }`,\n \"variables\": {\n \"marketingEngagement\": {\n \"occurredOn\": \"2018-06-29\",\n \"utcOffset\": \"-07:00\",\n \"isCumulative\": false,\n \"adSpend\": {\n \"currencyCode\": \"CAD\",\n \"amount\": \"19.90\"\n },\n \"impressionsCount\": 100,\n \"clicksCount\": 40,\n \"commentsCount\": 1,\n \"unsubscribesCount\": 1,\n \"complaintsCount\": 1,\n \"failsCount\": 1,\n \"sendsCount\": 1,\n \"uniqueViewsCount\": 1,\n \"uniqueClicksCount\": 1,\n \"sharesCount\": 5,\n \"viewsCount\": 10,\n \"favoritesCount\": 0,\n \"sessionsCount\": 40,\n \"sales\": {\n \"amount\": \"304.50\",\n \"currencyCode\": \"CAD\"\n },\n \"orders\": 8,\n \"firstTimeCustomers\": 5.0,\n \"returningCustomers\": 3.0\n },\n \"marketingActivityId\": \"gid://shopify/MarketingActivity/794355127\",\n \"channelHandle\": null,\n \"remoteId\": null\n },\n },\n});\n" Ruby example: "session = ShopifyAPI::Auth::Session.new(\n shop: \"your-development-store.myshopify.com\",\n access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n session: session\n)\n\nquery = <<~QUERY\n mutation M($marketingEngagement: MarketingEngagementInput!, $marketingActivityId: ID, $channelHandle: String, $remoteId: String) {\n marketingEngagementCreate(marketingEngagement: $marketingEngagement, marketingActivityId: $marketingActivityId, channelHandle: $channelHandle, remoteId: $remoteId) {\n marketingEngagement {\n occurredOn\n utcOffset\n isCumulative\n adSpend {\n amount\n currencyCode\n }\n clicksCount\n impressionsCount\n commentsCount\n favoritesCount\n unsubscribesCount\n complaintsCount\n failsCount\n sendsCount\n uniqueViewsCount\n uniqueClicksCount\n sharesCount\n viewsCount\n sessionsCount\n sales {\n amount\n currencyCode\n }\n orders\n firstTimeCustomers\n returningCustomers\n marketingActivity {\n id\n }\n channelHandle\n }\n userErrors {\n field\n message\n }\n }\n }\nQUERY\n\nvariables = {\n \"marketingEngagement\": {\n \"occurredOn\": \"2018-06-29\",\n \"utcOffset\": \"-07:00\",\n \"isCumulative\": false,\n \"adSpend\": {\n \"currencyCode\": \"CAD\",\n \"amount\": \"19.90\"\n },\n \"impressionsCount\": 100,\n \"clicksCount\": 40,\n \"commentsCount\": 1,\n \"unsubscribesCount\": 1,\n \"complaintsCount\": 1,\n \"failsCount\": 1,\n \"sendsCount\": 1,\n \"uniqueViewsCount\": 1,\n \"uniqueClicksCount\": 1,\n \"sharesCount\": 5,\n \"viewsCount\": 10,\n \"favoritesCount\": 0,\n \"sessionsCount\": 40,\n \"sales\": {\n \"amount\": \"304.50\",\n \"currencyCode\": \"CAD\"\n },\n \"orders\": 8,\n \"firstTimeCustomers\": 5.0,\n \"returningCustomers\": 3.0\n },\n \"marketingActivityId\": \"gid://shopify/MarketingActivity/794355127\",\n \"channelHandle\": nil,\n \"remoteId\": nil\n}\n\nresponse = client.query(query: query, variables: variables)\n" Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n `#graphql\n mutation M($marketingEngagement: MarketingEngagementInput!, $marketingActivityId: ID, $channelHandle: String, $remoteId: String) {\n marketingEngagementCreate(marketingEngagement: $marketingEngagement, marketingActivityId: $marketingActivityId, channelHandle: $channelHandle, remoteId: $remoteId) {\n marketingEngagement {\n occurredOn\n utcOffset\n isCumulative\n adSpend {\n amount\n currencyCode\n }\n clicksCount\n impressionsCount\n commentsCount\n favoritesCount\n unsubscribesCount\n complaintsCount\n failsCount\n sendsCount\n uniqueViewsCount\n uniqueClicksCount\n sharesCount\n viewsCount\n sessionsCount\n sales {\n amount\n currencyCode\n }\n orders\n firstTimeCustomers\n returningCustomers\n marketingActivity {\n id\n }\n channelHandle\n }\n userErrors {\n field\n message\n }\n }\n }`,\n {\n variables: {\n \"marketingEngagement\": {\n \"occurredOn\": \"2018-06-29\",\n \"utcOffset\": \"-07:00\",\n \"isCumulative\": false,\n \"adSpend\": {\n \"currencyCode\": \"CAD\",\n \"amount\": \"19.90\"\n },\n \"impressionsCount\": 100,\n \"clicksCount\": 40,\n \"commentsCount\": 1,\n \"unsubscribesCount\": 1,\n \"complaintsCount\": 1,\n \"failsCount\": 1,\n \"sendsCount\": 1,\n \"uniqueViewsCount\": 1,\n \"uniqueClicksCount\": 1,\n \"sharesCount\": 5,\n \"viewsCount\": 10,\n \"favoritesCount\": 0,\n \"sessionsCount\": 40,\n \"sales\": {\n \"amount\": \"304.50\",\n \"currencyCode\": \"CAD\"\n },\n \"orders\": 8,\n \"firstTimeCustomers\": 5.0,\n \"returningCustomers\": 3.0\n },\n \"marketingActivityId\": \"gid://shopify/MarketingActivity/794355127\",\n \"channelHandle\": null,\n \"remoteId\": null\n },\n },\n);\n\nconst data = await response.json();\n" Graphql query: "mutation M($marketingEngagement: MarketingEngagementInput!, $marketingActivityId: ID, $channelHandle: String, $remoteId: String) {\n marketingEngagementCreate(marketingEngagement: $marketingEngagement, marketingActivityId: $marketingActivityId, channelHandle: $channelHandle, remoteId: $remoteId) {\n marketingEngagement {\n occurredOn\n utcOffset\n isCumulative\n adSpend {\n amount\n currencyCode\n }\n clicksCount\n impressionsCount\n commentsCount\n favoritesCount\n unsubscribesCount\n complaintsCount\n failsCount\n sendsCount\n uniqueViewsCount\n uniqueClicksCount\n sharesCount\n viewsCount\n sessionsCount\n sales {\n amount\n currencyCode\n }\n orders\n firstTimeCustomers\n returningCustomers\n marketingActivity {\n id\n }\n channelHandle\n }\n userErrors {\n field\n message\n }\n }\n}" #### Graphql Input { "marketingEngagement": { "occurredOn": "2018-06-29", "utcOffset": "-07:00", "isCumulative": false, "adSpend": { "currencyCode": "CAD", "amount": "19.90" }, "impressionsCount": 100, "clicksCount": 40, "commentsCount": 1, "unsubscribesCount": 1, "complaintsCount": 1, "failsCount": 1, "sendsCount": 1, "uniqueViewsCount": 1, "uniqueClicksCount": 1, "sharesCount": 5, "viewsCount": 10, "favoritesCount": 0, "sessionsCount": 40, "sales": { "amount": "304.50", "currencyCode": "CAD" }, "orders": 8, "firstTimeCustomers": 5.0, "returningCustomers": 3.0 }, "marketingActivityId": "gid://shopify/MarketingActivity/794355127", "channelHandle": null, "remoteId": null } #### Graphql Response { "data": { "marketingEngagementCreate": { "marketingEngagement": { "occurredOn": "2018-06-29", "utcOffset": "-07:00", "isCumulative": false, "adSpend": { "amount": "19.9", "currencyCode": "CAD" }, "clicksCount": 40, "impressionsCount": 100, "commentsCount": 1, "favoritesCount": 0, "unsubscribesCount": 1, "complaintsCount": 1, "failsCount": 1, "sendsCount": 1, "uniqueViewsCount": 1, "uniqueClicksCount": 1, "sharesCount": 5, "viewsCount": 10, "sessionsCount": 40, "sales": { "amount": "304.5", "currencyCode": "CAD" }, "orders": "8.0", "firstTimeCustomers": "5.0", "returningCustomers": "3.0", "marketingActivity": { "id": "gid://shopify/MarketingActivity/794355127" }, "channelHandle": null }, "userErrors": [] } } } ### Create activity-level engagement with a remote ID Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2025-01/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation M($marketingEngagement: MarketingEngagementInput!, $marketingActivityId: ID, $channelHandle: String, $remoteId: String) { marketingEngagementCreate(marketingEngagement: $marketingEngagement, marketingActivityId: $marketingActivityId, channelHandle: $channelHandle, remoteId: $remoteId) { marketingEngagement { occurredOn utcOffset isCumulative adSpend { amount currencyCode } clicksCount impressionsCount commentsCount favoritesCount unsubscribesCount complaintsCount failsCount sendsCount uniqueViewsCount uniqueClicksCount sharesCount viewsCount sessionsCount sales { amount currencyCode } orders firstTimeCustomers returningCustomers marketingActivity { id } channelHandle } userErrors { field message } } }\",\n \"variables\": {\n \"marketingEngagement\": {\n \"occurredOn\": \"2018-06-29\",\n \"utcOffset\": \"-07:00\",\n \"isCumulative\": false,\n \"adSpend\": {\n \"currencyCode\": \"CAD\",\n \"amount\": \"19.90\"\n },\n \"impressionsCount\": 100,\n \"clicksCount\": 40,\n \"commentsCount\": 1,\n \"unsubscribesCount\": 1,\n \"complaintsCount\": 1,\n \"failsCount\": 1,\n \"sendsCount\": 1,\n \"uniqueViewsCount\": 1,\n \"uniqueClicksCount\": 1,\n \"sharesCount\": 5,\n \"viewsCount\": 10,\n \"favoritesCount\": 0,\n \"sessionsCount\": 40,\n \"sales\": {\n \"amount\": \"304.50\",\n \"currencyCode\": \"CAD\"\n },\n \"orders\": 8,\n \"firstTimeCustomers\": 5.0,\n \"returningCustomers\": 3.0\n },\n \"marketingActivityId\": null,\n \"channelHandle\": null,\n \"remoteId\": \"1234:5678\"\n }\n}'\n" Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n data: {\n \"query\": `mutation M($marketingEngagement: MarketingEngagementInput!, $marketingActivityId: ID, $channelHandle: String, $remoteId: String) {\n marketingEngagementCreate(marketingEngagement: $marketingEngagement, marketingActivityId: $marketingActivityId, channelHandle: $channelHandle, remoteId: $remoteId) {\n marketingEngagement {\n occurredOn\n utcOffset\n isCumulative\n adSpend {\n amount\n currencyCode\n }\n clicksCount\n impressionsCount\n commentsCount\n favoritesCount\n unsubscribesCount\n complaintsCount\n failsCount\n sendsCount\n uniqueViewsCount\n uniqueClicksCount\n sharesCount\n viewsCount\n sessionsCount\n sales {\n amount\n currencyCode\n }\n orders\n firstTimeCustomers\n returningCustomers\n marketingActivity {\n id\n }\n channelHandle\n }\n userErrors {\n field\n message\n }\n }\n }`,\n \"variables\": {\n \"marketingEngagement\": {\n \"occurredOn\": \"2018-06-29\",\n \"utcOffset\": \"-07:00\",\n \"isCumulative\": false,\n \"adSpend\": {\n \"currencyCode\": \"CAD\",\n \"amount\": \"19.90\"\n },\n \"impressionsCount\": 100,\n \"clicksCount\": 40,\n \"commentsCount\": 1,\n \"unsubscribesCount\": 1,\n \"complaintsCount\": 1,\n \"failsCount\": 1,\n \"sendsCount\": 1,\n \"uniqueViewsCount\": 1,\n \"uniqueClicksCount\": 1,\n \"sharesCount\": 5,\n \"viewsCount\": 10,\n \"favoritesCount\": 0,\n \"sessionsCount\": 40,\n \"sales\": {\n \"amount\": \"304.50\",\n \"currencyCode\": \"CAD\"\n },\n \"orders\": 8,\n \"firstTimeCustomers\": 5.0,\n \"returningCustomers\": 3.0\n },\n \"marketingActivityId\": null,\n \"channelHandle\": null,\n \"remoteId\": \"1234:5678\"\n },\n },\n});\n" Ruby example: "session = ShopifyAPI::Auth::Session.new(\n shop: \"your-development-store.myshopify.com\",\n access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n session: session\n)\n\nquery = <<~QUERY\n mutation M($marketingEngagement: MarketingEngagementInput!, $marketingActivityId: ID, $channelHandle: String, $remoteId: String) {\n marketingEngagementCreate(marketingEngagement: $marketingEngagement, marketingActivityId: $marketingActivityId, channelHandle: $channelHandle, remoteId: $remoteId) {\n marketingEngagement {\n occurredOn\n utcOffset\n isCumulative\n adSpend {\n amount\n currencyCode\n }\n clicksCount\n impressionsCount\n commentsCount\n favoritesCount\n unsubscribesCount\n complaintsCount\n failsCount\n sendsCount\n uniqueViewsCount\n uniqueClicksCount\n sharesCount\n viewsCount\n sessionsCount\n sales {\n amount\n currencyCode\n }\n orders\n firstTimeCustomers\n returningCustomers\n marketingActivity {\n id\n }\n channelHandle\n }\n userErrors {\n field\n message\n }\n }\n }\nQUERY\n\nvariables = {\n \"marketingEngagement\": {\n \"occurredOn\": \"2018-06-29\",\n \"utcOffset\": \"-07:00\",\n \"isCumulative\": false,\n \"adSpend\": {\n \"currencyCode\": \"CAD\",\n \"amount\": \"19.90\"\n },\n \"impressionsCount\": 100,\n \"clicksCount\": 40,\n \"commentsCount\": 1,\n \"unsubscribesCount\": 1,\n \"complaintsCount\": 1,\n \"failsCount\": 1,\n \"sendsCount\": 1,\n \"uniqueViewsCount\": 1,\n \"uniqueClicksCount\": 1,\n \"sharesCount\": 5,\n \"viewsCount\": 10,\n \"favoritesCount\": 0,\n \"sessionsCount\": 40,\n \"sales\": {\n \"amount\": \"304.50\",\n \"currencyCode\": \"CAD\"\n },\n \"orders\": 8,\n \"firstTimeCustomers\": 5.0,\n \"returningCustomers\": 3.0\n },\n \"marketingActivityId\": nil,\n \"channelHandle\": nil,\n \"remoteId\": \"1234:5678\"\n}\n\nresponse = client.query(query: query, variables: variables)\n" Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n `#graphql\n mutation M($marketingEngagement: MarketingEngagementInput!, $marketingActivityId: ID, $channelHandle: String, $remoteId: String) {\n marketingEngagementCreate(marketingEngagement: $marketingEngagement, marketingActivityId: $marketingActivityId, channelHandle: $channelHandle, remoteId: $remoteId) {\n marketingEngagement {\n occurredOn\n utcOffset\n isCumulative\n adSpend {\n amount\n currencyCode\n }\n clicksCount\n impressionsCount\n commentsCount\n favoritesCount\n unsubscribesCount\n complaintsCount\n failsCount\n sendsCount\n uniqueViewsCount\n uniqueClicksCount\n sharesCount\n viewsCount\n sessionsCount\n sales {\n amount\n currencyCode\n }\n orders\n firstTimeCustomers\n returningCustomers\n marketingActivity {\n id\n }\n channelHandle\n }\n userErrors {\n field\n message\n }\n }\n }`,\n {\n variables: {\n \"marketingEngagement\": {\n \"occurredOn\": \"2018-06-29\",\n \"utcOffset\": \"-07:00\",\n \"isCumulative\": false,\n \"adSpend\": {\n \"currencyCode\": \"CAD\",\n \"amount\": \"19.90\"\n },\n \"impressionsCount\": 100,\n \"clicksCount\": 40,\n \"commentsCount\": 1,\n \"unsubscribesCount\": 1,\n \"complaintsCount\": 1,\n \"failsCount\": 1,\n \"sendsCount\": 1,\n \"uniqueViewsCount\": 1,\n \"uniqueClicksCount\": 1,\n \"sharesCount\": 5,\n \"viewsCount\": 10,\n \"favoritesCount\": 0,\n \"sessionsCount\": 40,\n \"sales\": {\n \"amount\": \"304.50\",\n \"currencyCode\": \"CAD\"\n },\n \"orders\": 8,\n \"firstTimeCustomers\": 5.0,\n \"returningCustomers\": 3.0\n },\n \"marketingActivityId\": null,\n \"channelHandle\": null,\n \"remoteId\": \"1234:5678\"\n },\n },\n);\n\nconst data = await response.json();\n" Graphql query: "mutation M($marketingEngagement: MarketingEngagementInput!, $marketingActivityId: ID, $channelHandle: String, $remoteId: String) {\n marketingEngagementCreate(marketingEngagement: $marketingEngagement, marketingActivityId: $marketingActivityId, channelHandle: $channelHandle, remoteId: $remoteId) {\n marketingEngagement {\n occurredOn\n utcOffset\n isCumulative\n adSpend {\n amount\n currencyCode\n }\n clicksCount\n impressionsCount\n commentsCount\n favoritesCount\n unsubscribesCount\n complaintsCount\n failsCount\n sendsCount\n uniqueViewsCount\n uniqueClicksCount\n sharesCount\n viewsCount\n sessionsCount\n sales {\n amount\n currencyCode\n }\n orders\n firstTimeCustomers\n returningCustomers\n marketingActivity {\n id\n }\n channelHandle\n }\n userErrors {\n field\n message\n }\n }\n}" #### Graphql Input { "marketingEngagement": { "occurredOn": "2018-06-29", "utcOffset": "-07:00", "isCumulative": false, "adSpend": { "currencyCode": "CAD", "amount": "19.90" }, "impressionsCount": 100, "clicksCount": 40, "commentsCount": 1, "unsubscribesCount": 1, "complaintsCount": 1, "failsCount": 1, "sendsCount": 1, "uniqueViewsCount": 1, "uniqueClicksCount": 1, "sharesCount": 5, "viewsCount": 10, "favoritesCount": 0, "sessionsCount": 40, "sales": { "amount": "304.50", "currencyCode": "CAD" }, "orders": 8, "firstTimeCustomers": 5.0, "returningCustomers": 3.0 }, "marketingActivityId": null, "channelHandle": null, "remoteId": "1234:5678" } #### Graphql Response { "data": { "marketingEngagementCreate": { "marketingEngagement": { "occurredOn": "2018-06-29", "utcOffset": "-07:00", "isCumulative": false, "adSpend": { "amount": "19.9", "currencyCode": "CAD" }, "clicksCount": 40, "impressionsCount": 100, "commentsCount": 1, "favoritesCount": 0, "unsubscribesCount": 1, "complaintsCount": 1, "failsCount": 1, "sendsCount": 1, "uniqueViewsCount": 1, "uniqueClicksCount": 1, "sharesCount": 5, "viewsCount": 10, "sessionsCount": 40, "sales": { "amount": "304.5", "currencyCode": "CAD" }, "orders": "8.0", "firstTimeCustomers": "5.0", "returningCustomers": "3.0", "marketingActivity": { "id": "gid://shopify/MarketingActivity/794355127" }, "channelHandle": null }, "userErrors": [] } } } ### Create channel-level engagement for a channel handle Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2025-01/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation M($marketingEngagement: MarketingEngagementInput!, $marketingActivityId: ID, $channelHandle: String, $remoteId: String) { marketingEngagementCreate(marketingEngagement: $marketingEngagement, marketingActivityId: $marketingActivityId, channelHandle: $channelHandle, remoteId: $remoteId) { marketingEngagement { occurredOn utcOffset isCumulative adSpend { amount currencyCode } clicksCount impressionsCount commentsCount favoritesCount unsubscribesCount complaintsCount failsCount sendsCount uniqueViewsCount uniqueClicksCount sharesCount viewsCount sessionsCount sales { amount currencyCode } orders firstTimeCustomers returningCustomers marketingActivity { id } channelHandle } userErrors { field message } } }\",\n \"variables\": {\n \"marketingEngagement\": {\n \"occurredOn\": \"2018-06-29\",\n \"utcOffset\": \"-07:00\",\n \"isCumulative\": false,\n \"adSpend\": {\n \"currencyCode\": \"CAD\",\n \"amount\": \"19.90\"\n },\n \"impressionsCount\": 100,\n \"clicksCount\": 40,\n \"commentsCount\": 1,\n \"unsubscribesCount\": 1,\n \"complaintsCount\": 1,\n \"failsCount\": 1,\n \"sendsCount\": 1,\n \"uniqueViewsCount\": 1,\n \"uniqueClicksCount\": 1,\n \"sharesCount\": 5,\n \"viewsCount\": 10,\n \"favoritesCount\": 0,\n \"sessionsCount\": 40,\n \"sales\": {\n \"amount\": \"304.50\",\n \"currencyCode\": \"CAD\"\n },\n \"orders\": 8,\n \"firstTimeCustomers\": 5.0,\n \"returningCustomers\": 3.0\n },\n \"marketingActivityId\": null,\n \"channelHandle\": \"my-channel-handle\",\n \"remoteId\": null\n }\n}'\n" Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n data: {\n \"query\": `mutation M($marketingEngagement: MarketingEngagementInput!, $marketingActivityId: ID, $channelHandle: String, $remoteId: String) {\n marketingEngagementCreate(marketingEngagement: $marketingEngagement, marketingActivityId: $marketingActivityId, channelHandle: $channelHandle, remoteId: $remoteId) {\n marketingEngagement {\n occurredOn\n utcOffset\n isCumulative\n adSpend {\n amount\n currencyCode\n }\n clicksCount\n impressionsCount\n commentsCount\n favoritesCount\n unsubscribesCount\n complaintsCount\n failsCount\n sendsCount\n uniqueViewsCount\n uniqueClicksCount\n sharesCount\n viewsCount\n sessionsCount\n sales {\n amount\n currencyCode\n }\n orders\n firstTimeCustomers\n returningCustomers\n marketingActivity {\n id\n }\n channelHandle\n }\n userErrors {\n field\n message\n }\n }\n }`,\n \"variables\": {\n \"marketingEngagement\": {\n \"occurredOn\": \"2018-06-29\",\n \"utcOffset\": \"-07:00\",\n \"isCumulative\": false,\n \"adSpend\": {\n \"currencyCode\": \"CAD\",\n \"amount\": \"19.90\"\n },\n \"impressionsCount\": 100,\n \"clicksCount\": 40,\n \"commentsCount\": 1,\n \"unsubscribesCount\": 1,\n \"complaintsCount\": 1,\n \"failsCount\": 1,\n \"sendsCount\": 1,\n \"uniqueViewsCount\": 1,\n \"uniqueClicksCount\": 1,\n \"sharesCount\": 5,\n \"viewsCount\": 10,\n \"favoritesCount\": 0,\n \"sessionsCount\": 40,\n \"sales\": {\n \"amount\": \"304.50\",\n \"currencyCode\": \"CAD\"\n },\n \"orders\": 8,\n \"firstTimeCustomers\": 5.0,\n \"returningCustomers\": 3.0\n },\n \"marketingActivityId\": null,\n \"channelHandle\": \"my-channel-handle\",\n \"remoteId\": null\n },\n },\n});\n" Ruby example: "session = ShopifyAPI::Auth::Session.new(\n shop: \"your-development-store.myshopify.com\",\n access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n session: session\n)\n\nquery = <<~QUERY\n mutation M($marketingEngagement: MarketingEngagementInput!, $marketingActivityId: ID, $channelHandle: String, $remoteId: String) {\n marketingEngagementCreate(marketingEngagement: $marketingEngagement, marketingActivityId: $marketingActivityId, channelHandle: $channelHandle, remoteId: $remoteId) {\n marketingEngagement {\n occurredOn\n utcOffset\n isCumulative\n adSpend {\n amount\n currencyCode\n }\n clicksCount\n impressionsCount\n commentsCount\n favoritesCount\n unsubscribesCount\n complaintsCount\n failsCount\n sendsCount\n uniqueViewsCount\n uniqueClicksCount\n sharesCount\n viewsCount\n sessionsCount\n sales {\n amount\n currencyCode\n }\n orders\n firstTimeCustomers\n returningCustomers\n marketingActivity {\n id\n }\n channelHandle\n }\n userErrors {\n field\n message\n }\n }\n }\nQUERY\n\nvariables = {\n \"marketingEngagement\": {\n \"occurredOn\": \"2018-06-29\",\n \"utcOffset\": \"-07:00\",\n \"isCumulative\": false,\n \"adSpend\": {\n \"currencyCode\": \"CAD\",\n \"amount\": \"19.90\"\n },\n \"impressionsCount\": 100,\n \"clicksCount\": 40,\n \"commentsCount\": 1,\n \"unsubscribesCount\": 1,\n \"complaintsCount\": 1,\n \"failsCount\": 1,\n \"sendsCount\": 1,\n \"uniqueViewsCount\": 1,\n \"uniqueClicksCount\": 1,\n \"sharesCount\": 5,\n \"viewsCount\": 10,\n \"favoritesCount\": 0,\n \"sessionsCount\": 40,\n \"sales\": {\n \"amount\": \"304.50\",\n \"currencyCode\": \"CAD\"\n },\n \"orders\": 8,\n \"firstTimeCustomers\": 5.0,\n \"returningCustomers\": 3.0\n },\n \"marketingActivityId\": nil,\n \"channelHandle\": \"my-channel-handle\",\n \"remoteId\": nil\n}\n\nresponse = client.query(query: query, variables: variables)\n" Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n `#graphql\n mutation M($marketingEngagement: MarketingEngagementInput!, $marketingActivityId: ID, $channelHandle: String, $remoteId: String) {\n marketingEngagementCreate(marketingEngagement: $marketingEngagement, marketingActivityId: $marketingActivityId, channelHandle: $channelHandle, remoteId: $remoteId) {\n marketingEngagement {\n occurredOn\n utcOffset\n isCumulative\n adSpend {\n amount\n currencyCode\n }\n clicksCount\n impressionsCount\n commentsCount\n favoritesCount\n unsubscribesCount\n complaintsCount\n failsCount\n sendsCount\n uniqueViewsCount\n uniqueClicksCount\n sharesCount\n viewsCount\n sessionsCount\n sales {\n amount\n currencyCode\n }\n orders\n firstTimeCustomers\n returningCustomers\n marketingActivity {\n id\n }\n channelHandle\n }\n userErrors {\n field\n message\n }\n }\n }`,\n {\n variables: {\n \"marketingEngagement\": {\n \"occurredOn\": \"2018-06-29\",\n \"utcOffset\": \"-07:00\",\n \"isCumulative\": false,\n \"adSpend\": {\n \"currencyCode\": \"CAD\",\n \"amount\": \"19.90\"\n },\n \"impressionsCount\": 100,\n \"clicksCount\": 40,\n \"commentsCount\": 1,\n \"unsubscribesCount\": 1,\n \"complaintsCount\": 1,\n \"failsCount\": 1,\n \"sendsCount\": 1,\n \"uniqueViewsCount\": 1,\n \"uniqueClicksCount\": 1,\n \"sharesCount\": 5,\n \"viewsCount\": 10,\n \"favoritesCount\": 0,\n \"sessionsCount\": 40,\n \"sales\": {\n \"amount\": \"304.50\",\n \"currencyCode\": \"CAD\"\n },\n \"orders\": 8,\n \"firstTimeCustomers\": 5.0,\n \"returningCustomers\": 3.0\n },\n \"marketingActivityId\": null,\n \"channelHandle\": \"my-channel-handle\",\n \"remoteId\": null\n },\n },\n);\n\nconst data = await response.json();\n" Graphql query: "mutation M($marketingEngagement: MarketingEngagementInput!, $marketingActivityId: ID, $channelHandle: String, $remoteId: String) {\n marketingEngagementCreate(marketingEngagement: $marketingEngagement, marketingActivityId: $marketingActivityId, channelHandle: $channelHandle, remoteId: $remoteId) {\n marketingEngagement {\n occurredOn\n utcOffset\n isCumulative\n adSpend {\n amount\n currencyCode\n }\n clicksCount\n impressionsCount\n commentsCount\n favoritesCount\n unsubscribesCount\n complaintsCount\n failsCount\n sendsCount\n uniqueViewsCount\n uniqueClicksCount\n sharesCount\n viewsCount\n sessionsCount\n sales {\n amount\n currencyCode\n }\n orders\n firstTimeCustomers\n returningCustomers\n marketingActivity {\n id\n }\n channelHandle\n }\n userErrors {\n field\n message\n }\n }\n}" #### Graphql Input { "marketingEngagement": { "occurredOn": "2018-06-29", "utcOffset": "-07:00", "isCumulative": false, "adSpend": { "currencyCode": "CAD", "amount": "19.90" }, "impressionsCount": 100, "clicksCount": 40, "commentsCount": 1, "unsubscribesCount": 1, "complaintsCount": 1, "failsCount": 1, "sendsCount": 1, "uniqueViewsCount": 1, "uniqueClicksCount": 1, "sharesCount": 5, "viewsCount": 10, "favoritesCount": 0, "sessionsCount": 40, "sales": { "amount": "304.50", "currencyCode": "CAD" }, "orders": 8, "firstTimeCustomers": 5.0, "returningCustomers": 3.0 }, "marketingActivityId": null, "channelHandle": "my-channel-handle", "remoteId": null } #### Graphql Response { "data": { "marketingEngagementCreate": { "marketingEngagement": { "occurredOn": "2018-06-29", "utcOffset": "-07:00", "isCumulative": false, "adSpend": { "amount": "19.9", "currencyCode": "CAD" }, "clicksCount": 40, "impressionsCount": 100, "commentsCount": 1, "favoritesCount": 0, "unsubscribesCount": 1, "complaintsCount": 1, "failsCount": 1, "sendsCount": 1, "uniqueViewsCount": 1, "uniqueClicksCount": 1, "sharesCount": 5, "viewsCount": 10, "sessionsCount": 40, "sales": { "amount": "304.5", "currencyCode": "CAD" }, "orders": "8.0", "firstTimeCustomers": "5.0", "returningCustomers": "3.0", "marketingActivity": null, "channelHandle": "my-channel-handle" }, "userErrors": [] } } } ### Creates marketing engagements on a marketing event Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2025-01/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation M($marketingEngagement: MarketingEngagementInput!, $marketingActivityId: ID!) { marketingEngagementCreate(marketingEngagement: $marketingEngagement, marketingActivityId: $marketingActivityId) { marketingEngagement { occurredOn clicksCount commentsCount favoritesCount impressionsCount unsubscribesCount complaintsCount failsCount sendsCount uniqueViewsCount uniqueClicksCount isCumulative utcOffset adSpend { amount currencyCode } marketingActivity { id } } userErrors { field message } } }\",\n \"variables\": {\n \"marketingEngagement\": {\n \"occurredOn\": \"2018-06-29\",\n \"adSpend\": {\n \"currencyCode\": \"CAD\",\n \"amount\": \"19.90\"\n },\n \"utcOffset\": \"-07:00\",\n \"impressionsCount\": 100,\n \"clicksCount\": 40,\n \"commentsCount\": 1,\n \"unsubscribesCount\": 1,\n \"complaintsCount\": 1,\n \"failsCount\": 1,\n \"sendsCount\": 1,\n \"uniqueViewsCount\": 1,\n \"uniqueClicksCount\": 1,\n \"isCumulative\": true,\n \"favoritesCount\": 0\n },\n \"marketingActivityId\": \"gid://shopify/MarketingActivity/794355127\"\n }\n}'\n" Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n data: {\n \"query\": `mutation M($marketingEngagement: MarketingEngagementInput!, $marketingActivityId: ID!) {\n marketingEngagementCreate(marketingEngagement: $marketingEngagement, marketingActivityId: $marketingActivityId) {\n marketingEngagement {\n occurredOn\n clicksCount\n commentsCount\n favoritesCount\n impressionsCount\n unsubscribesCount\n complaintsCount\n failsCount\n sendsCount\n uniqueViewsCount\n uniqueClicksCount\n isCumulative\n utcOffset\n adSpend {\n amount\n currencyCode\n }\n marketingActivity {\n id\n }\n }\n userErrors {\n field\n message\n }\n }\n }`,\n \"variables\": {\n \"marketingEngagement\": {\n \"occurredOn\": \"2018-06-29\",\n \"adSpend\": {\n \"currencyCode\": \"CAD\",\n \"amount\": \"19.90\"\n },\n \"utcOffset\": \"-07:00\",\n \"impressionsCount\": 100,\n \"clicksCount\": 40,\n \"commentsCount\": 1,\n \"unsubscribesCount\": 1,\n \"complaintsCount\": 1,\n \"failsCount\": 1,\n \"sendsCount\": 1,\n \"uniqueViewsCount\": 1,\n \"uniqueClicksCount\": 1,\n \"isCumulative\": true,\n \"favoritesCount\": 0\n },\n \"marketingActivityId\": \"gid://shopify/MarketingActivity/794355127\"\n },\n },\n});\n" Ruby example: "session = ShopifyAPI::Auth::Session.new(\n shop: \"your-development-store.myshopify.com\",\n access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n session: session\n)\n\nquery = <<~QUERY\n mutation M($marketingEngagement: MarketingEngagementInput!, $marketingActivityId: ID!) {\n marketingEngagementCreate(marketingEngagement: $marketingEngagement, marketingActivityId: $marketingActivityId) {\n marketingEngagement {\n occurredOn\n clicksCount\n commentsCount\n favoritesCount\n impressionsCount\n unsubscribesCount\n complaintsCount\n failsCount\n sendsCount\n uniqueViewsCount\n uniqueClicksCount\n isCumulative\n utcOffset\n adSpend {\n amount\n currencyCode\n }\n marketingActivity {\n id\n }\n }\n userErrors {\n field\n message\n }\n }\n }\nQUERY\n\nvariables = {\n \"marketingEngagement\": {\n \"occurredOn\": \"2018-06-29\",\n \"adSpend\": {\n \"currencyCode\": \"CAD\",\n \"amount\": \"19.90\"\n },\n \"utcOffset\": \"-07:00\",\n \"impressionsCount\": 100,\n \"clicksCount\": 40,\n \"commentsCount\": 1,\n \"unsubscribesCount\": 1,\n \"complaintsCount\": 1,\n \"failsCount\": 1,\n \"sendsCount\": 1,\n \"uniqueViewsCount\": 1,\n \"uniqueClicksCount\": 1,\n \"isCumulative\": true,\n \"favoritesCount\": 0\n },\n \"marketingActivityId\": \"gid://shopify/MarketingActivity/794355127\"\n}\n\nresponse = client.query(query: query, variables: variables)\n" Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n `#graphql\n mutation M($marketingEngagement: MarketingEngagementInput!, $marketingActivityId: ID!) {\n marketingEngagementCreate(marketingEngagement: $marketingEngagement, marketingActivityId: $marketingActivityId) {\n marketingEngagement {\n occurredOn\n clicksCount\n commentsCount\n favoritesCount\n impressionsCount\n unsubscribesCount\n complaintsCount\n failsCount\n sendsCount\n uniqueViewsCount\n uniqueClicksCount\n isCumulative\n utcOffset\n adSpend {\n amount\n currencyCode\n }\n marketingActivity {\n id\n }\n }\n userErrors {\n field\n message\n }\n }\n }`,\n {\n variables: {\n \"marketingEngagement\": {\n \"occurredOn\": \"2018-06-29\",\n \"adSpend\": {\n \"currencyCode\": \"CAD\",\n \"amount\": \"19.90\"\n },\n \"utcOffset\": \"-07:00\",\n \"impressionsCount\": 100,\n \"clicksCount\": 40,\n \"commentsCount\": 1,\n \"unsubscribesCount\": 1,\n \"complaintsCount\": 1,\n \"failsCount\": 1,\n \"sendsCount\": 1,\n \"uniqueViewsCount\": 1,\n \"uniqueClicksCount\": 1,\n \"isCumulative\": true,\n \"favoritesCount\": 0\n },\n \"marketingActivityId\": \"gid://shopify/MarketingActivity/794355127\"\n },\n },\n);\n\nconst data = await response.json();\n" Graphql query: "mutation M($marketingEngagement: MarketingEngagementInput!, $marketingActivityId: ID!) {\n marketingEngagementCreate(marketingEngagement: $marketingEngagement, marketingActivityId: $marketingActivityId) {\n marketingEngagement {\n occurredOn\n clicksCount\n commentsCount\n favoritesCount\n impressionsCount\n unsubscribesCount\n complaintsCount\n failsCount\n sendsCount\n uniqueViewsCount\n uniqueClicksCount\n isCumulative\n utcOffset\n adSpend {\n amount\n currencyCode\n }\n marketingActivity {\n id\n }\n }\n userErrors {\n field\n message\n }\n }\n}" #### Graphql Input { "marketingEngagement": { "occurredOn": "2018-06-29", "adSpend": { "currencyCode": "CAD", "amount": "19.90" }, "utcOffset": "-07:00", "impressionsCount": 100, "clicksCount": 40, "commentsCount": 1, "unsubscribesCount": 1, "complaintsCount": 1, "failsCount": 1, "sendsCount": 1, "uniqueViewsCount": 1, "uniqueClicksCount": 1, "isCumulative": true, "favoritesCount": 0 }, "marketingActivityId": "gid://shopify/MarketingActivity/794355127" } #### Graphql Response { "data": { "marketingEngagementCreate": { "marketingEngagement": { "occurredOn": "2018-06-29", "clicksCount": 40, "commentsCount": 1, "favoritesCount": 0, "impressionsCount": 100, "unsubscribesCount": 1, "complaintsCount": 1, "failsCount": 1, "sendsCount": 1, "uniqueViewsCount": 1, "uniqueClicksCount": 1, "isCumulative": true, "utcOffset": "-07:00", "adSpend": { "amount": "19.9", "currencyCode": "CAD" }, "marketingActivity": { "id": "gid://shopify/MarketingActivity/794355127" } }, "userErrors": [] } } }