Choose Don’t replace existing images to add new images after the existing ones, or Replace existing images to clear a product’s gallery before its new images are uploaded. You choose per upload, in step 4 of Create upload.
The two options
| Option | Behaviour |
|---|---|
| Don’t replace existing images (recommended for tests) | New images are added to the product. Existing images are untouched. Re-running the same folder adds duplicates. |
| Replace existing images | Before the first new image of a product is uploaded, all existing images of that product are removed, not only images the app uploaded before, and not only the matched variant’s image. |
How replace mode works
- Removal happens once per product per job, right before that product’s first new image.
- If a product matches no image in this run, its images are not touched.
- With Don’t delete replaced images from ‘Files’ turned on in Settings, old images are detached from the product but kept in Content → Files. Without it they are deleted permanently.
- We can restrict replacement to only the matched variant’s images for your store on request.
Safe testing
- Test replace mode on one product first.
- Turn on Don’t delete replaced images from ‘Files’ so nothing is lost.
- Confirm the gallery ends up with exactly the new set, then run the full batch.
Running the same folder twice
Without replace mode, a second run of the same folder adds the images again. The app can’t know you didn’t intend that. When re-running, use replace mode or unmatch the images you don’t need.
Automatic retries are different: they only process images that failed and never duplicate successful uploads.