Shopify Flow: Untangling 'Invalid Variable' Errors in Admin API Metafield Updates

Hey fellow store owners and automation enthusiasts! It's your Shopify migration expert here, and today I want to dive into a really common, yet often frustrating, technical hiccup we see in the Shopify community: the dreaded 'invalid variable' error when using the Admin API request action within a Shopify Flow, especially when you're trying to update metafields in a loop. I recently saw a fantastic discussion unfold on the Shopify Community forums that really highlighted the nuances of this problem, and I wanted to break it down for you.

The original post, from a merchant named mn175787, detailed a very practical use case: setting up a scheduled Shopify Flow to track product variant cost changes (synced from a service like Printful). The idea was brilliant: store the last known cost in a metafield, then compare it daily and send an alert if it changed. Simple, right? Well, not quite, as they kept hitting an "getProductVariantData_item is invalid" error in their

metafieldsSet

mutation.

The Root of the Problem: Variable Scope in Loops

The first and most critical insight came from community members Maximus3 and tim_tairli. They immediately zeroed in on the variable naming. When you're working inside a "For each" loop in Shopify Flow, the variables for the current item in that loop don't just use the name of your initial "Get data" step (like

getProductVariantData_item

). Instead, they need to include "Foreachitem" in their name.

So, if mn175787 was trying to reference the variant ID or cost like this:

getProductVariantData_item.id
getProductVariantData_item.inventoryItem.unitCost.amount

The correct way to reference them inside the loop would be:

getProductVariantDataForeachitem.id
getProductVariantDataForeachitem.inventoryItem.unitCost.amount

This is a subtle but crucial distinction! As tim_tairli rightly pointed out, it's always best practice to use the "Add variable" button within Flow. It's usually smart enough to suggest the correct variable names, including that all-important "Foreachitem" prefix when you're in a loop context.

There was also a mention of ensuring the "Send Admin API request" action itself is actually configured to run "for each item" and not "after last item." If it's outside the loop's context, those item-specific variables won't exist at all, leading to similar errors. Always double-check your Flow's branching and action placement!

Metafield Mysteries: Data Types and GIDs

Beyond the loop variable, lumine dropped some fantastic knowledge about the specific quirks of the

metafieldsSet

GraphQL mutation. This is where things get a bit more granular:

1. Value Must Be a String (Even for Numbers)

This one catches a lot of people! Even if your metafield is defined as a

number_decimal

or

money

type, the

value

field in your GraphQL variables JSON *must* be passed as a

String

. As lumine explained, you cast the number to a string, and then the

type

field of the metafield definition tells Shopify how to interpret that string (e.g., as a number).

So, while you might have:

"value": "{{getProductVariantDataForeachitem.inventoryItem.unitCost.amount}}",
"type": "number_decimal"

The key is ensuring that

{{getProductVariantDataForeachitem.inventoryItem.unitCost.amount}}

resolves as a string within that JSON. Flow usually handles the string conversion for you when you put it inside quotes, but it's a good mental note: GraphQL expects that

value

to be a string.

2. The Full Variant GID is Required for

ownerId

Another common mistake is supplying just the numeric ID for

ownerId

. For GraphQL mutations like

metafieldsSet

, you need the Global ID (GID) of the resource. This looks something like

gid://shopify/ProductVariant/123456789

, not just

123456789

. Make sure your variable resolves to the full GID.

3. Handling Null Values Gracefully

Lumine also brought up an excellent point about third-party integrations. If a service like Printful sometimes returns a

null

cost for a variant, and that

null

flows into your GraphQL variables block, it's going to be rejected as an invalid value. It's always a good idea to consider adding a condition in your Flow to check if the value exists before attempting to set the metafield, or provide a default value if it's

null

.

Putting It All Together: Your Action Plan

Based on the community's collective wisdom, here's a step-by-step guide to troubleshooting and fixing these 'invalid variable' errors in your Shopify Flow Admin API requests for metafields:

1. Verify Your "For each" Loop Setup:

   • Ensure your "Send Admin API request" action is actually *inside* the "For each" loop, meaning it runs for *each item*, not "after last item."
   • If you're unsure, try recreating the action and using the "Add variable" button to guide you.

2. Correct Your Variable Naming:

   • Inside a "For each" loop, variables referencing the current item *must* include "Foreachitem" in their name.
   • Change variables like

     getProductVariantData_item.id

     to

     getProductVariantDataForeachitem.id

     and

     getProductVariantData_item.inventoryItem.unitCost.amount

     to

     getProductVariantDataForeachitem.inventoryItem.unitCost.amount

     .

3. Ensure

   ownerId

   is a Full GID:

   • For the

     ownerId

     field in your

     metafieldsSet

     mutation, use the full Global ID (GID) of the variant. This typically looks like

     gid://shopify/ProductVariant/123456789

     .
   • When you use the "Add variable" picker, ensure you select the variable that provides the GID, not just the numeric ID.

4. Confirm

   value

   is Passed as a String:

   • Even if your metafield is a number type (

     number_decimal

     ,

     money

     ), the

     value

     field in your GraphQL variables JSON must be a

     String

     .
   • Flow usually handles this by placing the variable in quotes, but double-check your JSON structure.

5. Implement Null Value Checks:

   • If your data source (like Printful) can return

     null

     for values you're trying to set, add a condition in your Flow to check for

     null

     before attempting the

     metafieldsSet

     mutation.
   • Alternatively, you could use a "Liquid" step to provide a default value (e.g., "0") if the original value is

     null

     .

It's amazing how a few small details can make or break a powerful automation. The Shopify Flow tool is incredibly robust, allowing you to build sophisticated workflows that save tons of time and keep your store running smoothly. But, as this community discussion shows, understanding the precise syntax and data requirements for its advanced features, especially when interacting with the Admin API, is key. Don't get discouraged by these errors; they're just part of the learning curve! Keep experimenting, keep asking questions in the community, and you'll master these flows in no time.