marketingEngagementCreate

mutation

Requires write_marketing_events access scope.

Creates a new marketing engagement for a marketing activity or a marketing channel.

Arguments

Anchor to channelHandlechannelHandle • 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.
Anchor to marketingActivityIdmarketingActivityId • 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.
Anchor to marketingEngagementmarketingEngagement • MarketingEngagementInput!required: The marketing engagement's attributes.
Anchor to remoteIdremoteId • 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.

Was this section helpful?

Anchor to MarketingEngagementCreatePayload returnsMarketingEngagementCreatePayload returns

Anchor to marketingEngagementmarketingEngagement • MarketingEngagement: The marketing engagement that was created. This represents customer activity taken on a marketing activity or a marketing channel.
Anchor to userErrorsuserErrors • [MarketingActivityUserError!]!non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Create activity-level engagement for a marketing activity ID
Create activity-level engagement with a remote ID
Create channel-level engagement for a channel handle
Creates marketing engagements on a marketing event
marketingEngagementCreate reference

Examples

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

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
    }
  }
}

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-01/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.0,
      "returningCustomers": 3.0
    },
    "marketingActivityId": "gid://shopify/MarketingActivity/794355127",
    "channelHandle": null,
    "remoteId": null
  }
}'

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.0,
        "returningCustomers": 3.0
      },
      "marketingActivityId": "gid://shopify/MarketingActivity/794355127",
      "channelHandle": null,
      "remoteId": null
    },
  },
);

const data = await response.json();

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.0,
        "returningCustomers": 3.0
      },
      "marketingActivityId": "gid://shopify/MarketingActivity/794355127",
      "channelHandle": null,
      "remoteId": null
    },
  },
});

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.0,
    "returningCustomers": 3.0
  },
  "marketingActivityId": "gid://shopify/MarketingActivity/794355127",
  "channelHandle": nil,
  "remoteId": nil
}

response = client.query(query: query, variables: variables)

Input 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

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"