Shopify product-media guide
Prepare, match, review, then upload.
A practical workflow for structured image folders, SKU, product-ID or handle matching, gallery order, and controlled review.
Direct answer
For a small number of Shopify products, the reliable native route is to open each product in Shopify Admin and add media in its Media section. For a prepared folder that must be applied across many products, first give every image file one stable identifier - SKU, product ID, or handle - then match the files, inspect the matches, and upload only after correcting exceptions. Shopify limits each product to 250 total media items, so a bulk process cannot bypass a full product gallery. [1]
BL Bulk Product Image Uploader is designed for the matching and upload step. Its Shopify workflow supports filenames matched by SKU, Shopify product ID, or product handle. In SKU mode, it also offers exact, prefix, and delimiter matching. It does not decide whether a photograph is accurate for a product, repair inconsistent catalog data, or remove the need to review the resulting product gallery. [2]
When a bulk workflow is appropriate - and when it is not
A bulk matching workflow is most useful when a supplier refresh, migration, seasonal range, or internal content project has produced a structured image library. The work still begins with data hygiene: the product identifiers in the store must be trustworthy, and the people preparing images must use the same identifier convention.
| Situation | Better approach | Why |
|---|---|---|
| You need to add one or two images to a few products. | Use Shopify Admin’s native product-media editor. | It is faster to inspect each product directly than to prepare a batch. |
| You have a folder of images already named with correct SKUs, IDs, or handles. | Use a controlled bulk matching workflow. | The identifiers can be reviewed before upload and reused in a repeatable process. |
| Your SKUs are duplicated, incomplete, or inconsistent. | Fix catalog data first, or match manually. | A file name cannot safely resolve an ambiguous product record. |
| A product already has a carefully curated gallery. | Start with Add Images, not overwrite. | You can review the new images without deleting current media. |
| A product is already near Shopify’s 250-media maximum. | Remove unneeded media or redesign the product structure before adding more. | Shopify’s per-product media limit cannot be raised. [1] |
Start with Shopify’s native product-media option
Shopify lets merchants add media directly from a product’s Media section. You can upload a new file, drag and drop it, select an existing file, or add an eligible item from a URL. Shopify also lets you arrange product media; the first media item becomes the featured or main item used in several store contexts. [1]
That native route is usually best for small edits. A bulk matching tool is useful when manually opening every product would create repetitive work and you already have a disciplined input folder. The goal is not merely “upload many files.” It is to produce an auditable mapping between each file and the correct product before changing the storefront.
Choose one identifier for the whole batch
Do not mix matching methods in one folder unless you are deliberately running separate batches. Choose the field that is complete, stable, and unique in the affected catalog.
| Matching method | Use it when | File-name example | Important note |
|---|---|---|---|
| SKU | Product or variant SKUs are maintained consistently. | TSHIRT-RED.0.jpg | Best choice when images are prepared around a SKU convention. The app offers extra SKU matching modes. |
| Product ID | You have a trusted Shopify product export with numeric product IDs. | 9876543210.1.webp | Keep the full numeric product ID before the order segment. |
| Handle | Product handles are stable and easier for the content team to use. | summer-canvas-tote.2.png | Use the exact Shopify product handle, not a product title. |
Before a full run, pick three representative products and confirm that the selected identifier in the image filename exactly matches the intended record in Shopify. This small check is more valuable than discovering a systematic naming error after hundreds of uploads.
Name image files to control the intended order
The Shopify uploader reads a file in either of two forms:
identifier.extension
identifier.orderIndex.extension
An unnumbered file uses order index 0. A number immediately before the final extension is the intended order index. In practical terms, use .0 for the image you want to appear first, then .1, .2, and so on for the rest of the planned gallery.
| Filename | Identifier read by the app | Planned order |
|---|---|---|
TSHIRT-RED.jpg | TSHIRT-RED | 0 |
TSHIRT-RED.1.jpg | TSHIRT-RED | 1 |
TSHIRT-RED.2.webp | TSHIRT-RED | 2 |
summer-canvas-tote.0.png | summer-canvas-tote | 0 |
9876543210.3.jpg | 9876543210 | 3 |
Important: dotted identifiers that end in a number
A final numeric segment is always treated as an order index. That means an identifier such as 233.44.56 is ambiguous if the file is named 233.44.56.jpg: the final 56 can be interpreted as the image order instead of part of the identifier.
Use an explicit final order slot instead:
Avoid: 233.44.56.jpg
Use: 233.44.56.0.jpg
The second name preserves 233.44.56 as the identifier and tells the uploader that this is the first planned image. This is especially important where supplier SKUs include periods and end with a number.
Understand Shopify SKU matching before you run Match All
In SKU mode, the Shopify uploader offers three matching modes. Exact is the safest default when every file identifier should equal one store variant SKU. Use prefix or delimiter only when your catalog’s naming convention makes the result unambiguous.
| Mode | How it works | Good use case | Example that matches | Main risk |
|---|---|---|---|---|
| Exact | The file identifier and variant SKU must match after the selected comparison rule. | A clean one-to-one SKU convention. | File 123456.jpg and SKU 123456. | A suffix or formatting difference prevents a match. |
| Prefix | The Shopify variant SKU must start with the file identifier. | A stable base SKU followed by variant attributes. | File 123456.jpg and SKU 123456-RED-2024. | A short or shared prefix can match the wrong product. |
| Delimiter | The values are compared using the part before a selected delimiter, such as |. | A catalog that stores a common root SKU followed by a delimited suffix. | File 123456.jpg and SKU 123456|SMALL. | It can hide a meaningful suffix if the convention is not documented. |
Use exact matching whenever possible. If you choose prefix matching, make the identifier long enough to identify one intended product or variant. A prefix that appears at the start of several SKUs is not a safe batch key. For delimiter matching, confirm the delimiter convention with the person who owns the product data and test it against real products first.
Match first; upload second
A reliable batch is a two-stage process. First, Match All reads the prepared identifiers and looks for the corresponding product records. Then you inspect the match table before choosing upload. Do not treat an automatic match as an approval step.
Review the following for every exception:
| Match-table result | What it means | What to do next |
|---|---|---|
| Correct product shown | The file identifier found the intended product. | Confirm the identifier and planned order, then leave it matched. |
| No match | The app could not find a product for that identifier. | Check the selected method, correct the filename/identifier, or use the manual product picker. |
| Unexpected product | The identifier convention is not unique enough or the wrong method was selected. | Stop the batch, correct the source data, and retest with a small sample. |
| Several images for one product | The files will be sorted by their numeric order index. | Check that .0, .1, .2 reflect the desired gallery order. |
The purpose of a no-match result is to prevent a silent attachment to an arbitrary product. Resolve no-match files before upload, or remove them from the batch and handle them separately.
Product images versus Shopify variant images
By default, the workflow adds images to the matched product’s media gallery. In the SKU workflow, the app also provides an option to assign the uploaded image to the matched Shopify variant once the media is ready.
Shopify itself permits one assigned image per variant. The rest of the related images can remain in the product gallery, where customers can browse them after selecting a variant. [3]
This distinction matters. Do not promise a separate, complete image gallery for every variant merely because a product has variants. Use the variant-image option when one representative image should be associated with a matched variant, and keep the product gallery ordered so related images appear together.
| Goal | Recommended Shopify approach |
|---|---|
| Add multiple images to the product gallery. | Match by SKU, ID, or handle; upload to the product. |
| Associate one uploaded image with a specific variant. | Use SKU matching and the app’s variant-image option. |
| Show several related images after a customer chooses an option. | Arrange the product gallery deliberately and use Shopify’s native product/variant media behavior. [3] |
Add Images versus Overwrite Images
Add Images is the conservative option. It keeps current product media and appends the new matched files, allowing the merchant to review the result before removing anything manually.
Overwrite Images is a destructive operation. In the inspected implementation, existing product media are removed before the new product-media flow proceeds. Do not use it until the file names, match results, and expected gallery outcome have been tested on a small non-critical set of products.
Pre-publication caution: The current source review found implementation limits that require regression testing for products with more than 50 existing media items. Until that test is complete, do not position overwrite as a universal “replace every gallery safely” feature.
A practical safety sequence is:
- Export or record the current product identifiers and keep the original image folder.
- Test Add Images on one representative product.
- Verify the match, the new gallery order, and the featured image.
- If replacement is truly required, test Overwrite Images on a separate low-risk product first.
- Only then decide whether a wider run is appropriate.
Keep the browser open and review the result
The upload workflow is designed to show matching and upload progress. Do not close the browser tab, refresh the page, or put the device to sleep while a batch is running. The final result should be reviewed as a list of successful and failed files, not assumed from a progress bar alone.
After completion, open several affected Shopify products and check the following:
| Review point | Why it matters |
|---|---|
| The first image is correct. | Shopify uses the first media item as the product’s main media in important store contexts. [1] |
| Gallery order matches the numbered source files. | Numbering is a plan; a storefront review confirms the result. |
| Variant assignment is correct where used. | A variant can have one assigned image. [3] |
| No-match or failed files are resolved. | A partial result should lead to a small correction batch, not a blind rerun. |
| The product remains below 250 total media items. | Shopify cannot increase this per-product limit. [1] |
Troubleshooting
My filename matched the wrong product
Stop before uploading the batch. Check whether you selected the wrong matching method or used a non-unique prefix. For a SKU batch, switch to exact matching if the store has clean SKUs. For a prefix or delimiter convention, lengthen the file identifier or correct the underlying SKU data so it resolves one intended record.
The final number in my SKU disappeared from the match
The file name may have been parsed as an identifier plus order index. Rename a dotted identifier that ends in a number to include an explicit order segment. For example, change 233.44.56.jpg to 233.44.56.0.jpg.
A file shows “No matching product found”
Confirm that the filename uses the selected type of identifier. A handle batch requires the Shopify product handle, not the visible product title. A product-ID batch requires the numeric Shopify product ID. If the catalog value is correct but a match still fails, use the manual picker for that file and record the naming issue before the next bulk run.
I need images for variants
Use SKU matching and the variant-image option only when the file should be assigned as the single representative image for the matched Shopify variant. Shopify’s platform model supports one assigned image per variant; additional related images belong in the product gallery. [3]
The product is already at Shopify’s media limit
Shopify allows a maximum of 250 images, 3D models, or videos per product. Remove obsolete media or consider splitting the product structure before adding more. The limit cannot be raised. [1]
Should I use overwrite for a large catalogue refresh?
Only after a controlled test. Overwrite changes existing product media, so it should be tested first on a low-risk product with a known gallery. Keep the original image library and verify the result before extending the workflow to additional products.
Frequently asked questions
Can I bulk upload Shopify product images by SKU?
Yes. The app’s Shopify workflow can match filenames using a product or variant SKU. Use exact matching unless your catalog has a documented, unambiguous prefix or delimiter convention. [2]
Can I use a Shopify product ID instead of a SKU?
Yes. Select product-ID matching and use the numeric Shopify product ID as the file identifier. Keep the order number immediately before the extension if you need to control sequence.
Can I match files by Shopify product handle?
Yes. Select handle matching and use the exact Shopify product handle in the filename. Do not substitute the visible product title for the handle.
What image file types should I prepare?
The app’s Shopify file validation accepts JPEG, PNG, GIF, and WebP. Shopify’s overall product-media system supports broader media types, but a bulk guide should use the app’s verified formats for this workflow. [1] [2]
Can I make the second image appear after the first one?
Use numeric order segments such as .0, .1, and .2 before the file extension, then verify the resulting gallery. The number prepares the intended sequence; the post-upload gallery review confirms it.
What does prefix matching mean?
Prefix matching checks whether the Shopify variant SKU begins with the file identifier. For example, 123456.jpg can match 123456-RED-2024. Use it only when that prefix points to one intended SKU.
Can the app assign images to variants?
On Shopify, the SKU workflow includes an optional variant-image assignment step. Shopify supports one assigned image per variant, while additional related images remain in the product gallery. [3]
Does the app bypass Shopify’s 250-media limit?
No. Shopify limits each product to 250 total media items, and that limit cannot be raised. [1]
Backlip fit and next step
If your Shopify image folder is already structured around reliable SKUs, product IDs, or handles, BL Bulk Product Image Uploader can reduce repetitive matching work. Start with a small, reviewable batch; use the Shopify App Store listing for current installation and plan details. [2]
The accurate outcome is not “upload everything instantly.” It is a repeatable process in which files, identifiers, product matches, gallery order, and exceptions are visible before the storefront changes.
References
[1] Shopify Help - Adding product media
[2] BL Bulk Product Image Uploader - Shopify App Store
[3] Shopify Help - Adding images to product variants