How to set `optionValues` for a product variant that is linked to a metafield value?

Jacco · April 7, 2025, 9:05am

Hi,

We are trying to set the optionValues, for a product variant where the optionValues that are linked to a metafieldValue, using the productVariantsBulkCreate and/of productVariantsBulkUpdate mutations, and we run into a confusing set of error messages.

Let’s try to update the optionValues with a productVariantsBulkUpdate mutation (for full mutation, see below), for a product option that is linked to a metafield value:

"optionValues": [
  {
    "optionName": "Color",
    "name": "Red",
    "linkedMetafieldValue": "gid://shopify/Metaobject/88683086037"
  }
]

# error message: Cannot set name for an option value linked to a metafield

Ok, let’s remove the name:

"optionValues": [
  {
    "optionName": "Color",
    "linkedMetafieldValue": "gid://shopify/Metaobject/88683086037"
  }
]

# error message: id or name must be specified

Ok… let’s try adding an id instead of a name then?

"optionValues": [
  {
    "optionName": "Color",
    "id": "gid://shopify/ProductOptionValue/3540024983765",
    "linkedMetafieldValue": "gid://shopify/Metaobject/88683086037"
  }
]

# error message: Cannot set id for an option value linked to a metafield

Maybe I need to only provide a linkedMetafieldValue?

"optionValues": [
  {
    "linkedMetafieldValue": "gid://shopify/Metaobject/88683086037"
  }
]

# error message: optionId or optionName must be specified

As you can see, the error message seem to point in a circle. Which kind-off suggests that setting a linkedMetafieldValue through the GraphQL API (version: 2025-04) is not supported?!

Our question

How do we set the optionValue for product options, that are linked to a metafield vale, using the productVariantsBulkCreate and/of productVariantsBulkUpdate mutations?

Thanks in advance!

^{For reference: full GraphQL mutation used:}

// Mutation
mutation ($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
  productVariantsBulkUpdate(productId: $productId, variants: $variants) {
    product {
      id
    }
    userErrors {
      field
      message
    }
  }
}

// Variables
{
  "productId": "gid://shopify/Product/8902245974229",
  "variants": [
    {
      "id": "gid://shopify/ProductVariant/51310185382101",
      "optionValues": (... see above ...)
    }
  ]
}

^{For reference: the following block will update the `optionValues` for a product option that is **not** linked to a metafield value, without error:}

"optionValues": [
  {
    "optionName": "Style",
    "name": "Fancy",
  }
]

# Ok (no errors)

Alan_G · April 7, 2025, 6:45pm

Hey @Jacco just out of curiosity, are you trying to change any part of the option values for those particular variants or swap variant IDs between products?

For example, if you’re trying to rename a product option but keep the metaobjects the same, we’ll return this error. There’s a bit more info in this thread here, but in cases where you need to adjust product options directly, we recommend using something like productOptionUpdate (you can update multiple options with this mutation, including removing, adding, etc.).

Just wondering what your use case is here/if that’s what you’re doing - happy to help out further

Jacco · April 7, 2025, 9:29pm

Hey @Alan_G,

I had read the thread you linked, but it does not solve our issue.

This is part of an App that synchronizes (configurable fields) products between 2 or more stores owned by the same merchant. So when the merchant makes a change to a product on one of those stores, the change is pushed to the other stores.

This particular case comes up when the merchant decides to add a product option that is connected to a metafield (for example ‘color’), or adds a product option value to an existing product options, that is connected to a metafield.

In both cases, we run into the same issue and error messages.

We do use the productOptionUpdate and/or productOptionCreate mutations, before pushing the productVariantsBulkCreate and/or productVariantsBulkUpdate mutations, to make sure the product options are available, at the store the change is being pushed to (because otherwise, we run into other errors), and got the metaobject IDs relevant to the store that is being pushed to.

Also please note that our App’s logic works without errors when creating, updating and/or deleting product options, product option values, and variants, as long as the product option is not linked to a metafield.

