Creating products & variants with linkedMetafield

Ronald_G · September 1, 2025, 12:20pm

We are using GraphQL 2025-07, has anyone had success following this Shopify article on Metafield-linked product options to create products with variants that has linkedMetafieldValues?

We’ve tried the following:

metaobjectCreate + productSet per the help article - we get error “Option ‘Color’ must specify at least one option value.” See code blocks below. (We also had to fix the error that Shopify variant positions now start with 1 instead of 0)
productCreate + productVariantsBulkCreate - we verified that the linkedMetafieldValues exist on product options, but productVariantsBulkCreate raises id or name must be specified
productCreate + productOptionUpdate + productVariantsBulkCreate - we get id or name must be specified

Here are the steps for #1

1. Verify metaobject exists:

query ($id: ID!) {
  metaobject(id: $id) {
    id
    type
    displayName
    handle
    fields {
      key
      value
    }
  }
}

Results:

{“id”=>“gid://shopify/Metaobject/52316602535”, “type”=>“shopify–color-pattern”, “displayName”=>“Gold”, “handle”=>“gold”, “fields”=>[{“key”=>“label”, “value”=>“Gold”}, {“key”=>“color”, “value”=>“#D49A06”}, {“key”=>“image”, “value”=>nil}, {“key”=>“color_taxonomy_reference”, “value”=>“["gid://shopify/TaxonomyValue/4"]”}, {“key”=>“pattern_taxonomy_reference”, “value”=>“gid://shopify/TaxonomyValue/2874”}]}

{"id"=>"gid://shopify/Metaobject/52316569767", "type"=>"shopify--color-pattern", "displayName"=>"Bronze", "handle"=>"bronze", "fields"=>[{"key"=>"label", "value"=>"Bronze"}, {"key"=>"color", "value"=>"#CD7F32"}, {"key"=>"image", "value"=>nil}, {"key"=>"color_taxonomy_reference", "value"=>"[\"gid://shopify/TaxonomyValue/657\"]"}, {"key"=>"pattern_taxonomy_reference", "value"=>"gid://shopify/TaxonomyValue/2874"}]}

2. productSet with parameters

{
  title: "product name set",
  vendor: "Product Test",
  status: "ACTIVE",
  productType: "Bracelet",
  productOptions: [
    {
      name: "Color",
      linkedMetafield: {
        namespace: "shopify",
        key: "color-pattern"
      }
    }
  ],
  variants: [
    {
      optionValues: [{ optionName: "Color", linkedMetafieldValue: "gid://shopify/Metaobject/52316602535"}],
      sku: "PT-322353-1",
    },
    {
      optionValues: [{ optionName: "Color", linkedMetafieldValue: "gid://shopify/Metaobject/52316569767"}],
      sku: "PT-322353-2",
    }
  ]
}

Error raised:
‘Color’ must specify at least one option value.

Alan_G · September 1, 2025, 8:48pm

Hey @Ronald_G - when creating the the product, are you setting the product category as well? Here’s a quick example per the docs there:

mutation productSet {
  productSet(synchronous: true, input: {
    title: "T-Shirt"
    category: "gid://shopify/TaxonomyCategory/aa-1-13-7"
    productOptions: [
      {
        name: "Size",
        values: [
          { name: "Small"},
          { name: "Medium"},
        ]
      },
      {
        name: "Color",
        linkedMetafield: {
          namespace: "shopify",
          key: "color-pattern",
        }
      }
    ],
    variants: [
      {
        position: 0
        optionValues: [
          { optionName: "Size", name: "Small" },
          { optionName: "Color", linkedMetafieldValue: "gid://shopify/Metaobject/70095274073" }
        ]
      },
      {
        position: 1
        optionValues: [
          { optionName: "Size", name: "Medium" },
          { optionName: "Color", linkedMetafieldValue: "gid://shopify/Metaobject/70095274073" }
        ]
      }
    ]
  }) {
    userErrors { message }
    product {
      id
    }
  }
}

You should be able to grab a product category ID here: 2025-03

Could you let me know if added the category to the productSet mutation resolves things or if the issue persists? Happy to help out further if need be for sure!

Ronald_G · September 1, 2025, 9:49pm

Thanks @Alan_G

We tried the sample code and it didn’t work.

We also assumed the metaobject ID is store specific? If so, we created a new product via Shopify admin (“gid://shopify/Product/8579978887335”), found the category ID and metaobject IDs, and tried to use productSet in GraphiQL, but still got “Option ‘Color’ must specify at least one option value.” See screenshots below:

mutation productSet {
  productSet(synchronous: true, input: {
    title: "T-Shirt"
    category: "gid://shopify/TaxonomyCategory/aa-1-13-8"
    productOptions: [
      {
        name: "Size",
        values: [
          { name: "Small"},
          { name: "Medium"},
        ]
      },
      {
        name: "Color",
        linkedMetafield: {
          namespace: "shopify",
          key: "color-pattern",
        }
      }
    ],
    variants: [
      {
        position: 1
        optionValues: [
          { optionName: "Size", name: "Small" },
          { optionName: "Color", linkedMetafieldValue: "gid://shopify/Metaobject/122144719015" }
        ]
      },
      {
        position: 2
        optionValues: [
          { optionName: "Size", name: "Medium" },
          { optionName: "Color", linkedMetafieldValue: "gid://shopify/Metaobject/122144751783" }
        ]
      }
    ]
  }) {
    userErrors { message }
    product {
      id
    }
  }
}

Alan_G · September 2, 2025, 3:34pm

Hey @Ronald_G - thanks for trying that. Are you setting up the metaobjects as well? In the guide there we have an example that might help. Just posting here for ease of reference:

mutation MetaobjectCreate($metaobject: MetaobjectCreateInput!) {
  metaobjectCreate(metaobject: $metaobject) {
    metaobject {
      id
      displayName
      fields {
        key
        value
      }
    }
    userErrors {
      field
      message
    }
  }
}

{
  "metaobject": {
    "type": "shopify--color-pattern",
    "fields": [
      {
        "key": "color_taxonomy_reference",
        "value": "[\"gid://shopify/TaxonomyValue/3\", \"gid://shopify/TaxonomyValue/10\"]"
      },
      {
        "key": "pattern_taxonomy_reference",
        "value": "gid://shopify/TaxonomyValue/2874"
      },
      {
        "key": "label",
        "value": "Orange/Blue"
      }
    ]
  }
}

If you’re using pre-existing metafields without the set taxonomy values that might be why that error is popping up. Let me know if you’re still seeing the issue pop up and I’m happy to keep troubleshooting with you.

Ronald_G · September 2, 2025, 8:30pm

Hi @Alan_G

I have a couple general questions:

Can metaobjects be reused for multiple products? Or does each product option needs it’s own metaobject?
Is there a help article on TaxonomyValue on what the valid values are? This Shopify.dev article isn’t helpful

I created 2 new metaobjects (“gid://shopify/Metaobject/153379340588” and “gid://shopify/Metaobject/153379602732”) and tried to use productSet, but still same error: “Option ‘Color’ must specify at least one option value.” See code and screenshots below.

Created “gid://shopify/Metaobject/153379340588” as Orange/Blue

Created “gid://shopify/Metaobject/153379602732” as Orange

Still same error when using productSet

mutation productSet {
  productSet(
    synchronous: true
    input: {title: "T-Shirt", category: "gid://shopify/TaxonomyCategory/aa-1-13-7", productOptions: [{name: "Size", values: [{name: "Small"}, {name: "Medium"}]}, {name: "Color", linkedMetafield: {namespace: "shopify", key: "color-pattern"}}], variants: [{position: 1, optionValues: [{optionName: "Size", name: "Small"}, {optionName: "Color", linkedMetafieldValue: "gid://shopify/Metaobject/153379340588"}]}, {position: 2, optionValues: [{optionName: "Size", name: "Medium"}, {optionName: "Color", linkedMetafieldValue: "gid://shopify/Metaobject/153379602732"}]}]}
  ) {
    userErrors {
      message
    }
    product {
      id
    }
  }
}

Alan_G · September 3, 2025, 4:23pm

Hey @Ronald_G - thanks for following up here.

shopify--color-pattern metaobjects should be reusable once they’re created.

You can reference the same metaobject across multiple products and variants there, there’s no rule that a metaobject once created should be tied tro only one product.

For the “Option ‘Color’ must specify at least one option value.” error we’re seeing there, just wanted to clarify that productSet validates options before it processes variants, so this is likely why we’re seeing that pop up.

I did a little digging, and I think the example below should resolve the error:

mutation productSet {
  productSet(
    synchronous: true
    input: {title: "T-Shirt", category: "gid://shopify/TaxonomyCategory/aa-1-13-7", productOptions: [{name: "Size", values: [{name: "Small"}, {name: "Medium"}]}, {name: "Color", linkedMetafield: {namespace: "shopify", key: "color-pattern", values: ["gid://shopify/Metaobject/153379340588", "gid://shopify/Metaobject/153379602732"]}}], variants: [{position: 1, optionValues: [{optionName: "Size", name: "Small"}, {optionName: "Color", linkedMetafieldValue: "gid://shopify/Metaobject/153379340588"}]}, {position: 2, optionValues: [{optionName: "Size", name: "Medium"}, {optionName: "Color", linkedMetafieldValue: "gid://shopify/Metaobject/153379602732"}]}]}
  ) {
    userErrors {
      field
      message
    }
    product {
      id
    }
  }
}

If you add the option-level Color values and still see an error, no worries. Feel free to reach back out here and share the exact productSet input and the responses for those two metaobjects (you can redact any shop-specific details), and I’ll keep digging with you. More than happy to help as always

Ronald_G · September 3, 2025, 6:28pm

Thank you @Alan_G for your help!

It looks like it worked for productSet. It looks like the Shopify.dev article is out of date.

Also, it seems that productCreate + productVariantsBulkCreate is raising id or name must be specified error. See below.

mutation productCreate($product: ProductCreateInput) {
  productCreate(product: $product) {
    product {
      id
      title
      status
      variantsCount {
        count
      }
      options {
        id
        name
        position
        values
        linkedMetafield {
          namespace
          key
        }
        optionValues {
          id
          name
          hasVariants
          linkedMetafieldValue
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

{
  "product": {
    "title": "Multiple variants + linkedMetaField",
    "category": "gid://shopify/TaxonomyCategory/aa-1-13-7",
    "productOptions": [
      {
        "name": "Color",
        "linkedMetafield": {
          "namespace": "shopify",
          "key": "color-pattern",
          "values": [
            "gid://shopify/Metaobject/122144719015",
            "gid://shopify/Metaobject/122144751783",
            "gid://shopify/Metaobject/122144784551"
          ]
        }
      }
    ]
  }
}

but productVariantsBulkCreate raises id or name must be specified error

mutation productVariantsBulkCreate($productId: ID!, $variants: [ProductVariantsBulkInput!]!, $strategy: ProductVariantsBulkCreateStrategy, $media: [CreateMediaInput!]) {
  productVariantsBulkCreate(
    productId: $productId
    media: $media
    variants: $variants
    strategy: $strategy
  ) {
    product {
      id
      title
      status
      variantsCount {
        count
      }
      options {
        id
        name
        position
        values
        linkedMetafield {
          namespace
          key
        }
        optionValues {
          id
          name
          hasVariants
          linkedMetafieldValue
        }
      }
    }
    productVariants {
      id
      displayName
      title
      sku
      position
      defaultCursor
      selectedOptions {
        name
        value
      }
    }
    userErrors {
      field
      message
    }
  }
}

{
  "productId": "gid://shopify/Product/8582130106535",
  "variants": [
    {
      "optionValues": [
        {
          "optionName": "Color",
          "linkedMetafieldValue": "gid://shopify/Metaobject/122144719015"
        }
      ],
      "inventoryItem": {
        "sku": "PT-1122112-RED"
      }
    },
    {
      "optionValues": [
        {
          "optionName": "Color",
          "linkedMetafieldValue": "gid://shopify/Metaobject/122144751783"
        }
      ],
      "inventoryItem": {
        "sku": "PT-1122112-YELLOW"
      }
    },
    {
      "optionValues": [
        {
          "optionName": "Color",
          "linkedMetafieldValue": "gid://shopify/Metaobject/122144784551"
        }
      ],
      "inventoryItem": {
        "sku": "PT-1122112-GREEN"
      }
    }
  ]
}

We also tried changing optionValues to this, but then we get Cannot set name for an option value linked to a metafield

{
                  optionName: "Color",
                  name: "Green",
                  linkedMetafieldValue: "gid://shopify/Metaobject/122144784551"
                }

Alan_G · September 4, 2025, 4:05pm

Hey @Ronald_G - no worries, glad it’s working for productSet for you! With productVariantsBulkCreate, My understanding is that this is actually expected behaviour, but I do agree it’s a bit strange if you haven’t encountered the flow before. Essentially, you have to run productOptionsCreate after productCreate and then manage variants using the bulk mutation:

We mention this in the docs here:

Creates one or more options on a product, such as size, color, or material. Each option includes a name, position, and a list of values. The combination of a product option and value creates a product variant. Use the productOptionsCreate mutation for the following use cases:

Add product choices: Add a new option, like “Size” (Small, Medium, Large) or “Color” (Red, Blue, Green), to an existing product so customers can select their preferred variant.

Enable personalization features: Add options such as “Engraving text” to let customers customize their purchase.

Offer seasonal or limited edition products: Add a new value (for example, “Holiday red”) to an existing option to support limited-time or seasonal variants.

Integrate with apps that manage product configuration: Allow third-party apps to add options, like “Bundle size”, when customers select or customize product bundles.

Link options to metafields: Associate a product option with a custom metafield, like “Fabric code”, for richer integrations with other systems or apps.

Note

The productOptionsCreate mutation enforces strict data integrity for product options and variants. All option positions must be sequential, and every option should be used by at least one variant. If you use the CREATE variant strategy, consider the maximum allowed number of variants for each product (100 by default, and 2,048 if you’ve enabled the Extended Variants developer preview).

After you create product options, you can further manage a product’s configuration using related mutations:

productOptionUpdate

productOptionsReorder

productOptionsDelete

productVariantsBulkCreate

productVariantsBulkUpdate

productSet

productOptionsCreate effectively creates variants itself. For bulk creations though, I’d stick with productSet since it allows you a bit more flexibility in terms of setting option/variant values alongside creating the product. Hope this helps/makes sense, let me know if I can clarify anything as always, happy to help!

Ronald_G · September 4, 2025, 6:22pm

Thank you @Alan_G so much for spending time on this question. You’ve been super helpful. Good to know the nuances of the different mutations.

Alan_G · September 4, 2025, 6:32pm

No worries, my pleasure @Ronald_G , let me know if I can help out further

Topic		Replies	Views
How to set `optionValues` for a product variant that is linked to a metafield value? GraphQL Admin API Troubleshooting general-gql-troubles	13	373	October 22, 2025
createOptions - productOptionsCreate GraphQL Admin API Troubleshooting general-gql-troubles	1	48	May 29, 2025
Updating existing product with the `productSet` mutation throws unexpected error, when `input.productOptions` using `linkedMetafield` and `input.metafields` are set at the same time GraphQL Admin API Troubleshooting general-gql-troubles	1	22	October 16, 2025
Creating product with variants GraphQL Admin API Troubleshooting rest-migration , general-gql-troubles	15	742	July 25, 2025
Adding category metafields via GraphQL Admin API Custom Data metafields	1	153	November 28, 2024

Creating products & variants with linkedMetafield

Related topics