# 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": []
    }
  }
}