Choose a version:

marketingEngagementCreate

mutation

Requires write_marketing_events access scope.

Creates a new marketing engagement for a marketing activity.

Arguments

Anchor to marketingActivityIdmarketingActivityId

•ID

The identifier of the marketing activity for which the engagement metrics are being provided. Exactly one of marketingActivityId, remoteId, or the deprecated channelHandle must be set.

Anchor to marketingEngagementmarketingEngagement

•MarketingEngagementInput!

required

The marketing engagement's attributes.

Show input fields

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. Exactly one of marketingActivityId, remoteId, or the deprecated channelHandle must be set.

Anchor to channelHandlechannelHandle

•String

Deprecated

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.

Show fields
Anchor to userErrorsuserErrors •[MarketingActivityUserError!]! non-null: The list of errors that occurred from executing the mutation.

Show fields

Was this section helpful?

Examples

Create activity-level engagement for a marketing activity ID

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
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-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
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  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 json = await response.json();
  return json.data;
}

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

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
    },
  },
});

Shopify CLI

shopify app execute \
--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
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-10/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    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
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

{
  "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

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

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-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"
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  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 json = await response.json();
  return json.data;
}

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

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"
    },
  },
});

Shopify CLI

shopify app execute \
--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"
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-10/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    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"
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

{
  "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 conversion metrics for a marketing activity ID

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
      primaryConversions
      allConversions
      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,
    "primaryConversions": 8,
    "allConversions": 40
  },
  "marketingActivityId": "gid://shopify/MarketingActivity/794355127",
  "channelHandle": null,
  "remoteId": null
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-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 primaryConversions allConversions 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,
      "primaryConversions": 8,
      "allConversions": 40
    },
    "marketingActivityId": "gid://shopify/MarketingActivity/794355127",
    "channelHandle": null,
    "remoteId": null
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  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
        primaryConversions
        allConversions
        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,
            "primaryConversions": 8,
            "allConversions": 40
        },
        "marketingActivityId": "gid://shopify/MarketingActivity/794355127",
        "channelHandle": null,
        "remoteId": null
    },
  },
  );
  const json = await response.json();
  return json.data;
}

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
        primaryConversions
        allConversions
        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,
    "primaryConversions": 8,
    "allConversions": 40
  },
  "marketingActivityId": "gid://shopify/MarketingActivity/794355127",
  "channelHandle": null,
  "remoteId": null
}

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

Node.js

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
          primaryConversions
          allConversions
          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,
            "primaryConversions": 8,
            "allConversions": 40
        },
        "marketingActivityId": "gid://shopify/MarketingActivity/794355127",
        "channelHandle": null,
        "remoteId": null
    },
  },
});

Shopify CLI

shopify app execute \
--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
      primaryConversions
      allConversions
      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,
    "primaryConversions": 8,
    "allConversions": 40
  },
  "marketingActivityId": "gid://shopify/MarketingActivity/794355127",
  "channelHandle": null,
  "remoteId": null
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-10/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    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
            primaryConversions
            allConversions
            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,
            "primaryConversions": 8,
            "allConversions": 40
        },
        "marketingActivityId": "gid://shopify/MarketingActivity/794355127",
        "channelHandle": null,
        "remoteId": null
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

{
  "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",
      "primaryConversions": "8.0",
      "allConversions": "40.0",
      "marketingActivity": {
        "id": "gid://shopify/MarketingActivity/794355127"
      },
      "channelHandle": null
    },
    "userErrors": []
  }
}

Create activity-level engagement with conversion metrics with a remote ID

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
      primaryConversions
      allConversions
      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,
    "primaryConversions": 8,
    "allConversions": 40
  },
  "marketingActivityId": null,
  "channelHandle": null,
  "remoteId": "1234:5678"
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-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 primaryConversions allConversions 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,
      "primaryConversions": 8,
      "allConversions": 40
    },
    "marketingActivityId": null,
    "channelHandle": null,
    "remoteId": "1234:5678"
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  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
        primaryConversions
        allConversions
        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,
            "primaryConversions": 8,
            "allConversions": 40
        },
        "marketingActivityId": null,
        "channelHandle": null,
        "remoteId": "1234:5678"
    },
  },
  );
  const json = await response.json();
  return json.data;
}

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
        primaryConversions
        allConversions
        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,
    "primaryConversions": 8,
    "allConversions": 40
  },
  "marketingActivityId": null,
  "channelHandle": null,
  "remoteId": "1234:5678"
}

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

