Choose a version:

Anchor to marketingActivityUpsertExternal

marketingActivityUpsertExternal

mutation

Requires write_marketing_events access scope.

Creates a new external marketing activity or updates an existing one. When optional fields are absent or null, associated information will be removed from an existing marketing activity.

Anchor to Arguments

Arguments

Anchor to inputinput

•MarketingActivityUpsertExternalInput!

required

The input field for creating or updating an external marketing activity.

Show input fields

Was this section helpful?

Anchor to MarketingActivityUpsertExternalPayload returnsMarketingActivityUpsertExternalPayload returns

Anchor to marketingActivitymarketingActivity •MarketingActivity: The external marketing activity that was created or updated.

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

Upsert (create or update) an external marketing activity

Query

mutation marketingActivityUpsertExternal($input: MarketingActivityUpsertExternalInput!) {
  marketingActivityUpsertExternal(input: $input) {
    marketingActivity {
      id
    }
  }
}

Variables

{
  "input": {
    "remoteId": "A unique identifier",
    "title": "New Title",
    "remoteUrl": "https://example.com",
    "status": "ACTIVE",
    "utm": {
      "source": "email",
      "medium": "newsletter",
      "campaign": "external-campaign"
    },
    "tactic": "NEWSLETTER",
    "marketingChannelType": "EMAIL"
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation marketingActivityUpsertExternal($input: MarketingActivityUpsertExternalInput!) { marketingActivityUpsertExternal(input: $input) { marketingActivity { id } } }",
 "variables": {
    "input": {
      "remoteId": "A unique identifier",
      "title": "New Title",
      "remoteUrl": "https://example.com",
      "status": "ACTIVE",
      "utm": {
        "source": "email",
        "medium": "newsletter",
        "campaign": "external-campaign"
      },
      "tactic": "NEWSLETTER",
      "marketingChannelType": "EMAIL"
    }
  }
}'

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 marketingActivityUpsertExternal($input: MarketingActivityUpsertExternalInput!) {
    marketingActivityUpsertExternal(input: $input) {
      marketingActivity {
        id
      }
    }
  }`,
  {
    variables: {
        "input": {
            "remoteId": "A unique identifier",
            "title": "New Title",
            "remoteUrl": "https://example.com",
            "status": "ACTIVE",
            "utm": {
                "source": "email",
                "medium": "newsletter",
                "campaign": "external-campaign"
            },
            "tactic": "NEWSLETTER",
            "marketingChannelType": "EMAIL"
        }
    },
  },
  );
  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 marketingActivityUpsertExternal($input: MarketingActivityUpsertExternalInput!) {
    marketingActivityUpsertExternal(input: $input) {
      marketingActivity {
        id
      }
    }
  }
QUERY

variables = {
  "input": {
    "remoteId": "A unique identifier",
    "title": "New Title",
    "remoteUrl": "https://example.com",
    "status": "ACTIVE",
    "utm": {
      "source": "email",
      "medium": "newsletter",
      "campaign": "external-campaign"
    },
    "tactic": "NEWSLETTER",
    "marketingChannelType": "EMAIL"
  }
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation marketingActivityUpsertExternal($input: MarketingActivityUpsertExternalInput!) {
      marketingActivityUpsertExternal(input: $input) {
        marketingActivity {
          id
        }
      }
    }`,
    "variables": {
        "input": {
            "remoteId": "A unique identifier",
            "title": "New Title",
            "remoteUrl": "https://example.com",
            "status": "ACTIVE",
            "utm": {
                "source": "email",
                "medium": "newsletter",
                "campaign": "external-campaign"
            },
            "tactic": "NEWSLETTER",
            "marketingChannelType": "EMAIL"
        }
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation marketingActivityUpsertExternal($input: MarketingActivityUpsertExternalInput!) {
  marketingActivityUpsertExternal(input: $input) {
    marketingActivity {
      id
    }
  }
}' \
--variables \
'{
  "input": {
    "remoteId": "A unique identifier",
    "title": "New Title",
    "remoteUrl": "https://example.com",
    "status": "ACTIVE",
    "utm": {
      "source": "email",
      "medium": "newsletter",
      "campaign": "external-campaign"
    },
    "tactic": "NEWSLETTER",
    "marketingChannelType": "EMAIL"
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation marketingActivityUpsertExternal($input: MarketingActivityUpsertExternalInput!) {
        marketingActivityUpsertExternal(input: $input) {
          marketingActivity {
            id
          }
        }
      }
    `,
    variables: {
        "input": {
            "remoteId": "A unique identifier",
            "title": "New Title",
            "remoteUrl": "https://example.com",
            "status": "ACTIVE",
            "utm": {
                "source": "email",
                "medium": "newsletter",
                "campaign": "external-campaign"
            },
            "tactic": "NEWSLETTER",
            "marketingChannelType": "EMAIL"
        }
    },
  }),
});

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

Response

{
  "marketingActivityUpsertExternal": {
    "marketingActivity": {
      "id": "gid://shopify/MarketingActivity/1063897336"
    }
  }
}

marketingActivityUpsertExternal 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 marketingActivityUpsertExternal($input: MarketingActivityUpsertExternalInput!) {

marketingActivityUpsertExternal(input: $input) {

marketingActivity {

}

}`,

{

variables: {

"input": {

"remoteId": "A unique identifier",

"title": "New Title",

"remoteUrl": "https://example.com",

"status": "ACTIVE",

"utm": {

"source": "email",

"medium": "newsletter",

"campaign": "external-campaign"

"tactic": "NEWSLETTER",

"marketingChannelType": "EMAIL"

}

);

const json = await response.json();

return json.data;

}

GQL

mutation marketingActivityUpsertExternal($input: MarketingActivityUpsertExternalInput!) {
  marketingActivityUpsertExternal(input: $input) {
    marketingActivity {
      id
    }
  }
}