I am setting up a Shopify Flow to add a free gift to orders that contain a specific native bundle. I need to cap this promotion at exactly 500 orders. Since Flow doesn’t have a built-in counter, could someone provide the JSON for a Send Admin API Request (or a Run Code snippet) that checks a shop-level Metafield counter and increments it by 1 each time the gift is added, stopping the flow once it hits 500?
Hi @tatiaa
This is Vineet from Identixweb, a Shopify Development Agency.
Yeah, I’d be careful trying to handle this with a simple flow metafield counter.
A basic shop-level metafield counter can work for a rough cap, but it is not ideal for an exact 500-order limit because two orders can trigger the Flow at almost the same time. Both could read the same counter value before it updates.
Also, shopify flow’s Run code action can calculate values, but it can’t make API calls or update the shop by itself. For updating the counter, you’d need Update shop metafield or Send Admin API request with metafieldsSet.
A basic JSON for metafields set would look like this:
{
“metafields”: [
{
“ownerId”: “{{ shop.id }}”,
“namespace”: “promotions”,
“key”: “free_gift_counter”,
“type”: “number_integer”,
“value”: “{{ shop.metafields.promotions.free_gift_counter.value | default: 0 | plus: 1 }}”
}
]
}
Then, your flow logic would be:
-
Order created
-
Check the order contains the specific bundle
-
Check the shop metafield counter is less than
500 -
Add the free gift
-
Increment the shop metafield counter
-
Add an order tag like
free-gift-added
But for an exact cap, I’d recommend using the free gift product’s inventory as the real limiter. Set the gift SKU inventory to 500, don’t allow overselling, and let Flow add the gift only when inventory is available. Shopify even has a Flow template for adding a free item to new orders when the item is in stock.
If you still want a true counter-based setup, the safer version is to use metafieldsSet with compareDigest, because Shopify supports compare-and-set for handling concurrent metafield updates. But that’s more advanced and may need a custom app/webhook if you want it to be 100% reliable.
Usually you do not need an API call or Run code for this.
You can reference the shop metafield directly in a conditional and then there is an action to update shop metafield.
However, the race condition is quite possible.
How fast those orders are coming in?
If race condition is a possibility and your 500 limit is strict, then setting the inventory on a free gift product is an easier way of ensuring this.
Using metafieldsSet with compareDigest may be problematic since Flow native tools do not expose the compareDigest values.
Running a GraphQL query is also not possible natively.
One can use “Send HTTP request” to perform a GraphQL query (to obtain both metafield value and digest) but this would require getting an Access token which is also complicated beyond the scope of the forum.
Finally, if the digest do not match the system will return an error, which will likely break the flow.
Use the free gift product’s own inventory as the limiter. Set the gift SKU to 500 units, disable overselling, and let Flow add it only when inventory is available. Shopify handles the concurrency for you, and there’s even a built-in Flow template for this exact pattern.
To achieve this in Shopify Flow, you can use the Send Admin API Request action with a GraphQL mutation to update your shop metafield. First, ensure your flow starts with an order created trigger and checks if the specific bundle is present and if the current shop metafield counter is less than 500. If the conditions are met, use the add order line item action to give the free gift.
Right after that, add the Send Admin API Request action using the POST method to the graphql.json endpoint. Your query should use the metafieldsSet mutation, targeting your shop ID as the owner, and for the value, you can use standard Liquid math like {{ shop.metafields.custom.gift_counter | plus: 1 }} to increment the number automatically.
Hope this helps.