Node.js

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
          primaryConversions
          allConversions
          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,
            "primaryConversions": 8,
            "allConversions": 40
        },
        "marketingActivityId": null,
        "channelHandle": null,
        "remoteId": "1234:5678"
    },
  },
});

Shopify CLI

shopify app execute \
--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
      primaryConversions
      allConversions
      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,
    "primaryConversions": 8,
    "allConversions": 40
  },
  "marketingActivityId": null,
  "channelHandle": null,
  "remoteId": "1234:5678"
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-10/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    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
            primaryConversions
            allConversions
            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,
            "primaryConversions": 8,
            "allConversions": 40
        },
        "marketingActivityId": null,
        "channelHandle": null,
        "remoteId": "1234:5678"
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

{
  "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",
      "primaryConversions": "8.0",
      "allConversions": "40.0",
      "marketingActivity": {
        "id": "gid://shopify/MarketingActivity/794355127"
      },
      "channelHandle": null
    },
    "userErrors": []
  }
}

Create channel-level engagement for a channel handle

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
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-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
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  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 json = await response.json();
  return json.data;
}

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

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
    },
  },
});

Shopify CLI

shopify app execute \
--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
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-10/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    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
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

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

Create channel-level engagement with conversion metrics for a channel handle

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
      primaryConversions
      allConversions
      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,
    "primaryConversions": 8,
    "allConversions": 40
  },
  "marketingActivityId": null,
  "channelHandle": "my-channel-handle",
  "remoteId": null
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-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 primaryConversions allConversions 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,
      "primaryConversions": 8,
      "allConversions": 40
    },
    "marketingActivityId": null,
    "channelHandle": "my-channel-handle",
    "remoteId": null
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  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
        primaryConversions
        allConversions
        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,
            "primaryConversions": 8,
            "allConversions": 40
        },
        "marketingActivityId": null,
        "channelHandle": "my-channel-handle",
        "remoteId": null
    },
  },
  );
  const json = await response.json();
  return json.data;
}

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
        primaryConversions
        allConversions
        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,
    "primaryConversions": 8,
    "allConversions": 40
  },
  "marketingActivityId": null,
  "channelHandle": "my-channel-handle",
  "remoteId": null
}

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

Node.js

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
          primaryConversions
          allConversions
          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,
            "primaryConversions": 8,
            "allConversions": 40
        },
        "marketingActivityId": null,
        "channelHandle": "my-channel-handle",
        "remoteId": null
    },
  },
});

Shopify CLI

shopify app execute \
--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
      primaryConversions
      allConversions
      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,
    "primaryConversions": 8,
    "allConversions": 40
  },
  "marketingActivityId": null,
  "channelHandle": "my-channel-handle",
  "remoteId": null
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-10/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    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
            primaryConversions
            allConversions
            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,
            "primaryConversions": 8,
            "allConversions": 40
        },
        "marketingActivityId": null,
        "channelHandle": "my-channel-handle",
        "remoteId": null
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

{
  "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",
      "primaryConversions": "8.0",
      "allConversions": "40.0",
      "marketingActivity": null,
      "channelHandle": "my-channel-handle"
    },
    "userErrors": []
  }
}

marketingEngagementCreate reference

Examples

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {

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,

"returningCustomers": 3

"marketingActivityId": "gid://shopify/MarketingActivity/794355127",

"channelHandle": null,

"remoteId": null

);

const json = await response.json();

return json.data;

}

GQL

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

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-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
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  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 json = await response.json();
  return json.data;
}

Node.js

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
    },
  },
});

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)

Shopify CLI

shopify app execute \
--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
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-10/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    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
    },
  }),
});

const { data } = await response.json();
console.log(data);

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

}