^{For reference: I also came across a question over at the community.shopify.com forums, that ran into the same issue: productVariantsBulkCreate: Cannot Set options for Linked Metafield - Shopify Community}

Jacco · April 9, 2025, 9:59am

Hi @Alan_G,

Let me rephrase my question.

Let’s say I have this product, with a single product option (Shape), that is not linked to a metafield:

{
  "product": {
    "id": "gid://shopify/Product/8240700719262",
    "title": "Widget",
    "options": [
      {
        "id": "gid://shopify/ProductOption/10510620131486",
        "name": "Shape",
        "position": 1,
        "linkedMetafield": null,
        "optionValues": [
          {
            "id": "gid://shopify/ProductOptionValue/4139788730526",
            "name": "Square",
            "linkedMetafieldValue": null
          },
          {
            "id": "gid://shopify/ProductOptionValue/4139788763294",
            "name": "Round",
            "linkedMetafieldValue": null
          }
        ]
      }
    ],
    "variants": {
      "nodes": [
        {
          "id": "gid://shopify/ProductVariant/45314272002206",
          "title": "Square",
          "selectedOptions": [
            {
              "name": "Shape",
              "optionValue": {
                "id": "gid://shopify/ProductOptionValue/4139788730526",
                "name": "Square",
                "linkedMetafieldValue": null
              }
            }
          ]
        },
        {
          "id": "gid://shopify/ProductVariant/45314272034974",
          "title": "Round",
          "selectedOptions": [
            {
              "name": "Shape",
              "optionValue": {
                "id": "gid://shopify/ProductOptionValue/4139788763294",
                "name": "Round",
                "linkedMetafieldValue": null
              }
            }
          ]
        }
      ]
    }
  }
}

What GraphQL mutations do I need to do, to add a product option (Color, in this example), that is linked to a metafield:

{
  "product": {
    "id": "gid://shopify/Product/8240700719262",
    "title": "Widget",
    "options": [
      {
        "id": "gid://shopify/ProductOption/10510620131486",
        "name": "Shape",
        "position": 1,
        "linkedMetafield": null,
        "optionValues": [
          {
            "id": "gid://shopify/ProductOptionValue/4139788730526",
            "name": "Square",
            "linkedMetafieldValue": null
          },
          {
            "id": "gid://shopify/ProductOptionValue/4139788763294",
            "name": "Round",
            "linkedMetafieldValue": null
          }
        ]
      },
      {
        "id": "gid://shopify/ProductOption/10510624325790",
        "name": "Color",
        "position": 2,
        "linkedMetafield": {
          "namespace": "shopify",
          "key": "color-pattern"
        },
        "optionValues": [
          {
            "id": "gid://shopify/ProductOptionValue/4139812126878",
            "name": "Blue",
            "linkedMetafieldValue": "gid://shopify/Metaobject/92031156382"
          },
          {
            "id": "gid://shopify/ProductOptionValue/4139812159646",
            "name": "Green",
            "linkedMetafieldValue": "gid://shopify/Metaobject/92609839262"
          }
        ]
      }
    ],
    "variants": {
      "nodes": [
        {
          "id": "gid://shopify/ProductVariant/45314272002206",
          "title": "Square / Blue",
          "selectedOptions": [
            {
              "name": "Shape",
              "optionValue": {
                "id": "gid://shopify/ProductOptionValue/4139788730526",
                "name": "Square",
                "linkedMetafieldValue": null
              }
            },
            {
              "name": "Color",
              "optionValue": {
                "id": "gid://shopify/ProductOptionValue/4139812126878",
                "name": "Blue",
                "linkedMetafieldValue": "gid://shopify/Metaobject/92031156382"
              }
            }
          ]
        },
        {
          "id": "gid://shopify/ProductVariant/45314293530782",
          "title": "Square / Green",
          "selectedOptions": [
            {
              "name": "Shape",
              "optionValue": {
                "id": "gid://shopify/ProductOptionValue/4139788730526",
                "name": "Square",
                "linkedMetafieldValue": null
              }
            },
            {
              "name": "Color",
              "optionValue": {
                "id": "gid://shopify/ProductOptionValue/4139812159646",
                "name": "Green",
                "linkedMetafieldValue": "gid://shopify/Metaobject/92609839262"
              }
            }
          ]
        },
        {
          "id": "gid://shopify/ProductVariant/45314272034974",
          "title": "Round / Blue",
          "selectedOptions": [
            {
              "name": "Shape",
              "optionValue": {
                "id": "gid://shopify/ProductOptionValue/4139788763294",
                "name": "Round",
                "linkedMetafieldValue": null
              }
            },
            {
              "name": "Color",
              "optionValue": {
                "id": "gid://shopify/ProductOptionValue/4139812126878",
                "name": "Blue",
                "linkedMetafieldValue": "gid://shopify/Metaobject/92031156382"
              }
            }
          ]
        },
        {
          "id": "gid://shopify/ProductVariant/45314293563550",
          "title": "Round / Green",
          "selectedOptions": [
            {
              "name": "Shape",
              "optionValue": {
                "id": "gid://shopify/ProductOptionValue/4139788763294",
                "name": "Round",
                "linkedMetafieldValue": null
              }
            },
            {
              "name": "Color",
              "optionValue": {
                "id": "gid://shopify/ProductOptionValue/4139812159646",
                "name": "Green",
                "linkedMetafieldValue": "gid://shopify/Metaobject/92609839262"
              }
            }
          ]
        }
      ]
    }
  }
}

