How to Replace a Shopify Product Image Without Breaking Your Theme | AssetScope
Replacing a product image in Shopify sounds simple. In practice, it carries a hidden risk that can break parts of your store silently, with no error message and no warning. Understanding this risk — and how to mitigate it — is essential for any merchant who regularly updates their product photography. If you manage product images regularly, AssetScope’s Shopify image optimiser automates the entire safe-replacement workflow described below.
Why Replacing Shopify Images Is Risky
When you upload an image to Shopify, it is assigned a permanent CDN URL. This URL includes a unique hash: something like cdn.shopify.com/s/files/1/0123/4567/files/product-hero.jpg?v=1234567890.
If you delete that image and upload a new one (even with the same filename), Shopify generates a completely new URL. Any place that referenced the old URL — whether in your theme’s Liquid code, a metafield, a page’s rich text, or a custom section — now points to a broken link.
The result is a silent failure. No 404 error page. The image simply disappears from the part of your store that referenced the old URL. You may not notice for days or weeks, and neither will most of your customers — until a banner image is missing, a featured product card shows a broken image, or a review screenshot surfaces it.
How Shopify’s CDN URL System Works
Every image you upload to Shopify is stored on Shopify’s global CDN (Content Delivery Network), powered by Cloudflare. Shopify assigns each image a URL that includes: the store’s internal ID, a folder path, the filename, and a version query parameter (?v=) that changes with every re-upload.
This URL is immutable. Once an image is deleted, its URL is permanently gone. There is no redirect, no fallback, and no way to assign the same URL to a new image. Shopify does not offer URL aliasing or image replacement at the CDN level.
This matters because many parts of a Shopify store reference images by their full CDN URL rather than by a dynamic Liquid object. When the URL changes, any reference that was pointing to the old URL now points to nothing.
Understanding this mechanism is the key to understanding why “just replacing the image” in Shopify is not as safe as it sounds — and why a pre-replacement scan is essential.
What Types of Theme References Break
The most common places where Shopify CDN URLs get hardcoded are:
Custom theme sections: Many themes and page builder tools (Shogun, PageFly, GemPages) store image URLs as settings values rather than as product image references. These URLs are hardcoded into your theme customisation and will not update automatically.
JSON template settings: Shopify’s Online Store 2.0 themes store section configuration in JSON files. Image references in these settings are stored as full CDN URLs. If you open your theme code and search for cdn.shopify.com in the templates/ and sections/ folders, you’ll likely find dozens of hardcoded URLs.
Metafields: Image metafields store URLs directly. If you replace a product image and had stored its URL in a metafield for use in a custom section, the metafield now points to a dead URL.
Liquid templates: Developers sometimes hardcode image URLs in Liquid files for one-off customisations. These references don’t update when the image is replaced.
Rich text pages: If you’ve pasted an image URL directly into a Shopify page or blog post using the rich text editor, replacing the image will break that reference too.
Step-by-Step: How to Safely Replace a Shopify Product Image
Follow these steps to replace a product image without breaking any theme references:
Step 1: Identify the image’s current CDN URL. Open the product in Shopify admin, right-click the image, and copy the image address. This is the URL you need to search for.
Step 2: Search your theme files for references. Download your active theme (Online Store → Themes → Actions → Download theme file). Open the ZIP and use a text editor to search for the CDN URL across all .liquid and .json files.
Step 3: Note every file that references the URL. Common locations include sections/*.liquid, templates/*.json, config/settings_data.json, and snippets/*.liquid.
Step 4: Upload the new image to the product in Shopify admin. Copy the new CDN URL.
Step 5: Update every theme reference from the old URL to the new URL. Re-upload the modified theme files or edit them through the Shopify code editor.
Step 6: Delete the old image from the product only after confirming all references are updated.
This process is manual, error-prone, and takes 10–30 minutes per image. For stores that regularly update product photography, it’s not sustainable.
How to Replace Images Safely: The Theme Scan Approach
The safe approach is to scan your active theme’s files for references to the image URL before replacing it. If you find references, you update them to the new URL at the same time as you replace the image.
AssetScope’s replace workflow automates this. When you initiate an image replacement, it scans every file in your active theme (Liquid templates, JSON settings, sections) for references to the current image URL. If it finds any, it shows you exactly where they are before you proceed.
You can then either proceed with the replacement (AssetScope updates the references in the theme files simultaneously) or abort if the scope of the change is larger than expected.
Manual vs. AssetScope: A Comparison
| Task | Manual Method | AssetScope |
|---|---|---|
| Find theme references | Download theme ZIP, search text files manually | Automatic scan, results in seconds |
| Update references | Edit each file individually, re-upload to theme | Updated simultaneously with the image swap |
| Time per image | 10–30 minutes | Under 60 seconds |
| Risk of missed references | High — easy to miss a file | None — every file is scanned |
| Bulk replacement | Not practical | Replace multiple images in one session |
When Image Replacement Is Safe Without a Theme Scan
Not every image replacement carries the same risk. Replacing an image that is only referenced via Shopify’s standard product image association — the images attached to a product variant that your theme accesses through standard Liquid objects like product.featured_image — is safe. These references are dynamic and follow the product object, not the URL.
It’s only hardcoded URL references that break. For most product images on standard themes, image replacement is safe. For images used in customised sections, banners, or page builder blocks, the theme scan is essential.
Fix this in minutes with AssetScope
AssetScope’s Image Optimiser is built for exactly this task — no CSV, no developer, no waiting.
Try FREE — 7 Days on UsSee all 15 tools in AssetScope →
Frequently Asked Questions
Yes. Every image uploaded to Shopify is assigned a unique CDN URL with a hash. Deleting an image and uploading a new one — even with the same filename — generates a completely new URL. Any hardcoded references to the old URL will break silently.
It can. If your theme references the image by its full CDN URL — in section settings, JSON templates, Liquid files, or metafields — then replacing the image changes that URL and breaks the reference. The image will silently disappear from wherever it was used. A theme scan before replacing identifies every reference so you can update them.
Bulk image replacement requires scanning every theme file for every image URL being replaced. Doing this manually is impractical at scale. AssetScope's Image Optimiser lets you replace multiple product images in one session, scanning your theme for references to each image automatically and updating them simultaneously.
Yes. The safe method is: (1) identify all theme files that reference the image's CDN URL, (2) upload the new image, (3) update every reference to the new URL, (4) delete the old image. AssetScope automates all four steps. Manually, you would need to download your theme, search every file for the URL, edit each reference, and re-upload — a process that takes 10–30 minutes per image.
AssetScope's replace workflow scans your active theme's Liquid files, JSON settings, and section configurations for references to the image URL you're replacing. It identifies every reference before you proceed, so you can make an informed decision. Manually, you would need to download your theme and use a text editor to search for the URL — which most merchants cannot do without developer help.
Bulk image replacement carries the same risks as individual replacement, multiplied. We recommend always running a theme scan before replacing any image that might be referenced outside of Shopify's standard product image objects. AssetScope enforces this by making the theme scan part of the replacement workflow.