Heyy,
Better File Name and ALT Text means better SEO. I am updating filename [MediaImage] and alt text using fileUpdate mutation.
The API works smoothly. But one thing I noticed is that, the images used inside the content body does not get the new file name or alt text. And the file url has a query parameter like zotac-geforce.png?v=1764585516 which have 1 year cache validity.
So, If I rename the file initially the contents are okay but after one year will all the content start breaking as the cache will be missing and files are renamed.
The image has following response headers.
cache-control: public, max-age=31557600
cf-cache-status: HIT
1 Like
Hey @illusionist3886, could you share more about how you’re implementing images in the content body? I’m curious what “content body” refers to here. ie, product descriptions, blog posts, metafields, or something else? How are the images embedded? Raw HTML <img> tags, file references, or another method?
Also, after renaming, are the images currently displaying or already broken? If the old URL stops working after a rename, I’d expect images to break immediately rather than after cache expires, so I want to make sure I understand your setup.
By “content body” I refers to “Description” (HTML Version) of Product,Article,Collection etc.
Step 1: We can add image from editor and it gives the flexibility to choose from media library.
Step 2: The image with alt text is pushed to content/editor.
Step 3: We can see the image in online store.
Step 4: We change image name and alt text from “Files” option or “fileUpdate” mutation.
Step 5: The content’s image is not updated (neither name nor alt text)
Step 6: The content still show the image as it’s cached for 1 year. [It works in incognito too]
Assumption is, after 1 year passes the image cache will be invalidated and browser might try to load original image but that’s not available as name is changed.
Question, we need to update image name and alt text. What is the safest way?
Note: [The issue does not occur for “media” or featured image feature. It only happens to Conents image.]
YT for reference: https://youtu.be/LHomP0OWs_I
Thanks for the clarification and the video! Your assumption that embedded description images will break after rename is correct.
When you embed an image via the rich text editor, it inserts a static HTML string directly into the body HTML, including the alt text: <img src="cdn.shopify.com/.../old-name.jpg?v=123" alt="your alt text">. That HTML lives in the description field and doesn’t update when the source file changes.
There’s an important distinction with fileUpdate: replacing file content (new image, same filename) keeps the URL intact. However, renaming a file changes the actual path, breaking the old URL.
For SEO-driven file renaming, the safest approach is to name files correctly before embedding them. For existing embedded images, after renaming you’ll need to update the body HTML too. Either manually in Admin, or via API (productUpdate, articleUpdate, etc.) to find/replace the old URL with the new one.
Description fields store raw HTML, not dynamic file references. This is different from media/featured images (like ProductImage), which are database relationships that follow the file.