Editing Variant Options with Category Metafield

The situation…

You would like to edit a variant option on your product using our app. To do this, you create a task within the Variants & Options task function — such as Add a Variant Option Value (for multiple variants).

You can check our How to Edit Product Variants for a full overview of variant editing tasks available in the app.

However,

The task log may be labelled Failed, with an unfamiliar error in the task log.

What does the error mean?

This error indicates that the variant option is linked to a category metafield, which prevents certain edits from being made through a standard variant task.

A variant option is considered connected to a category metafield if, in the Variants section of the product page in Shopify Admin, the option values appear highlighted in blue with a link icon on the right:

Similarly, the Category Metafield section will display an icon indicating it is connected to a variant option:

Can I still edit my variants?

Yes — the app now includes dedicated tasks for managing variant options linked to category metafields. See the section below.

As a general rule: if the variant value you are adding already exists in the linked metaobject list, a standard Add a Variant Option Value task will still complete successfully. The error only occurs when attempting to add a value that does not exist in the metaobject.

In this article...

App Tasks for Category Metafield-Linked Options
Manual alternative: Disconnecting from Shopify Admin
Reconnecting Metafield–Option Value (After Manual Edits)

App Tasks for Category Metafield-Linked Options

The app now supports three dedicated tasks for working with variant options linked to category metafields. These are found within the Variants & Options task function.

1. Replace Text in Variant Option Value (Linked to Metafield)

Use this task if you want to change the option value of a product option that is linked to a category metafield (also called a metaobject).

Example: If the product option Color is linked to the Color metaobject and has values Red and Blue, this task can be used to change Red to Yellow.

Note: The replacement value (e.g., Yellow) must already exist as an entry in the metaobject. If it does not, the change will be skipped for that product.

You can specify multiple changes in a single task by clicking the Add Option Values button — however, all changes must be under the same product option. For example, you can change Red → Blue and Yellow → Green in one task, as long as both belong to the same option.

2. Link Product Options to Category Metafields

Use this task if you want to connect a product option to a category metafield (metaobject). This links each of the option's values to its corresponding entry in the selected metaobject definition.

Example: If a product has an option named Color and you select the Color metaobject definition, each option value (e.g., Red, Blue) will be linked to the matching metaobject entry with the same display name.

Note: The display names of the metaobject entries must exactly match the option value names (case sensitive). If a match is not found, the product will be skipped.

This task will only connect options that are not already linked to a metafield. Products whose option is already linked will be skipped.

You can connect multiple product options at once by clicking the Add another link button.

3. Unlink Product Options from Category Metafields

Use this task if you want to disconnect a product option from its category metafield (metaobject). This removes the link between the option and its metaobject definition.

Example: If a product has an option named Color that is linked to the Color metaobject definition, this task will unlink it so the option values are no longer connected to metaobject entries.

This task will only disconnect options that are currently linked to a metafield. Products whose option is not linked will be skipped.

Note: Option name matching is case sensitive.

You can disconnect multiple product options at once by clicking the Add another option button.

Manual alternative: Disconnecting from Shopify Admin

If you prefer to manage the link directly in Shopify, or if only a small number of products are affected, you can also disconnect and reconnect manually. Note that if multiple products are affected, you will need to do this for each one individually.

Open Shopify Admin and select the product with the linked variant option.
In the Variants section, locate the option with the blue-highlighted values and link icon.
Click the icon, then tap Disconnect. Confirm in the pop-up by clicking Confirm, then Done.
Click Save to apply the changes.

Reconnecting Metafield–Option Value (After Manual Edits)

After editing variants manually in Shopify Admin, you can reconnect the option to its category metafield. When reconnected, the category metafield will automatically copy over the values from the variant option.

Important: Doing the reverse — adding a value to the category metafield first and then connecting it to a variant option — will result in the value being removed. Always reconnect from the variant option side.

Alternatively, use the Link Product Options to Category Metafields task described above to reconnect in bulk.

Need help?

If you need any assistance or have questions about this feature, feel free to reach us at help@hextom.com.