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

1const { admin } = await authenticate.admin(request);
2
3const response = await admin.graphql(
4  `#graphql
5  mutation M($marketingEngagement: MarketingEngagementInput!, $marketingActivityId: ID, $channelHandle: String, $remoteId: String) {
6    marketingEngagementCreate(marketingEngagement: $marketingEngagement, marketingActivityId: $marketingActivityId, channelHandle: $channelHandle, remoteId: $remoteId) {
7      marketingEngagement {
8        occurredOn
9        utcOffset
10        isCumulative
11        adSpend {
12          amount
13          currencyCode
14        }
15        clicksCount
16        impressionsCount
17        commentsCount
18        favoritesCount
19        unsubscribesCount
20        complaintsCount
21        failsCount
22        sendsCount
23        uniqueViewsCount
24        uniqueClicksCount
25        sharesCount
26        viewsCount
27        sessionsCount
28        sales {
29          amount
30          currencyCode
31        }
32        orders
33        firstTimeCustomers
34        returningCustomers
35        marketingActivity {
36          id
37        }
38        channelHandle
39      }
40      userErrors {
41        field
42        message
43      }
44    }
45  }`,
46  {
47    variables: {
48      "marketingEngagement": {
49        "occurredOn": "2018-06-29",
50        "utcOffset": "-07:00",
51        "isCumulative": false,
52        "adSpend": {
53          "currencyCode": "CAD",
54          "amount": "19.90"
55        },
56        "impressionsCount": 100,
57        "clicksCount": 40,
58        "commentsCount": 1,
59        "unsubscribesCount": 1,
60        "complaintsCount": 1,
61        "failsCount": 1,
62        "sendsCount": 1,
63        "uniqueViewsCount": 1,
64        "uniqueClicksCount": 1,
65        "sharesCount": 5,
66        "viewsCount": 10,
67        "favoritesCount": 0,
68        "sessionsCount": 40,
69        "sales": {
70          "amount": "304.50",
71          "currencyCode": "CAD"
72        },
73        "orders": 8,
74        "firstTimeCustomers": 5.0,
75        "returningCustomers": 3.0
76      },
77      "marketingActivityId": "gid://shopify/MarketingActivity/794355127",
78      "channelHandle": null,
79      "remoteId": null
80    },
81  },
82);
83
84const data = await response.json();
85

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-04/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

1{
2  "marketingEngagement": {
3    "occurredOn": "2018-06-29",
4    "utcOffset": "-07:00",
5    "isCumulative": false,
6    "adSpend": {
7      "currencyCode": "CAD",
8      "amount": "19.90"
9    },
10    "impressionsCount": 100,
11    "clicksCount": 40,
12    "commentsCount": 1,
13    "unsubscribesCount": 1,
14    "complaintsCount": 1,
15    "failsCount": 1,
16    "sendsCount": 1,
17    "uniqueViewsCount": 1,
18    "uniqueClicksCount": 1,
19    "sharesCount": 5,
20    "viewsCount": 10,
21    "favoritesCount": 0,
22    "sessionsCount": 40,
23    "sales": {
24      "amount": "304.50",
25      "currencyCode": "CAD"
26    },
27    "orders": 8,
28    "firstTimeCustomers": 5,
29    "returningCustomers": 3
30  },
31  "marketingActivityId": "gid://shopify/MarketingActivity/794355127",
32  "channelHandle": null,
33  "remoteId": null
34}

Response

JSON

1{
2  "marketingEngagementCreate": {
3    "marketingEngagement": {
4      "occurredOn": "2018-06-29",
5      "utcOffset": "-07:00",
6      "isCumulative": false,
7      "adSpend": {
8        "amount": "19.9",
9        "currencyCode": "CAD"
10      },
11      "clicksCount": 40,
12      "impressionsCount": 100,
13      "commentsCount": 1,
14      "favoritesCount": 0,
15      "unsubscribesCount": 1,
16      "complaintsCount": 1,
17      "failsCount": 1,
18      "sendsCount": 1,
19      "uniqueViewsCount": 1,
20      "uniqueClicksCount": 1,
21      "sharesCount": 5,
22      "viewsCount": 10,
23      "sessionsCount": 40,
24      "sales": {
25        "amount": "304.5",
26        "currencyCode": "CAD"
27      },
28      "orders": "8.0",
29      "firstTimeCustomers": "5.0",
30      "returningCustomers": "3.0",
31      "marketingActivity": {
32        "id": "gid://shopify/MarketingActivity/794355127"
33      },
34      "channelHandle": null
35    },
36    "userErrors": []
37  }
38}