Choose a version:

webPixelCreate

mutation

Requires write_pixels access scope. Also: The app requires read_customer_events access scope and user access permission.

Activate a web pixel extension by creating a web pixel record on the store where you installed your app.

When you run the webPixelCreate mutation, Shopify validates it against the settings definition in shopify.extension.toml. If the settings input field doesn't match the schema that you defined, then the mutation fails. Learn how to define web pixel settings.

Anchor to Arguments

Arguments

Anchor to webPixelwebPixel •WebPixelInput! required: The web pixel settings in JSON format.

Was this section helpful?

Anchor to WebPixelCreatePayload returnsWebPixelCreatePayload returns

Anchor to userErrorsuserErrors •[ErrorsWebPixelUserError!]! non-null: The list of errors that occurred from executing the mutation.
Anchor to webPixelwebPixel •WebPixel: The created web pixel settings.

Was this section helpful?

Examples

Create a web pixel

Description

Create a [web pixel](https://shopify.dev/docs/apps/build/marketing-analytics/build-web-pixels) record on the store where you installed your app. The settings must match the schema defined in your extension's `shopify.extension.toml` file.

Query

mutation webPixelCreate($webPixel: WebPixelInput!) {
  webPixelCreate(webPixel: $webPixel) {
    userErrors {
      field
      message
      code
    }
    webPixel {
      id
      settings
    }
  }
}

Variables

{
  "webPixel": {
    "settings": {
      "trackingId": "GA-TRACKING-ID-123"
    }
  }
}

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 webPixelCreate($webPixel: WebPixelInput!) { webPixelCreate(webPixel: $webPixel) { userErrors { field message code } webPixel { id settings } } }",
 "variables": {
    "webPixel": {
      "settings": {
        "trackingId": "GA-TRACKING-ID-123"
      }
    }
  }
}'

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 webPixelCreate($webPixel: WebPixelInput!) {
    webPixelCreate(webPixel: $webPixel) {
      userErrors {
        field
        message
        code
      }
      webPixel {
        id
        settings
      }
    }
  }`,
  {
    variables: {
        "webPixel": {
            "settings": {
                "trackingId": "GA-TRACKING-ID-123"
            }
        }
    },
  },
  );
  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 webPixelCreate($webPixel: WebPixelInput!) {
    webPixelCreate(webPixel: $webPixel) {
      userErrors {
        field
        message
        code
      }
      webPixel {
        id
        settings
      }
    }
  }
QUERY

variables = {
  "webPixel": {
    "settings": {
      "trackingId": "GA-TRACKING-ID-123"
    }
  }
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation webPixelCreate($webPixel: WebPixelInput!) {
      webPixelCreate(webPixel: $webPixel) {
        userErrors {
          field
          message
          code
        }
        webPixel {
          id
          settings
        }
      }
    }`,
    "variables": {
        "webPixel": {
            "settings": {
                "trackingId": "GA-TRACKING-ID-123"
            }
        }
    },
  },
});

Response

{
  "webPixelCreate": {
    "userErrors": [],
    "webPixel": {
      "id": "gid://shopify/WebPixel/937414752",
      "settings": "{\"trackingId\":\"GA-TRACKING-ID-123\"}"
    }
  }
}

Creating a web pixel with invalid settings returns an error

Description

This example shows the error response when you try to create a web pixel with invalid settings. If you provide an empty `settings` object, then the mutation returns an error.

Query

mutation webPixelCreate($webPixel: WebPixelInput!) {
  webPixelCreate(webPixel: $webPixel) {
    userErrors {
      field
      message
      code
    }
    webPixel {
      id
      settings
    }
  }
}

Variables

{
  "webPixel": {
    "settings": {}
  }
}

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 webPixelCreate($webPixel: WebPixelInput!) { webPixelCreate(webPixel: $webPixel) { userErrors { field message code } webPixel { id settings } } }",
 "variables": {
    "webPixel": {
      "settings": {}
    }
  }
}'

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 webPixelCreate($webPixel: WebPixelInput!) {
    webPixelCreate(webPixel: $webPixel) {
      userErrors {
        field
        message
        code
      }
      webPixel {
        id
        settings
      }
    }
  }`,
  {
    variables: {
        "webPixel": {
            "settings": {}
        }
    },
  },
  );
  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 webPixelCreate($webPixel: WebPixelInput!) {
    webPixelCreate(webPixel: $webPixel) {
      userErrors {
        field
        message
        code
      }
      webPixel {
        id
        settings
      }
    }
  }
QUERY

variables = {
  "webPixel": {
    "settings": {}
  }
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation webPixelCreate($webPixel: WebPixelInput!) {
      webPixelCreate(webPixel: $webPixel) {
        userErrors {
          field
          message
          code
        }
        webPixel {
          id
          settings
        }
      }
    }`,
    "variables": {
        "webPixel": {
            "settings": {}
        }
    },
  },
});

Response

{
  "webPixelCreate": {
    "userErrors": [
      {
        "field": [
          "webPixel"
        ],
        "message": "Missing keys: trackingId",
        "code": "INVALID_SETTINGS"
      }
    ],
    "webPixel": null
  }
}

webPixelCreate 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 webPixelCreate($webPixel: WebPixelInput!) {

webPixelCreate(webPixel: $webPixel) {

userErrors {

field

message

code

}

webPixel {

settings

}

}`,

{

variables: {

"webPixel": {

"settings": {

"trackingId": "GA-TRACKING-ID-123"

}

);

const json = await response.json();

return json.data;

}

GQL

mutation webPixelCreate($webPixel: WebPixelInput!) {
  webPixelCreate(webPixel: $webPixel) {
    userErrors {
      field
      message
      code
    }
    webPixel {
      id
      settings
    }
  }
}

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 webPixelCreate($webPixel: WebPixelInput!) { webPixelCreate(webPixel: $webPixel) { userErrors { field message code } webPixel { id settings } } }",
 "variables": {
    "webPixel": {
      "settings": {
        "trackingId": "GA-TRACKING-ID-123"
      }
    }
  }
}'

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 webPixelCreate($webPixel: WebPixelInput!) {
    webPixelCreate(webPixel: $webPixel) {
      userErrors {
        field
        message
        code
      }
      webPixel {
        id
        settings
      }
    }
  }`,
  {
    variables: {
        "webPixel": {
            "settings": {
                "trackingId": "GA-TRACKING-ID-123"
            }
        }
    },
  },
  );
  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 webPixelCreate($webPixel: WebPixelInput!) {
      webPixelCreate(webPixel: $webPixel) {
        userErrors {
          field
          message
          code
        }
        webPixel {
          id
          settings
        }
      }
    }`,
    "variables": {
        "webPixel": {
            "settings": {
                "trackingId": "GA-TRACKING-ID-123"
            }
        }
    },
  },
});

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 webPixelCreate($webPixel: WebPixelInput!) {
    webPixelCreate(webPixel: $webPixel) {
      userErrors {
        field
        message
        code
      }
      webPixel {
        id
        settings
      }
    }
  }
QUERY

variables = {
  "webPixel": {
    "settings": {
      "trackingId": "GA-TRACKING-ID-123"
    }
  }
}

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

Input variables

JSON

{

"webPixel": {

"settings": {

"trackingId": "GA-TRACKING-ID-123"

}

Response

JSON

{

"webPixelCreate": {

"userErrors": [],

"webPixel": {

"id": "gid://shopify/WebPixel/937414752",

"settings": "{\"trackingId\":\"GA-TRACKING-ID-123\"}"

}