How to Use Category Metafields in Product Creation via the GraphQL API

Technical Q&A
1

wangli29751_0-1744012806520.png
wangli29751_0-1744012806520.png873×385 11.3 KB

On the admin page, we can create a product within a selected category. Products in a category can have predefined metafields to choose from. Is there a standard way to access these category metafields through the API?

2

Hey @wangli29751 this query is relates to Shopify’s Product Taxonomy and Category Metafields, a newer feature that helps with product attributes like (material, color, etc.) based on the assigned product category.

When creating products via the GraphQL Admin API, you can access and assign category-based metafields, but there are some important details to keep in mind.

1: Why are category Metafields?

  • When a product is assigned a Product Category like shoes or t-shirts Shopify attaches’ standardized metafields definitions relevant to the category like material, size, color.
  • These are not regular custom metafields they are predefined by Shopify for consistency across categories.

Now the Question is that how to access Category metafield via GraphQL?

There is a standardized way to fetch and use these via GraphQL Admin API. Just follow these steps.

  • Get product Category Suggestions: To explore what categories are available you can check from this code.
query {
  productCategorySuggestions(query: "t-shirt") {
    productTaxonomyNode {
      id
      name
      fullName
    }
  }
}
​
  • Get Metafield Definition for a category: Once you have a productTaxonomyNode.id, you can use this Query.
query {
  productTaxonomyNode(id: "gid://shopify/ProductTaxonomyNode/12345") {
    id
    name
    metafieldDefinitions(first: 50) {
      edges {
        node {
          id
          name
          key
          namespace
          type {
            name
          }
        }
      }
    }
  }
}
  • Assign a category to a Product: Now it’s time to assign a product to the exact category. You can use this code like this:
mutation {
  productCreate(input: {
    title: "Nike Air Max",
    productCategory: {
      productTaxonomyNodeId: "gid://shopify/ProductTaxonomyNode/12345"
    }
  }) {
    product {
      id
      title
    }
    userErrors {
      field
      message
    }
  }
}
  • Set Category Metafileds Values: After assigning the category, set metafields using the category-defined namespace and key.
mutation {
  metafieldsSet(metafields: [
    {
      ownerId: "gid://shopify/Product/PRODUCT_ID",
      namespace: "standard",
      key: "material",
      type: "single_line_text_field",
      value: "Cotton"
    }
  ]) {
    metafields {
      id
      key
      value
    }
    userErrors {
      field
      message
    }
  }
}

By following these steps you will be able to use category Metafields in Product creation via the GraphQL API.

if this was really helpful prove it via like and Mark as Solution.

3

Thank you for your reply, but it appears that none of the queries or mutations you provided were valid.

4

Hi, Wangli

Yes, there is a standard way to access category metafields through the API in various eCommerce platforms like Shopify, WooCommerce, and others. Here, I will explain how you might approach this depending on the platform you are working with. Since many platforms, like Shopify, allow for category-specific metafields, let’s start with a more general guide and dive into specifics for Shopify.

There are some categories metafields using these APIs

Shopify and WooCommerce (Wordpress)

5

Only AI bots here :sleepy_face:

6

Hey there! I’m trying to create a Product using the Shopify Admin GraphiQL API, set its Category, and add Metafields for that Category. I saw your reply in a post, which was super helpful, but when I tried your approach with the new 2025-04 version, I ran into issues. It seems like productCategorySuggestions is deprecated in this version, and my query returned some errors. Can you help me figure out how to achieve this with the 2025-04 version of the Shopify Admin GraphiQL API?

{
    "query": "query { productCategorySuggestions(query: \"t-shirt\") { productTaxonomyNode { id name fullName } } }",
    "variables": {
        "sku": "916042",
        "first": 5
    }
}

{
    "errors": [
        {
            "message": "Field 'productCategorySuggestions' doesn't exist on type 'QueryRoot'",
            "locations": [
                {
                    "line": 1,
                    "column": 9
                }
            ],
            "path": [
                "query",
                "productCategorySuggestions"
            ],
            "extensions": {
                "code": "undefinedField",
                "typeName": "QueryRoot",
                "fieldName": "productCategorySuggestions"
            }
        }
    ]
}