Basics of batch uploading product images to ZIP

Catalog media batch uploads transfer a large number of product images from a single ZIP file to the store's product image repository. The service uploads the package in parts, processes it in the background, and displays the results of each package entry.

Batch upload saves images with their filenames. It does not associate the image with a product or infer the product from the product code.

Prepare the ZIP file

Prepare for a batch upload of catalog media by collecting supported images into a single .zip package. Supported extensions are JPG, JPEG, PNG, GIF, WEBP, AVIF, and SVG. The service also checks the file content to ensure that it matches the extension.

Use filenames that are referenced in the product image data. Do not include encrypted files, symbolic links, absolute paths, or .. path components. Directories, files starting with a dot, and __MACOSX entries are ignored.

The limits for individual images, number of files in a package, total extracted size, and downloadable ZIP file come from the server settings. The user interface does not display their current values before the download.

Start batch upload

Open Catalog Media Batch Uploads at /products/media/batch-upload . Select New Batch Upload and open the Upload Product Image ZIP card.

Select a single ZIP file and press Start Download . The browser creates a batch, transfers the file in parts specified by the service, completes the multi-part download, and queues the batch for processing.

Do not close the page during a file transfer. If the transfer fails, the browser will attempt to abort the incomplete multipart download. Correct the error and start a new batch; the same failed transfer will not be resumed from the user interface.

When the transfer is complete, the page automatically opens the batch details page.

Track the status of the batch

A catalog media batch can progress through the states Uploading Started , Uploaded , Queued , Processing , Completed , Completed with errors , Uploading Aborted , and Failed . The details page automatically updates the incomplete batch: first every two seconds, then every five seconds, and during long processing every ten seconds.

The status panel shows the total count, as well as counters for processed, saved, failed, and skipped entries. The file table shows the index, packet entry, extension, size, result, saved file name, and error code.

Limit files by result using server search. Filename search only filters entries from the currently loaded page, so it is not a full batch search. The table uses cursor-based paging.

Interpret file results

Catalog Media File Result Saved means the image file passed the checks and was written to the product image repository. Ignored means an accepted exclusion, such as a directory, hidden file, __MACOSX entry, or unsupported extension.

Failed indicates a file-specific error. Causes include unsafe path or filename, symbolic link, encrypted content, empty or too large file, total extracted size exceeded, extension and content mismatch, or save error.

Completed with errors can contain both successful and failed files. Filter out the failed and skipped ones, fix only the necessary files, and send them as a new ZIP package.

Attach images to products

Batch upload of catalog media saves the image with the base name used in the ZIP package. The product will only display the image when its main or secondary image field refers to the same filename.

Set up references in product import or in the product media editor. Batch upload does not associate files with products based on the product code, folder, or part of the filename.

Plan your product data import and image batch together. Import images first if necessary, define product references, and check for representative products on the product page, product list, and feeds that use them.

Replacing images

Replacing an image in catalog media with the same filename may overwrite the file in the product image repository. This will not change the product image reference, but caches and image conversions may delay the new content from appearing.

Before mass replacement, make sure the new images match the products in the old filenames. Keep the original files for refund and review a few products before accepting the entire batch.

The batch result indicates whether the save was successful, not whether every version of the image the customer saw changed. Compare the image content and address on the product page and in a managed review that bypasses the cache.

Good to know

Catalog media batch uploads only handle a ZIP package of product images. It is not an import of product documents, media categories, or product data.

The package is processed in parts in a background queue. A working background worker is required for the batch to be completed; a batch that remains in the queue will not be completed by simply refreshing the browser.

File-specific diagnostics are the primary check for the final result. Additionally, confirm the image shown to the customer with the actual product, as a successful save does not prove a product reference or cache refresh.