--- title: marketingActivityCreateExternal - GraphQL Admin description: Creates a new external marketing activity. api_version: 2025-10 api_name: admin type: mutation api_type: graphql source_url: html: https://shopify.dev/docs/api/admin-graphql/latest/mutations/marketingActivityCreateExternal md: https://shopify.dev/docs/api/admin-graphql/latest/mutations/marketingActivityCreateExternal.md --- # marketing​Activity​Create​External mutation Requires `write_marketing_events` access scope. Creates a new external marketing activity. ## Arguments * input [Marketing​Activity​Create​External​Input!](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/MarketingActivityCreateExternalInput) required The input field for creating an external marketing activity. *** ## Marketing​Activity​Create​External​Payload returns * marketing​Activity [Marketing​Activity](https://shopify.dev/docs/api/admin-graphql/latest/objects/MarketingActivity) The external marketing activity that was created. * user​Errors [\[Marketing​Activity​User​Error!\]!](https://shopify.dev/docs/api/admin-graphql/latest/objects/MarketingActivityUserError) non-null The list of errors that occurred from executing the mutation. *** ## 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 ```graphql mutation marketingActivityCreateExternal($createInput: MarketingActivityCreateExternalInput!) { marketingActivityCreateExternal(input: $createInput) { marketingActivity { id } } } ``` #### 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" } } ``` #### cURL ```bash curl -X POST \ https://your-development-store.myshopify.com/admin/api/2025-10/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 ```javascript 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 ```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 ```javascript 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" } }, }, }); ``` #### Response ```json { "marketingActivityCreateExternal": { "marketingActivity": { "id": "gid://shopify/MarketingActivity/1063897621" } } } ``` * ### Creates a marketing event #### Query ```graphql mutation MarketingCreateEvent($input: MarketingActivityCreateExternalInput!) { marketingActivityCreateExternal(input: $input) { marketingActivity { id marketingEvent { id type startedAt utmCampaign utmMedium utmSource marketingChannelType } } } } ``` #### Variables ```json { "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 ```bash curl -X POST \ https://your-development-store.myshopify.com/admin/api/2025-10/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 ```javascript 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 ```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 ```javascript 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" } }, }, }); ``` #### Response ```json { "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 [Open in GraphiQL](http://localhost:3457/graphiql?query=mutation%20marketingActivityCreateExternal\(%24createInput%3A%20MarketingActivityCreateExternalInput!\)%20%7B%0A%20%20marketingActivityCreateExternal\(input%3A%20%24createInput\)%20%7B%0A%20%20%20%20marketingActivity%20%7B%0A%20%20%20%20%20%20id%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D\&variables=%7B%0A%20%20%22createInput%22%3A%20%7B%0A%20%20%20%20%22remoteId%22%3A%20%22fake_id%22%2C%0A%20%20%20%20%22title%22%3A%20%22New%20Title%22%2C%0A%20%20%20%20%22remoteUrl%22%3A%20%22https%3A%2F%2Fexample.com%22%2C%0A%20%20%20%20%22remotePreviewImageUrl%22%3A%20%22https%3A%2F%2Fexample.com%22%2C%0A%20%20%20%20%22status%22%3A%20%22ACTIVE%22%2C%0A%20%20%20%20%22utm%22%3A%20%7B%0A%20%20%20%20%20%20%22source%22%3A%20%22email%22%2C%0A%20%20%20%20%20%20%22medium%22%3A%20%22newsletter%22%2C%0A%20%20%20%20%20%20%22campaign%22%3A%20%22external-campaign%22%0A%20%20%20%20%7D%2C%0A%20%20%20%20%22tactic%22%3A%20%22NEWSLETTER%22%2C%0A%20%20%20%20%22marketingChannelType%22%3A%20%22EMAIL%22%0A%20%20%7D%0A%7D) ```javascript 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; } ``` ##### GQL ``` mutation marketingActivityCreateExternal($createInput: MarketingActivityCreateExternalInput!) { marketingActivityCreateExternal(input: $createInput) { marketingActivity { id } } } ``` ##### cURL ``` curl -X POST \ https://your-development-store.myshopify.com/admin/api/2025-10/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) ``` ## Input variables JSON ```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 ```json { "marketingActivityCreateExternal": { "marketingActivity": { "id": "gid://shopify/MarketingActivity/1063897621" } } } ```