If we know which GraphQL mutations are needed to make this happen, we can most likely figure out the rest on our own

^{For reference: the query used to fetch the GraphQL data:}

# query
query ($id: ID!) {
  product(id: $id) {
    id
    title
    options {
      id
      name
      position
      linkedMetafield {
        namespace
        key
      }
      optionValues {
        id
        name
        linkedMetafieldValue
      }
    }
    variants(first: 10) {
      nodes {
        id
        title
        selectedOptions {
          name
          optionValue {
            id
            name
            linkedMetafieldValue
          }
        }
      }
    }
  }
}

# variables
{
  "id": "gid://shopify/Product/8240700719262"
}

Alan_G · April 9, 2025, 3:13pm

Hey @Jacco - thanks for clarifying. Generally, you should be able to use the metaobjectCreate and then our recommendation is to use the productSet mutation to link the metafield-linked option to a product. There’s a bit more info in our documentation here: Metafield-linked product options but, the general method would be something like this:

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

variables:

{
  "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"
      }
    ]
  }
}

The Taxonomy Values referenced there can be found here if needed, but you should be able to use any custom metafield as the value. Once the option is linked to a metafield though, you should be able to link option values to the right metaobject entry in the bulk update mutation too.

Hope this helps/makes sense - let me know if I can clarify anything as always here!

Jacco · April 9, 2025, 3:19pm

When you write “(…) and then our recommendation is to use the productSet mutation to link the metafield-linked option to a product.”

Does that mean that the productVariantsBulkCreate and productVariantsBulkUpdate mutations are not supported, when it comes to creating/updating existing products for this use case?

While it is probably possible to build an expensive workaround, we originally decided against using the productSet mutation, because it lacks the granularity we need.

jhardin_accumula · May 7, 2025, 10:57pm

I am seeing similar issues when trying to add a new variant to an existing linked matrix (not updating an existing variant, and not trying to make the matrix linked via the API).

The error messages returned by productVariantsBulkCreate are confusingly conflicting.

This seems to be a simple error in the validation of such a mutation - if a metaobject ID is provided for the optionValue then the name should not be needed as that should come from the displayName on the metaobject.

The documented use of the productSet mutation suggests that’s the proper way to do it:

        optionValues: [
          { optionName: "Size", name: "Small" },
          { optionName: "Color", linkedMetafieldValue: "gid://shopify/Metaobject/70095274073" }
        ]

Metafield-linked product options

It really feels like the validation for productVariantsBulkCreate is incorrectly using semantics that would be appropriate for productVariantsBulkUpdate.

