Choose a version:

tagsAdd

mutation

Adds tags to a resource. If the resource type doesn't support tagging, the id argument returns a resource-not-found error.

Tags help merchants organize and filter resources. See the tags argument for supported input formats.

Learn more about using tags to organize subscription orders.

Anchor to Arguments

Arguments

Anchor to idid •ID! required: The ID of a resource to add tags to. Supported resources: Order, DraftOrder, Customer, Product, Article, and DiscountNode.
Anchor to tagstags •[String!]! required: A list of tags to add to the resource. Can be an array of strings or a single string composed of a comma-separated list of values. Example values: ["tag1", "tag2", "tag3"], "tag1, tag2, tag3".

Was this section helpful?

Anchor to TagsAddPayload returnsTagsAddPayload returns

Anchor to nodenode •Node: The object that was updated.
Anchor to userErrorsuserErrors •[UserError!]! non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Examples

Add tags to a customer

Query

mutation addTags($id: ID!, $tags: [String!]!) {
  tagsAdd(id: $id, tags: $tags) {
    node {
      id
    }
    userErrors {
      message
    }
  }
}

Variables

{
  "id": "gid://shopify/Customer/544365967",
  "tags": "one, two, three"
}

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 addTags($id: ID!, $tags: [String!]!) { tagsAdd(id: $id, tags: $tags) { node { id } userErrors { message } } }",
 "variables": {
    "id": "gid://shopify/Customer/544365967",
    "tags": "one, two, three"
  }
}'

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 addTags($id: ID!, $tags: [String!]!) {
    tagsAdd(id: $id, tags: $tags) {
      node {
        id
      }
      userErrors {
        message
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/Customer/544365967",
        "tags": "one, two, three"
    },
  },
  );
  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 addTags($id: ID!, $tags: [String!]!) {
    tagsAdd(id: $id, tags: $tags) {
      node {
        id
      }
      userErrors {
        message
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/Customer/544365967",
  "tags": "one, two, three"
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation addTags($id: ID!, $tags: [String!]!) {
      tagsAdd(id: $id, tags: $tags) {
        node {
          id
        }
        userErrors {
          message
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Customer/544365967",
        "tags": "one, two, three"
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation addTags($id: ID!, $tags: [String!]!) {
  tagsAdd(id: $id, tags: $tags) {
    node {
      id
    }
    userErrors {
      message
    }
  }
}' \
--variables \
'{
  "id": "gid://shopify/Customer/544365967",
  "tags": "one, two, three"
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation addTags($id: ID!, $tags: [String!]!) {
        tagsAdd(id: $id, tags: $tags) {
          node {
            id
          }
          userErrors {
            message
          }
        }
      }
    `,
    variables: {
        "id": "gid://shopify/Customer/544365967",
        "tags": "one, two, three"
    },
  }),
});

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

Response

{
  "tagsAdd": {
    "node": {
      "id": "gid://shopify/Customer/544365967"
    },
    "userErrors": []
  }
}

Add tags to a product

Query

mutation addTags($id: ID!, $tags: [String!]!) {
  tagsAdd(id: $id, tags: $tags) {
    node {
      id
    }
    userErrors {
      message
    }
  }
}

Variables

{
  "id": "gid://shopify/Product/20995642",
  "tags": "one, two, three"
}

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 addTags($id: ID!, $tags: [String!]!) { tagsAdd(id: $id, tags: $tags) { node { id } userErrors { message } } }",
 "variables": {
    "id": "gid://shopify/Product/20995642",
    "tags": "one, two, three"
  }
}'

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 addTags($id: ID!, $tags: [String!]!) {
    tagsAdd(id: $id, tags: $tags) {
      node {
        id
      }
      userErrors {
        message
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/Product/20995642",
        "tags": "one, two, three"
    },
  },
  );
  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 addTags($id: ID!, $tags: [String!]!) {
    tagsAdd(id: $id, tags: $tags) {
      node {
        id
      }
      userErrors {
        message
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/Product/20995642",
  "tags": "one, two, three"
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation addTags($id: ID!, $tags: [String!]!) {
      tagsAdd(id: $id, tags: $tags) {
        node {
          id
        }
        userErrors {
          message
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Product/20995642",
        "tags": "one, two, three"
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation addTags($id: ID!, $tags: [String!]!) {
  tagsAdd(id: $id, tags: $tags) {
    node {
      id
    }
    userErrors {
      message
    }
  }
}' \
--variables \
'{
  "id": "gid://shopify/Product/20995642",
  "tags": "one, two, three"
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation addTags($id: ID!, $tags: [String!]!) {
        tagsAdd(id: $id, tags: $tags) {
          node {
            id
          }
          userErrors {
            message
          }
        }
      }
    `,
    variables: {
        "id": "gid://shopify/Product/20995642",
        "tags": "one, two, three"
    },
  }),
});

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

Response

{
  "tagsAdd": {
    "node": {
      "id": "gid://shopify/Product/20995642"
    },
    "userErrors": []
  }
}

Attempt to add tags to an product that does not exist

Query

mutation addTags($id: ID!, $tags: [String!]!) {
  tagsAdd(id: $id, tags: $tags) {
    node {
      id
    }
    userErrors {
      message
    }
  }
}

Variables

{
  "id": "gid://shopify/Product/12345",
  "tags": "one, two, three"
}

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 addTags($id: ID!, $tags: [String!]!) { tagsAdd(id: $id, tags: $tags) { node { id } userErrors { message } } }",
 "variables": {
    "id": "gid://shopify/Product/12345",
    "tags": "one, two, three"
  }
}'

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 addTags($id: ID!, $tags: [String!]!) {
    tagsAdd(id: $id, tags: $tags) {
      node {
        id
      }
      userErrors {
        message
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/Product/12345",
        "tags": "one, two, three"
    },
  },
  );
  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 addTags($id: ID!, $tags: [String!]!) {
    tagsAdd(id: $id, tags: $tags) {
      node {
        id
      }
      userErrors {
        message
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/Product/12345",
  "tags": "one, two, three"
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation addTags($id: ID!, $tags: [String!]!) {
      tagsAdd(id: $id, tags: $tags) {
        node {
          id
        }
        userErrors {
          message
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Product/12345",
        "tags": "one, two, three"
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation addTags($id: ID!, $tags: [String!]!) {
  tagsAdd(id: $id, tags: $tags) {
    node {
      id
    }
    userErrors {
      message
    }
  }
}' \
--variables \
'{
  "id": "gid://shopify/Product/12345",
  "tags": "one, two, three"
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation addTags($id: ID!, $tags: [String!]!) {
        tagsAdd(id: $id, tags: $tags) {
          node {
            id
          }
          userErrors {
            message
          }
        }
      }
    `,
    variables: {
        "id": "gid://shopify/Product/12345",
        "tags": "one, two, three"
    },
  }),
});

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

Response

{
  "tagsAdd": {
    "node": null,
    "userErrors": [
      {
        "message": "Product does not exist"
      }
    ]
  }
}

tagsAdd 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 addTags($id: ID!, $tags: [String!]!) {

tagsAdd(id: $id, tags: $tags) {

node {

}

userErrors {

message

}

}`,

{

variables: {

"id": "gid://shopify/Customer/544365967",

"tags": "one, two, three"

);

const json = await response.json();

return json.data;

}

GQL

mutation addTags($id: ID!, $tags: [String!]!) {
  tagsAdd(id: $id, tags: $tags) {
    node {
      id
    }
    userErrors {
      message
    }
  }
}

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 addTags($id: ID!, $tags: [String!]!) { tagsAdd(id: $id, tags: $tags) { node { id } userErrors { message } } }",
 "variables": {
    "id": "gid://shopify/Customer/544365967",
    "tags": "one, two, three"
  }
}'

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 addTags($id: ID!, $tags: [String!]!) {
    tagsAdd(id: $id, tags: $tags) {
      node {
        id
      }
      userErrors {
        message
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/Customer/544365967",
        "tags": "one, two, three"
    },
  },
  );
  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 addTags($id: ID!, $tags: [String!]!) {
      tagsAdd(id: $id, tags: $tags) {
        node {
          id
        }
        userErrors {
          message
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Customer/544365967",
        "tags": "one, two, three"
    },
  },
});

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 addTags($id: ID!, $tags: [String!]!) {
    tagsAdd(id: $id, tags: $tags) {
      node {
        id
      }
      userErrors {
        message
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/Customer/544365967",
  "tags": "one, two, three"
}

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

Shopify CLI

shopify app execute \
--query \
'mutation addTags($id: ID!, $tags: [String!]!) {
  tagsAdd(id: $id, tags: $tags) {
    node {
      id
    }
    userErrors {
      message
    }
  }
}' \
--variables \
'{
  "id": "gid://shopify/Customer/544365967",
  "tags": "one, two, three"
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation addTags($id: ID!, $tags: [String!]!) {
        tagsAdd(id: $id, tags: $tags) {
          node {
            id
          }
          userErrors {
            message
          }
        }
      }
    `,
    variables: {
        "id": "gid://shopify/Customer/544365967",
        "tags": "one, two, three"
    },
  }),
});

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

Input variables

JSON

{

"id": "gid://shopify/Customer/544365967",

"tags": "one, two, three"

}

Response

JSON

{

"tagsAdd": {

"node": {

"id": "gid://shopify/Customer/544365967"

"userErrors": []

}