--- title: marketingEngagementCreate - GraphQL Admin description: >- Creates a new marketing engagement for a marketing activity or a marketing channel. api_version: 2024-10 api_name: admin type: mutation api_type: graphql source_url: html: >- https://shopify.dev/docs/api/admin-graphql/2024-10/mutations/marketingEngagementCreate md: >- https://shopify.dev/docs/api/admin-graphql/2024-10/mutations/marketingEngagementCreate.txt --- # marketing​Engagement​Create mutation Requires `write_marketing_events` access scope. Creates a new marketing engagement for a marketing activity or a marketing channel. ## Arguments * channel​Handle [String](https://shopify.dev/docs/api/admin-graphql/2024-10/scalars/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. * marketing​Activity​Id [ID](https://shopify.dev/docs/api/admin-graphql/2024-10/scalars/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. * marketing​Engagement [Marketing​Engagement​Input!](https://shopify.dev/docs/api/admin-graphql/2024-10/input-objects/MarketingEngagementInput) required The marketing engagement's attributes. * remote​Id [String](https://shopify.dev/docs/api/admin-graphql/2024-10/scalars/String) A custom unique identifier for the marketing activity, which can be used to manage the activity and send engagement metrics without having to store our marketing activity ID in your systems. This or the marketingActivityId should be set when and only when providing activity-level engagements. This should be nil when providing channel-level engagements. *** ## Marketing​Engagement​Create​Payload returns * marketing​Engagement [Marketing​Engagement](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/MarketingEngagement) The marketing engagement that was created. This represents customer activity taken on a marketing activity or a marketing channel. * user​Errors [\[Marketing​Activity​User​Error!\]!](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/MarketingActivityUserError) non-null The list of errors that occurred from executing the mutation. *** ## Examples * ### Create activity-level engagement for a marketing activity ID #### Query ```graphql 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 } } } ``` #### Variables ```json { "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, "returningCustomers": 3 }, "marketingActivityId": "gid://shopify/MarketingActivity/794355127", "channelHandle": null, "remoteId": null } ``` #### cURL ```bash curl -X POST \ https://your-development-store.myshopify.com/admin/api/2024-10/graphql.json \ -H 'Content-Type: application/json' \ -H 'X-Shopify-Access-Token: {access_token}' \ -d '{ "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 } } }", "variables": { "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, "returningCustomers": 3 }, "marketingActivityId": "gid://shopify/MarketingActivity/794355127", "channelHandle": null, "remoteId": null } }' ``` #### Remix ```javascript const { admin } = await authenticate.admin(request); const response = await admin.graphql( `#graphql 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 } } }`, { variables: { "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, "returningCustomers": 3 }, "marketingActivityId": "gid://shopify/MarketingActivity/794355127", "channelHandle": null, "remoteId": null }, }, ); const data = await response.json(); ``` #### Ruby ```ruby session = ShopifyAPI::Auth::Session.new( shop: "your-development-store.myshopify.com", access_token: access_token ) client = ShopifyAPI::Clients::Graphql::Admin.new( session: session ) query = <<~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 } } } QUERY variables = { "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, "returningCustomers": 3 }, "marketingActivityId": "gid://shopify/MarketingActivity/794355127", "channelHandle": null, "remoteId": null } response = client.query(query: query, variables: variables) ``` #### Node.js ```javascript const client = new shopify.clients.Graphql({session}); const data = await client.query({ data: { "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 } } }`, "variables": { "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, "returningCustomers": 3 }, "marketingActivityId": "gid://shopify/MarketingActivity/794355127", "channelHandle": null, "remoteId": null }, }, }); ``` #### Response ```json { "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 #### Query ```graphql 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 } } } ``` #### Variables ```json { "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, "returningCustomers": 3 }, "marketingActivityId": null, "channelHandle": null, "remoteId": "1234:5678" } ``` #### cURL ```bash curl -X POST \ https://your-development-store.myshopify.com/admin/api/2024-10/graphql.json \ -H 'Content-Type: application/json' \ -H 'X-Shopify-Access-Token: {access_token}' \ -d '{ "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 } } }", "variables": { "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, "returningCustomers": 3 }, "marketingActivityId": null, "channelHandle": null, "remoteId": "1234:5678" } }' ``` #### Remix ```javascript const { admin } = await authenticate.admin(request); const response = await admin.graphql( `#graphql 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 } } }`, { variables: { "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, "returningCustomers": 3 }, "marketingActivityId": null, "channelHandle": null, "remoteId": "1234:5678" }, }, ); const data = await response.json(); ``` #### Ruby ```ruby session = ShopifyAPI::Auth::Session.new( shop: "your-development-store.myshopify.com", access_token: access_token ) client = ShopifyAPI::Clients::Graphql::Admin.new( session: session ) query = <<~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 } } } QUERY variables = { "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, "returningCustomers": 3 }, "marketingActivityId": null, "channelHandle": null, "remoteId": "1234:5678" } response = client.query(query: query, variables: variables) ``` #### Node.js ```javascript const client = new shopify.clients.Graphql({session}); const data = await client.query({ data: { "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 } } }`, "variables": { "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, "returningCustomers": 3 }, "marketingActivityId": null, "channelHandle": null, "remoteId": "1234:5678" }, }, }); ``` #### Response ```json { "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 #### Query ```graphql 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 } } } ``` #### Variables ```json { "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, "returningCustomers": 3 }, "marketingActivityId": null, "channelHandle": "my-channel-handle", "remoteId": null } ``` #### cURL ```bash curl -X POST \ https://your-development-store.myshopify.com/admin/api/2024-10/graphql.json \ -H 'Content-Type: application/json' \ -H 'X-Shopify-Access-Token: {access_token}' \ -d '{ "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 } } }", "variables": { "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, "returningCustomers": 3 }, "marketingActivityId": null, "channelHandle": "my-channel-handle", "remoteId": null } }' ``` #### Remix ```javascript const { admin } = await authenticate.admin(request); const response = await admin.graphql( `#graphql 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 } } }`, { variables: { "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, "returningCustomers": 3 }, "marketingActivityId": null, "channelHandle": "my-channel-handle", "remoteId": null }, }, ); const data = await response.json(); ``` #### Ruby ```ruby session = ShopifyAPI::Auth::Session.new( shop: "your-development-store.myshopify.com", access_token: access_token ) client = ShopifyAPI::Clients::Graphql::Admin.new( session: session ) query = <<~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 } } } QUERY variables = { "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, "returningCustomers": 3 }, "marketingActivityId": null, "channelHandle": "my-channel-handle", "remoteId": null } response = client.query(query: query, variables: variables) ``` #### Node.js ```javascript const client = new shopify.clients.Graphql({session}); const data = await client.query({ data: { "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 } } }`, "variables": { "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, "returningCustomers": 3 }, "marketingActivityId": null, "channelHandle": "my-channel-handle", "remoteId": null }, }, }); ``` #### Response ```json { "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 #### Query ```graphql 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 } } } ``` #### Variables ```json { "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" } ``` #### cURL ```bash curl -X POST \ https://your-development-store.myshopify.com/admin/api/2024-10/graphql.json \ -H 'Content-Type: application/json' \ -H 'X-Shopify-Access-Token: {access_token}' \ -d '{ "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 } } }", "variables": { "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" } }' ``` #### Remix ```javascript const { admin } = await authenticate.admin(request); const response = await admin.graphql( `#graphql 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 } } }`, { variables: { "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" }, }, ); const data = await response.json(); ``` #### Ruby ```ruby session = ShopifyAPI::Auth::Session.new( shop: "your-development-store.myshopify.com", access_token: access_token ) client = ShopifyAPI::Clients::Graphql::Admin.new( session: session ) query = <<~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 } } } QUERY variables = { "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" } response = client.query(query: query, variables: variables) ``` #### Node.js ```javascript const client = new shopify.clients.Graphql({session}); const data = await client.query({ data: { "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 } } }`, "variables": { "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" }, }, }); ``` #### Response ```json { "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": [] } } ``` * ### marketingEngagementCreate reference [Open in GraphiQL](http://localhost:3457/graphiql?query=mutation%20M\(%24marketingEngagement%3A%20MarketingEngagementInput!%2C%20%24marketingActivityId%3A%20ID%2C%20%24channelHandle%3A%20String%2C%20%24remoteId%3A%20String\)%20%7B%0A%20%20marketingEngagementCreate\(marketingEngagement%3A%20%24marketingEngagement%2C%20marketingActivityId%3A%20%24marketingActivityId%2C%20channelHandle%3A%20%24channelHandle%2C%20remoteId%3A%20%24remoteId\)%20%7B%0A%20%20%20%20marketingEngagement%20%7B%0A%20%20%20%20%20%20occurredOn%0A%20%20%20%20%20%20utcOffset%0A%20%20%20%20%20%20isCumulative%0A%20%20%20%20%20%20adSpend%20%7B%0A%20%20%20%20%20%20%20%20amount%0A%20%20%20%20%20%20%20%20currencyCode%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20clicksCount%0A%20%20%20%20%20%20impressionsCount%0A%20%20%20%20%20%20commentsCount%0A%20%20%20%20%20%20favoritesCount%0A%20%20%20%20%20%20unsubscribesCount%0A%20%20%20%20%20%20complaintsCount%0A%20%20%20%20%20%20failsCount%0A%20%20%20%20%20%20sendsCount%0A%20%20%20%20%20%20uniqueViewsCount%0A%20%20%20%20%20%20uniqueClicksCount%0A%20%20%20%20%20%20sharesCount%0A%20%20%20%20%20%20viewsCount%0A%20%20%20%20%20%20sessionsCount%0A%20%20%20%20%20%20sales%20%7B%0A%20%20%20%20%20%20%20%20amount%0A%20%20%20%20%20%20%20%20currencyCode%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20orders%0A%20%20%20%20%20%20firstTimeCustomers%0A%20%20%20%20%20%20returningCustomers%0A%20%20%20%20%20%20marketingActivity%20%7B%0A%20%20%20%20%20%20%20%20id%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20channelHandle%0A%20%20%20%20%7D%0A%20%20%20%20userErrors%20%7B%0A%20%20%20%20%20%20field%0A%20%20%20%20%20%20message%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D\&variables=%7B%0A%20%20%22marketingEngagement%22%3A%20%7B%0A%20%20%20%20%22occurredOn%22%3A%20%222018-06-29%22%2C%0A%20%20%20%20%22utcOffset%22%3A%20%22-07%3A00%22%2C%0A%20%20%20%20%22isCumulative%22%3A%20false%2C%0A%20%20%20%20%22adSpend%22%3A%20%7B%0A%20%20%20%20%20%20%22currencyCode%22%3A%20%22CAD%22%2C%0A%20%20%20%20%20%20%22amount%22%3A%20%2219.90%22%0A%20%20%20%20%7D%2C%0A%20%20%20%20%22impressionsCount%22%3A%20100%2C%0A%20%20%20%20%22clicksCount%22%3A%2040%2C%0A%20%20%20%20%22commentsCount%22%3A%201%2C%0A%20%20%20%20%22unsubscribesCount%22%3A%201%2C%0A%20%20%20%20%22complaintsCount%22%3A%201%2C%0A%20%20%20%20%22failsCount%22%3A%201%2C%0A%20%20%20%20%22sendsCount%22%3A%201%2C%0A%20%20%20%20%22uniqueViewsCount%22%3A%201%2C%0A%20%20%20%20%22uniqueClicksCount%22%3A%201%2C%0A%20%20%20%20%22sharesCount%22%3A%205%2C%0A%20%20%20%20%22viewsCount%22%3A%2010%2C%0A%20%20%20%20%22favoritesCount%22%3A%200%2C%0A%20%20%20%20%22sessionsCount%22%3A%2040%2C%0A%20%20%20%20%22sales%22%3A%20%7B%0A%20%20%20%20%20%20%22amount%22%3A%20%22304.50%22%2C%0A%20%20%20%20%20%20%22currencyCode%22%3A%20%22CAD%22%0A%20%20%20%20%7D%2C%0A%20%20%20%20%22orders%22%3A%208%2C%0A%20%20%20%20%22firstTimeCustomers%22%3A%205%2C%0A%20%20%20%20%22returningCustomers%22%3A%203%0A%20%20%7D%2C%0A%20%20%22marketingActivityId%22%3A%20%22gid%3A%2F%2Fshopify%2FMarketingActivity%2F794355127%22%2C%0A%20%20%22channelHandle%22%3A%20null%2C%0A%20%20%22remoteId%22%3A%20null%0A%7D) ```javascript const { admin } = await authenticate.admin(request); const response = await admin.graphql( `#graphql 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 } } }`, { variables: { "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, "returningCustomers": 3 }, "marketingActivityId": "gid://shopify/MarketingActivity/794355127", "channelHandle": null, "remoteId": null }, }, ); const data = await response.json(); ``` ## Input variables JSON ```json { "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, "returningCustomers": 3 }, "marketingActivityId": "gid://shopify/MarketingActivity/794355127", "channelHandle": null, "remoteId": null } ``` ## Response JSON ```json { "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": [] } } ```