Choose a version:

Anchor to marketingActivityCreateExternal

marketingActivityCreateExternal

mutation

Requires write_marketing_events access scope.

Creates a new external marketing activity.

Anchor to Arguments

Arguments

Anchor to inputinput

•MarketingActivityCreateExternalInput!

required

The input field for creating an external marketing activity.

Was this section helpful?

Anchor to MarketingActivityCreateExternalPayload returnsMarketingActivityCreateExternalPayload returns

Anchor to marketingActivitymarketingActivity •MarketingActivity: The external marketing activity that was created.
Anchor to userErrorsuserErrors •[MarketingActivityUserError!]! non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Examples

Create an external marketing activity with a status

Description

Starting from API version 2024-01, the status field for creating an external marketing activity will be an optional, modifiable field.

Query

mutation marketingActivityCreateExternal($createInput: MarketingActivityCreateExternalInput!) {
  marketingActivityCreateExternal(input: $createInput) {
    marketingActivity {
      id
    }
  }
}

Variables

{
  "createInput": {
    "remoteId": "fake_id",
    "title": "New Title",
    "remoteUrl": "https://example.com",
    "remotePreviewImageUrl": "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 marketingActivityCreateExternal($createInput: MarketingActivityCreateExternalInput!) { marketingActivityCreateExternal(input: $createInput) { marketingActivity { id } } }",
 "variables": {
    "createInput": {
      "remoteId": "fake_id",
      "title": "New Title",
      "remoteUrl": "https://example.com",
      "remotePreviewImageUrl": "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 marketingActivityCreateExternal($createInput: MarketingActivityCreateExternalInput!) {
    marketingActivityCreateExternal(input: $createInput) {
      marketingActivity {
        id
      }
    }
  }`,
  {
    variables: {
        "createInput": {
            "remoteId": "fake_id",
            "title": "New Title",
            "remoteUrl": "https://example.com",
            "remotePreviewImageUrl": "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 marketingActivityCreateExternal($createInput: MarketingActivityCreateExternalInput!) {
    marketingActivityCreateExternal(input: $createInput) {
      marketingActivity {
        id
      }
    }
  }
QUERY

variables = {
  "createInput": {
    "remoteId": "fake_id",
    "title": "New Title",
    "remoteUrl": "https://example.com",
    "remotePreviewImageUrl": "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 marketingActivityCreateExternal($createInput: MarketingActivityCreateExternalInput!) {
      marketingActivityCreateExternal(input: $createInput) {
        marketingActivity {
          id
        }
      }
    }`,
    "variables": {
        "createInput": {
            "remoteId": "fake_id",
            "title": "New Title",
            "remoteUrl": "https://example.com",
            "remotePreviewImageUrl": "https://example.com",
            "status": "ACTIVE",
            "utm": {
                "source": "email",
                "medium": "newsletter",
                "campaign": "external-campaign"
            },
            "tactic": "NEWSLETTER",
            "marketingChannelType": "EMAIL"
        }
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation marketingActivityCreateExternal($createInput: MarketingActivityCreateExternalInput!) {
  marketingActivityCreateExternal(input: $createInput) {
    marketingActivity {
      id
    }
  }
}' \
--variables \
'{
  "createInput": {
    "remoteId": "fake_id",
    "title": "New Title",
    "remoteUrl": "https://example.com",
    "remotePreviewImageUrl": "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 marketingActivityCreateExternal($createInput: MarketingActivityCreateExternalInput!) {
        marketingActivityCreateExternal(input: $createInput) {
          marketingActivity {
            id
          }
        }
      }
    `,
    variables: {
        "createInput": {
            "remoteId": "fake_id",
            "title": "New Title",
            "remoteUrl": "https://example.com",
            "remotePreviewImageUrl": "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

{
  "marketingActivityCreateExternal": {
    "marketingActivity": {
      "id": "gid://shopify/MarketingActivity/1063897621"
    }
  }
}

Creates a marketing event

Query

mutation MarketingCreateEvent($input: MarketingActivityCreateExternalInput!) {
  marketingActivityCreateExternal(input: $input) {
    marketingActivity {
      id
      marketingEvent {
        id
        type
        startedAt
        utmCampaign
        utmMedium
        utmSource
        marketingChannelType
      }
    }
  }
}

Variables

{
  "input": {
    "remoteId": "fake_id",
    "title": "New Marketing Event",
    "remoteUrl": "https://example.com",
    "remotePreviewImageUrl": "https://example.com",
    "utm": {
      "source": "source",
      "medium": "medium",
      "campaign": "campaign"
    },
    "marketingChannelType": "SOCIAL",
    "tactic": "POST"
  }
}

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 MarketingCreateEvent($input: MarketingActivityCreateExternalInput!) { marketingActivityCreateExternal(input: $input) { marketingActivity { id marketingEvent { id type startedAt utmCampaign utmMedium utmSource marketingChannelType } } } }",
 "variables": {
    "input": {
      "remoteId": "fake_id",
      "title": "New Marketing Event",
      "remoteUrl": "https://example.com",
      "remotePreviewImageUrl": "https://example.com",
      "utm": {
        "source": "source",
        "medium": "medium",
        "campaign": "campaign"
      },
      "marketingChannelType": "SOCIAL",
      "tactic": "POST"
    }
  }
}'

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 MarketingCreateEvent($input: MarketingActivityCreateExternalInput!) {
    marketingActivityCreateExternal(input: $input) {
      marketingActivity {
        id
        marketingEvent {
          id
          type
          startedAt
          utmCampaign
          utmMedium
          utmSource
          marketingChannelType
        }
      }
    }
  }`,
  {
    variables: {
        "input": {
            "remoteId": "fake_id",
            "title": "New Marketing Event",
            "remoteUrl": "https://example.com",
            "remotePreviewImageUrl": "https://example.com",
            "utm": {
                "source": "source",
                "medium": "medium",
                "campaign": "campaign"
            },
            "marketingChannelType": "SOCIAL",
            "tactic": "POST"
        }
    },
  },
  );
  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 MarketingCreateEvent($input: MarketingActivityCreateExternalInput!) {
    marketingActivityCreateExternal(input: $input) {
      marketingActivity {
        id
        marketingEvent {
          id
          type
          startedAt
          utmCampaign
          utmMedium
          utmSource
          marketingChannelType
        }
      }
    }
  }
QUERY

variables = {
  "input": {
    "remoteId": "fake_id",
    "title": "New Marketing Event",
    "remoteUrl": "https://example.com",
    "remotePreviewImageUrl": "https://example.com",
    "utm": {
      "source": "source",
      "medium": "medium",
      "campaign": "campaign"
    },
    "marketingChannelType": "SOCIAL",
    "tactic": "POST"
  }
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation MarketingCreateEvent($input: MarketingActivityCreateExternalInput!) {
      marketingActivityCreateExternal(input: $input) {
        marketingActivity {
          id
          marketingEvent {
            id
            type
            startedAt
            utmCampaign
            utmMedium
            utmSource
            marketingChannelType
          }
        }
      }
    }`,
    "variables": {
        "input": {
            "remoteId": "fake_id",
            "title": "New Marketing Event",
            "remoteUrl": "https://example.com",
            "remotePreviewImageUrl": "https://example.com",
            "utm": {
                "source": "source",
                "medium": "medium",
                "campaign": "campaign"
            },
            "marketingChannelType": "SOCIAL",
            "tactic": "POST"
        }
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation MarketingCreateEvent($input: MarketingActivityCreateExternalInput!) {
  marketingActivityCreateExternal(input: $input) {
    marketingActivity {
      id
      marketingEvent {
        id
        type
        startedAt
        utmCampaign
        utmMedium
        utmSource
        marketingChannelType
      }
    }
  }
}' \
--variables \
'{
  "input": {
    "remoteId": "fake_id",
    "title": "New Marketing Event",
    "remoteUrl": "https://example.com",
    "remotePreviewImageUrl": "https://example.com",
    "utm": {
      "source": "source",
      "medium": "medium",
      "campaign": "campaign"
    },
    "marketingChannelType": "SOCIAL",
    "tactic": "POST"
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation MarketingCreateEvent($input: MarketingActivityCreateExternalInput!) {
        marketingActivityCreateExternal(input: $input) {
          marketingActivity {
            id
            marketingEvent {
              id
              type
              startedAt
              utmCampaign
              utmMedium
              utmSource
              marketingChannelType
            }
          }
        }
      }
    `,
    variables: {
        "input": {
            "remoteId": "fake_id",
            "title": "New Marketing Event",
            "remoteUrl": "https://example.com",
            "remotePreviewImageUrl": "https://example.com",
            "utm": {
                "source": "source",
                "medium": "medium",
                "campaign": "campaign"
            },
            "marketingChannelType": "SOCIAL",
            "tactic": "POST"
        }
    },
  }),
});

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

Response

{
  "marketingActivityCreateExternal": {
    "marketingActivity": {
      "id": "gid://shopify/MarketingActivity/1063897614",
      "marketingEvent": {
        "id": "gid://shopify/MarketingEvent/1069064164",
        "type": "POST",
        "startedAt": "2024-11-18T22:43:21Z",
        "utmCampaign": "campaign",
        "utmMedium": "medium",
        "utmSource": "source",
        "marketingChannelType": "SOCIAL"
      }
    }
  }
}

marketingActivityCreateExternal reference

Examples

Open in GraphiQL

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

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

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(

`#graphql

mutation marketingActivityCreateExternal($createInput: MarketingActivityCreateExternalInput!) {

marketingActivityCreateExternal(input: $createInput) {

marketingActivity {

}

}`,

{

variables: {

"createInput": {

"remoteId": "fake_id",

"title": "New Title",

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

"remotePreviewImageUrl": "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 marketingActivityCreateExternal($createInput: MarketingActivityCreateExternalInput!) {
  marketingActivityCreateExternal(input: $createInput) {
    marketingActivity {
      id
    }
  }
}

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 marketingActivityCreateExternal($createInput: MarketingActivityCreateExternalInput!) { marketingActivityCreateExternal(input: $createInput) { marketingActivity { id } } }",
 "variables": {
    "createInput": {
      "remoteId": "fake_id",
      "title": "New Title",
      "remoteUrl": "https://example.com",
      "remotePreviewImageUrl": "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 marketingActivityCreateExternal($createInput: MarketingActivityCreateExternalInput!) {
    marketingActivityCreateExternal(input: $createInput) {
      marketingActivity {
        id
      }
    }
  }`,
  {
    variables: {
        "createInput": {
            "remoteId": "fake_id",
            "title": "New Title",
            "remoteUrl": "https://example.com",
            "remotePreviewImageUrl": "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;
}

Node.js

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

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 marketingActivityCreateExternal($createInput: MarketingActivityCreateExternalInput!) {
    marketingActivityCreateExternal(input: $createInput) {
      marketingActivity {
        id
      }
    }
  }
QUERY

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

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

Shopify CLI

shopify app execute \
--query \
'mutation marketingActivityCreateExternal($createInput: MarketingActivityCreateExternalInput!) {
  marketingActivityCreateExternal(input: $createInput) {
    marketingActivity {
      id
    }
  }
}' \
--variables \
'{
  "createInput": {
    "remoteId": "fake_id",
    "title": "New Title",
    "remoteUrl": "https://example.com",
    "remotePreviewImageUrl": "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 marketingActivityCreateExternal($createInput: MarketingActivityCreateExternalInput!) {
        marketingActivityCreateExternal(input: $createInput) {
          marketingActivity {
            id
          }
        }
      }
    `,
    variables: {
        "createInput": {
            "remoteId": "fake_id",
            "title": "New Title",
            "remoteUrl": "https://example.com",
            "remotePreviewImageUrl": "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);

Input variables

JSON

{

"createInput": {

"remoteId": "fake_id",

"title": "New Title",

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

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

"status": "ACTIVE",

"utm": {

"source": "email",

"medium": "newsletter",

"campaign": "external-campaign"

"tactic": "NEWSLETTER",

"marketingChannelType": "EMAIL"

}

Response

JSON

{

"marketingActivityCreateExternal": {

"marketingActivity": {

"id": "gid://shopify/MarketingActivity/1063897621"

}