Bulk image uploads in Shopify can quickly become a nightmare when you’re managing hundreds or even thousands of products. That’s where the Smart Bulk Image Upload app comes in and one of its most powerful features is Metafield Matching.
In this article, we’ll break down:
- What metafields are in Shopify
- How metafield matching works
- When and why to use metafields for bulk image uploads
- Real use cases, like assigning a single image to multiple products
What Are Shopify Metafields?
Shopify metafields are custom data fields you can attach to products, variants, collections, customers, or even orders. Think of them like flexible labels or tags that help store structured, specific information.
A metafield consists of:
- Namespace (like a folder): custom
- Key (the field name): material_code
- Value: MATERIAL-1021
- Type: single_line_text, number, file, etc.
You might already be using metafields to store:
- Technical specs (e.g., battery size)
- SEO metadata
- Product certifications
- Internal codes
But here’s the fun part: you can also use them to match images to products.
What Is Metafield Matching?
Metafield Matching is a feature in the Smart Bulk Image Upload app that links images to products or variants using values stored in metafields instead of relying on SKU, title, or barcode.
This gives you full control over how you organize and assign images especially useful when:
- Your SKUs aren’t unique
- You want to assign one image to multiple products
- You have internal product codes that aren’t public
Matching Modes
The app supports three metafield matching strategies:
Exact Match
Image filename = metafield value
Metafield = goldRing01 → goldRing01.jpg
Metafield Contains Image Name
Metafield includes the image name
Metafield = image:goldRing0100 → goldRing01.jpg
Image Name Contains Metafield
Filename contains metafield value
Metafield = goldRing01 → goldRing01-front.jpg
You pick the match type based on how your images are named vs. how you store values in metafields.(But we use underscores to determine the order of the images 🙂 )
How to Create a Metafield in Shopify
Before you can match images using metafields, you first need to define and populate those metafields inside Shopify. Here’s a step-by-step guide to doing it from the admin interface.
Step 1: Go to Metafields and Metaobjects
- From your Shopify Admin, click Settings (bottom left)
- Then choose Metafields and Metaobjects
This is where you manage metafields for different resources (products, variants, customers, etc.)
Step 2: Select the Resource Type
- Choose either Products or Variants, depending on where you want to attach the metafield
- For images that apply to the whole product → use Product
- For images specific to size/color variants → use Variant
Step 3: Add a Metafield Definition
- Click “Add definition”
- Fill in the fields:
- Name: A readable label (e.g., “Color Code”)
- Namespace and Key: E.g., custom.color_code
- Type: Use Single line text (recommended for image matching)
- Click Save
Step 4: Add Metafield Values
- Go to the actual product or variant page, and click on the product
Scroll down to the Metafields section (bottom of the page)
Enter the value for each product (e.g., black.dress, etc.)
Click Save
That’s it now you can use these metafield values for image matching in the app.
Setting It Up in the App
Once you’ve installed the app:
- In the app settings, choose your Metafield Source:
- Product Metafields: matches at the product level
- Variant Metafields: if you’re assigning images to specific variants
- Enter the Namespace and Key used in your metafields.
Example: custom.color_id - Select the match type:
- Match by Exact Metafield
- Match if Metafield contains image name
- Match if Image name contains metafield
- Upload your images with filenames that align with the metafield values.
- Hit Upload, and the app will automatically assign images based on the match logic.
Use Cases
1. Assigning One Image to Many Products
Let’s say you have 10 different products that all use the same user manual or fabric swatch image.
Instead of uploading the same image 10 times, you can:
- Create a metafield custom.shared_asset = swatch_blue on each product
- Upload a file named swatch_blue.jpg
- Use ‘Match by exact METAFIELD’ to link them all
Done! One upload, multiple assignments saving you time and storage.
2. Variant-Specific Images (e.g., by color)
You sell a T-shirt that comes in 5 colors. Each variant has a metafield:
- custom.color_code = red001, blue001, etc.
Your image files are named:
- red001_front.jpg, red001_back.jpg, etc.
Use the Image Name Contains Metafield match type, and images will be automatically linked to the correct color variants.
3. Internal Product Codes
If your team uses internal codes like MX-2201 to identify products, you can store these in metafields:
- Namespace: internal, Key: sku_alt, Value: MX-2201
Upload an image named MX-2201.jpg, and the app will match it based on metafields even if the public-facing SKU or title doesn’t help.
Final Thoughts
Metafield matching is one of the most underrated features in Shopify’s ecosystem when paired with bulk automation tools.
- It gives you granular control
- Saves hours of repetitive uploading
- Supports scale without breaking structure
If you are managing a small catalogue of products or large ones, mastering metafield matching can seriously optimize your product media workflow.
