How to update Taxonomy Attributes of a product with GraphQL Admin API (2025-01)

Technical Q&A

Topic summary

A developer is attempting to programmatically create products and set their taxonomy attributes using Shopify’s GraphQL Admin API (2025-01), but is encountering documentation gaps and unclear implementation details.

Main Challenge:
Unclear how to properly set Taxonomy Attributes, which appear to be metafields under the “shopify” namespace. The relationship between Metafield, Metaobject, and MetaobjectDefinition remains confusing.

Progress Made:

  • Successfully creating products with correct category IDs
  • Discovered the standardMetaobjectDefinitionEnable mutation for enabling templated definitions
  • Found that standard definitions must be enabled before setting taxonomy values

Specific Issues:

  • Official documentation page for standard definitions is nearly empty (only 1 item listed)
  • Attribute naming inconsistencies: Taxonomy shows separate “color” and “pattern” attributes, but the actual type is “shopify–color-pattern” (discovered only through network inspection)
  • No documented query exists for fetching all available Standard Metaobject Definitions
  • Mismatch between attribute handles in the Taxonomy Repository and actual API types

Status: Unresolved. The developer seeks guidance from Shopify developers, as the feature appears poorly documented for the new 2025-01 API version. Another user confirms similar documentation difficulties.

Summarized with AI on October 28. AI used: claude-sonnet-4-5-20250929.
1

Hello,

I’ve been working with the GraphQL Admin API (2025-01) for a few days. It’s honestly incredible, but there are some areas I’m struggling to find a lot of information on and LLMs aren’t much help here since the API is relatively new.

My goal is to programmatically create products, set their category and their attribute values according to the Shopify Standard Product Taxonomy (https://shopify.github.io/product-taxonomy/releases/unstable/).

I have gone as far as to create the product with the right category ID. At this stage I’m a bit confused how “Attributes” are defined. To my understanding Taxonomy Attributes are metafields (?) under the “shopify” namespace which I believe makes me unable to edit them directly by passing metafields to the productCreate mutation.

In general I feel like the while relationship between Metafield, Metaobject and MegaobjectDefinition is a bit unclear. It would be great if someone could point me to some documentation that clearly explains their relationship. Please also correct me if these metafields have nothing to do with Taxonomy Attributes.

Here is a small example of my query:

mutation createProduct($product: ProductCreateInput!, $media: [CreateMediaInput!]) {
    productCreate(product: $product, media: $media) {
      product {
        ...product
      }
      userErrors {
        field
        message
      }
    }
  }
  ${productFragment}

And the variables:

{
  product: {
    status: "DRAFT",
    category: "gid://shopify/TaxonomyCategory/fr-24-4",
    title: "...",
    descriptionHtml: "...",
    vendor: "...",
    productType: "Static",
    tags: [
      "b2b-import",
      "Tables",
      "Kitchen & Dining Room Tables",
    ],
    metafields: [
      {
        namespace: "b2b",
        key: "identification_code",
        value: "FB98337.21",
        type: "single_line_text_field",
      },
      {
        namespace: "b2b",
        key: "stockQuantity",
        value: "156",
        type: "number_integer",
      },
      {
        namespace: "shopify",
        key: "Leg color",
        value: "[\"gid://shopify/TaxonomyValue/1\"]",
        type: "list.metaobject_reference",
      },
      {
        namespace: "shopify",
        key: "Leg material",
        value: "[\"gid://shopify/TaxonomyValue/21884\"]",
        type: "list.metaobject_reference",
      },
      {
        namespace: "shopify",
        key: "Tabletop color",
        value: "[\"gid://shopify/TaxonomyValue/7\"]",
        type: "list.metaobject_reference",
      },
      {
        namespace: "shopify",
        key: "Tabletop material",
        value: "[\"gid://shopify/TaxonomyValue/21862\",\"gid://shopify/TaxonomyValue/21899\"]",
        type: "list.metaobject_reference",
      },
    ],
  },
}

I know I need to do some “prep-work” before being able to set those shopify TaxonomyValue fields but I’m not sure what.

Can someone please guide me or point me to some relevant documentation?

Please note again that I’m using GraphQL Admin API 2025-01 which is has differences compared to 2024 version.

Many thanks in advance!

Sorry for the not-so-relevant label on the post, but there were no labels for API or GraphQL.

3 Likes
2

I discovered some new information that might help. But I still hope to get some feedback from shopify developers as it really seems like this feature is not barely documented.

I found the following mutation:

standardMetaobjectDefinitionEnable(type: $type) {
    metaobjectDefinition {
      ...MetaobjectDefinition
    }
}

This allows you to enable templated definitions in your store. It looks like this is the right way to enable definitions for the shopify pre-made attributes that are defined in the Taxonomy documentation.

Now there are still issues with this:

  1. I found a documentation page which is meant to provide a list of all the standard definitions but it seems to be pretty much empty (only 1 item) https://shopify.dev/docs/apps/build/custom-data/metaobjects/list-of-standard-definitions
  2. In the Taxonomy website I see attributes for “color” and “pattern”. However, there is no “shopify–color” type. The type we are supposed to use is called “shopify–color-pattern” which is a combination of the “color” and “pattern” attributes and has fields for both. I only found this by inspecting the network requests from the Shopify Admin Dashboard.
  3. There is no documented query I could find for fetching all available Standard Metaobject Definitions.

How are we supposed to know the available “types” if they are not documented and they are not always matching with the attribute handles in the Taxonomy Repository?

Any additional information would be greatly appreciated.

3

I’m also having trouble with documentation on the subject

4

Hello @ApsTechLead, did you find a solution?