This is blocking an important application fix for us. How do we add new variants to an existing metaobject-linked matrix via productVariantsBulkCreate? Refactoring to use a different mutation just to work around this API bug would be most unwelcome.

Does that mean that the productVariantsBulkCreate and productVariantsBulkUpdate mutations are not supported, when it comes to creating/updating existing ~~products~~ variants for this use case?

…I sure hope not.

jhardin_accumula · May 28, 2025, 7:06pm

@jacco: There is a way around this, the productVariantsBulkCreate mutation will work for meta-linked options - but you need to do some prep work…

Create the MetaObject (already needed to do this) and capture its ID
Repeat as needed for multiple option values being added.
New step: using the productOptionUpdate mutation, add the new MetaObject IDs to the Option on the affected product.
Make sure you provide "variantStrategy": "LEAVE_AS_IS" so that Shopify doesn’t automatically create variants for the new option value(s):

{
  "productId": "gid://shopify/Product/7549509795926",
  "variantStrategy": "LEAVE_AS_IS",
  "option": {
    "id": "gid://shopify/ProductOption/9701258756182"
  },
  "optionValuesToAdd": [
    {
      "linkedMetafieldValue": "gid://shopify/Metaobject/102586810454"
    }
  ]
}

Using the productVariantBulkCreate mutation, create the new variant(s) using the linked option value(s) as was attempted before.
Here is where the “must provide name or ID” error comes in… If you provide the name for the option value in addition to the metaobject ID the mutation now works - the variant(s) are created properly with the linked option values, now that they exist on the product as valid values for the option.

So it may or may not be a validation error in the mutation. It may instead be that the productVariantsBulkCreate mutation can’t add linked options to the product and needs help with that part of the process, and the error message it returns totally obscures that fact.

Ronald_G · September 1, 2025, 12:48am

Thank you @Jacco and @jhardin_accumula . We tried what you suggested, but still keep getting variants > 0 > optionValues > 0 id or name must be specified error when using productVariantsBulkCreate. However, if we add name, we get Cannot set name for an option value linked to a metafield

It used to work in 2025-01, but not in 2025-07 version of the GraphQL. Have you any luck?

The variant input looks something like this as per this Shopify article:

[
  {
    optionValues: [
      {
        optionName: "Color",
        linkedMetafieldValue: "gid://shopify/Metaobject/52316602535"
      }],
  ...
  }
]

Ronald_G · September 1, 2025, 1:24am

Hi @Alan_G

Just to add, the example in Metafield-linked product options doesn’t seem to even work. It raises error “Option ‘Color’ must specify at least one option value.”

Evaldas_Raisutis · October 16, 2025, 8:07am

As someone who’s about to start migrating to the new 2048 variant limit and looking to add linked metaobject options to the integration - this is concerning

Is it still an issue?

Jacco · October 17, 2025, 12:22pm

Yes, unfortunately, it is still an issue to modify the optionvalues for existing products. Creating new ones from scratch is supported through the method described by Alan_G.

soulchild · October 21, 2025, 6:33pm

@Alan_G Any news on this? How should we proceed to add a new variant to an existing product (existing product option matrix), if the option is metafield linked?

Alan_G · October 22, 2025, 2:50pm

Hey @soulchild thanks for hanging in there on this one.

Just want to clarify, is the issue still popping up when you’re trying to add a variant to a product that already has a metafield-linked option set up with some existing variants, or is this a fresh product you’re building out?

Have you had a chance to try the workaround that @jhardin_accumula mentioned? Basically doing a productOptionUpdate first with variantStrategy: LEAVE_AS_IS to add the metaobject as an option value, then running productVariantsBulkCreate with both the name and linkedMetafieldValue fields populated. Just curious where that approach breaks down for you if you’ve tried it or if it’s still not working in newer API versions.

If you can share what your product’s option structure looks like right now (the options and optionValues fields) and the exact mutation you’re running with the error message, that’d help me figure out if we’re looking at a bug or if there’s a specific workflow issue here. Also, just curious, which API version are you on? There’s mention upthread that this might’ve worked in 2025-01 but broken in 2025-07, so I wanted to double check to see if that’s still the case.

