Choose a version:

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: 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.

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

Open in GraphiQL

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 {

}

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();

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/2024-07/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

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

}