Bulk Image Uploader for BigCommerce
🔧 Quick Info: Upload Images lets you add product and variant images to BigCommerce in bulk using one ZIP file containing the images and a CSV file that identifies where each image belongs.
What It Does
Upload Images lets you add images to many BigCommerce products or variants at once instead of uploading them individually through the BigCommerce control panel.
You provide two files:
- A ZIP file containing the image files.
- A supplemental CSV file that tells the tool which SKU each image belongs to, the image filename, its alt text, and whether it should be the main thumbnail image.
The tool reads each row in the CSV, finds the matching image inside the ZIP file, and then looks for the SKU in your BigCommerce store.
- If the SKU matches a product, the image is added to that product.
- If the SKU matches a variant, the image is added to that variant.
- If the image or SKU cannot be found, the row is skipped and reported as an error.
One CSV Row per Image: Every image you want uploaded must have its own row in the supplemental CSV. A product can appear on multiple rows when you are uploading several images to the same SKU.
The upload runs as a background job, so you can close the page after starting it. When the job is complete, you’ll receive an email notification.
If any images could not be uploaded, the completion results include an error spreadsheet showing the affected rows and the reason each one failed.
When Should You Use This?
- You are migrating a catalog and need to add product images in bulk.
- You are refreshing product photography across many SKUs.
- You have a folder of images that need to be assigned to existing products or variants.
- You want to add several additional images to many products.
- You need to assign image alt text in bulk.
- You want to choose which image should be used as the product’s main thumbnail.
- You want to avoid uploading images one product at a time in BigCommerce.
Before You Get Started
- Confirm that the Image Uploader add-on is active for your store.
- Gather all image files into one standard ZIP archive.
- Keep the ZIP file at or below 250 MB.
- Keep each individual image file below 8 MB.
- Prepare a supplemental CSV with one row for every image.
- Make sure the products and variants already exist in BigCommerce.
- Confirm that the SKUs in the CSV match the product or variant SKUs in your store.
- Confirm that every image filename in the CSV matches a file inside the ZIP.
Subscription Required: Upload Images is a paid add-on. If the tool is not active for your store, you’ll be prompted to subscribe before uploading files.
Exact Filenames Required: The image filename in the CSV must match the filename inside the ZIP, including its spelling and file extension.
How to Use It
1 Open the Tool
Open Upload Images from your BigCommerce tools dashboard.
2 Upload the ZIP File
In the Zip File area, upload the ZIP archive containing your product and variant images.
The ZIP can contain images for several products and variants, as long as each image is listed in the supplemental CSV.
3 Upload the Supplemental CSV
In the Supplemental CSV area, upload the CSV that describes the images inside the ZIP.
The CSV must contain one row per image and include columns for the SKU, image filename, alt text, and thumbnail setting.
4 Map the CSV Columns
After the CSV is uploaded, match each spreadsheet column to the corresponding Upload Images field:
- SKU
- Image Name
- Alt
- Thumbnail
All four fields are required.
5 Confirm Notification Settings
Continue to Notification Settings and confirm the email address that should receive the completion notice.
Your account email is filled in by default, but you can change it.
6 Start the Upload
Submit the upload. A confirmation appears to let you know the job has started.
The images are processed in the background, so you can close the page.
7 Review the Results
When the upload is complete, check your email for the completion notice.
If any rows failed, download the error spreadsheet, review the reason for each error, correct the ZIP or CSV, and upload the affected rows again.
ZIP File Requirements
| Requirement | Details |
|---|---|
| File Type | A standard .zip archive. |
| Maximum ZIP Size | 250 MB. |
| Maximum Image Size | Each image must be smaller than 8 MB. |
| Image Names | Every uploaded image must be referenced by its exact filename in the supplemental CSV. |
| macOS Files | The hidden __MACOSX folder and its files are ignored automatically. |
Supplemental CSV Requirements
The supplemental CSV must contain one row for every image you want to upload. Its first row must contain the column headers.
| Column | Required? | What It Does |
|---|---|---|
sku |
Yes | The product or variant SKU where the image should be uploaded. |
image_name |
Yes | The exact filename of the image inside the ZIP, including the extension, such as widget-front.jpg. |
alt |
Yes | The image description or alt text saved with the image. |
thumbnail |
Yes | Indicates whether the image should be used as the product’s main thumbnail image. |
Example CSV
| sku | image_name | alt | thumbnail |
|---|---|---|---|
| WIDGET-100 | widget-front.jpg | Front view of Widget 100 | Yes |
| WIDGET-100 | widget-side.jpg | Side view of Widget 100 | No |
| WIDGET-100-RED | widget-red.jpg | Widget 100 in red | No |
How Images Are Matched
Each CSV row must pass two checks before an image can be uploaded:
- The value in
image_namemust match an image inside the ZIP. - The value in
skumust match a product or variant in BigCommerce.
| Match Result | What Happens |
|---|---|
| Image found and product SKU found | The image is uploaded to the product. |
| Image found and variant SKU found | The image is uploaded to the variant. |
| Image not found in ZIP | The row is skipped and reported as an error. |
| SKU not found in BigCommerce | The row is skipped and reported as an error. |
Troubleshooting and FAQ
The error says “Image not found in zip file”
The value in the CSV’s Image Name field does not match an image inside the ZIP.
Check the spelling, capitalization, spaces, and file extension. For example, widget.jpg and widget.jpeg are different filenames.
The image was not processed because the SKU was not found
The SKU does not match an existing product or variant in your BigCommerce store.
Confirm that the item exists and check the SKU for typing errors, spaces, punctuation differences, or confusion between a product SKU and a variant SKU.
Some images uploaded and others did not
This is expected when only certain CSV rows contain errors. Successful rows are processed, while failed rows are listed separately in the error report.
Correct only the failed rows and upload them again.
The ZIP file will not upload
Confirm that the file is a valid .zip archive and that its total size does not exceed 250 MB.
Also confirm that every individual image inside the archive is smaller than 8 MB.
The CSV column names are different
Your CSV headers do not have to use the exact example names. After uploading the CSV, map your columns to SKU, Image Name, Alt, and Thumbnail.
The wrong image became the thumbnail
Review the Thumbnail values in the supplemental CSV. Mark the image you want as the main product image and make sure the other images for that product are not also marked as the thumbnail.
Where is my completion notice?
Check the inbox and spam folder for the email address shown on the Notification Settings step.
The upload runs in the background, and the completion email is sent after the full job finishes.