One other thought here that I wanted to share in case it helps, have you looked at using productSet for this? The docs show it handling linked options pretty cleanly in one shot, though I know it’s a different mutation, I wanted to share that just in case it helps:

Let me know and I can help out.

jhardin_accumula · October 29, 2025, 4:10pm

Alan_G:

There is still a problem in this that we are unable to work around.

When adding a new variant to a metaoption-linked matrix via productVariantsBulkCreate we (sometimes) run into a situation where the request is rejected apparently due to a data validation error.

For example, here are the options on the variant we’re trying to add:

{"optionValues":[{"name":"Red","optionName":"Color"},{"name":"Large","linkedMetafieldValue":"gid://shopify/Metaobject/157671751977","optionName":"Size (UK)"}]

We are getting this error: {"code":"CANNOT_SET_NAME_FOR_LINKED_OPTION_VALUE","message":"Cannot set name for an option value linked to a metafield"}

Superficially, that is reasonable since it’s a metaobject-linked option - the value name shouldn’t be needed as that’s defined by the metaobject that ID is pointing at.

However, if we remove the name from that request and provide just the metaobject ID, we still get an error:

{ "code": "INVALID_INPUT", "message": "id or name must be specified" }

…and we don’t have an option ID as we’re using the variant bulk create to add the option value to the matrix; we have a linkedMetafieldValue, why is that not sufficient?

So we’re stuck.

It should be possible to add a new variant with a new linked option value to a matrix in one GQL request. Can we get this validation error fixed, so that if we specify both a name and a linked metafield value ID then the variant create will succeed using that option value?

Thanks!

jhardin_accumula · October 29, 2025, 4:25pm

Followup:

Further analysis of this case indicates the matrix at Shopify had that
option linked to a taxonomy we currently don’t support. The new value
was added to the “Size” taxonomy by our code, but the product refused
to accept that metaobject because the product was using the “Shoe
Size” taxonomy. Thus the workaround I suggested earlier failed halfway
through and the productVariantsBulkCreate validation error was not
bypassed.

My comment on the forum still stands: it looks like the
productVariantsBulkCreate mutation can’t add new linked options to the
product. Can that be fixed?

Francois_Rulliere · November 19, 2025, 1:54pm

I came here with a problem and found a solution by myself. Maybe it will help you.

I wanted to have a productSet using linked metafields for update and create. I ended up with this working payload, maybe it will work for you:

{
  "synchronous": true,
  "input": {
    "id": "gid://shopify/Product/10183677346081",
    "productOptions": [
      {
        "name": "Color variant",
        "linkedMetafield": {
          "namespace": "custom",
          "key": "color_variant",
          "values": [
            "gid://shopify/Metaobject/177191977249",
            "gid://shopify/Metaobject/177192468769"
          ]
        }
      }
    ], 
    "title": "test123",
    "variants": [
      {
        "optionValues": [
          {
            "optionName": "Color variant",
            "linkedMetafieldValue": "gid://shopify/Metaobject/177191977249"
          }
        ], 
        "price": "100.00"
      },
      {
        "optionValues": [
          {
            "optionName": "Color variant",
            "linkedMetafieldValue": "gid://shopify/Metaobject/177192468769"
          }
        ] ,
        "price": "200.00"
      }
    ]
  }
}

Topic		Replies	Views
Creating products & variants with linkedMetafield Custom Data metafields	9	210	September 4, 2025
createOptions - productOptionsCreate GraphQL Admin API Troubleshooting general-gql-troubles	1	68	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 Custom Data metafields	1	65	October 16, 2025
How to update product options when the product is using metafield? GraphQL Admin API Troubleshooting rest-migration , general-gql-troubles	2	513	January 2, 2025
Removing/Replacing metaobject variants Custom Data metaobjects	2	45	November 24, 2025

How to set `optionValues` for a product variant that is linked to a metafield value?

Related topics