File reference (image) Shop metafield not usable in email notifications
Reproduction steps
Create a file reference (image) shop-level metafield with the namespace “custom_fields” and key “email_header_image”. Populate it with any image.
In any transactional email, use one of those snippets to attempt to display the image :
It is currently impossible to output the URL of an (image) file shop metafield in the transactional notifications.
On the online store, it can be displayed in several ways :
In the transactional emails, all of those methods will fail to render, and the only output available is the GID of the media file.
On my store, using {{ shop.metafields.custom_fields.email_header_image | metafield_tag }} will output : gid://shopify/MediaImage/72410027163974
The current workaround is to use a text metafield to past the CDN URL of the image into, but this is not very user-friendly, and can be a problem when working with different file types.
Thanks for flagging this, and for the detailed write-up.
I’m thinking this may be expected behaviour on our end here, but I’m going to confirm things and see if I can pass this along as feature feedback at the very least.
Hey @Alex-OddBrew - thanks for waiting on my reply here - just following up on some threads
Just to clarify what I meant by expected behaviour there: it’s not that this is ideal, but email notification templates don’t currently resolve file_reference metafields the same way Online Store theme Liquid does.
In theme Liquid, that metafield can resolve into a typed media/image object, so filters like image_url, image_tag, or metafield_tag have the image data they need. In notification Liquid, the shop metafield is currently exposed more like its raw value, so a file reference ends up as the media GID rather than a usable image object/URL. Since image_url can’t build an image URL from just that GID string, it renders blank or only outputs the GID.
So for built-in transactional notification templates, the reliable workaround right now is still storing the CDN URL directly, for example in a text metafield. I definitely get that’s not super ideal, especially for file/image workflows, so I’m happy to pass this along as feedback on our end here.
Thank you for the clarification !
Indeed it would be nice to have the same behavior on the theme and the notifications at some point, but just having this difference explained in the docs would already be great !
Yeah, that’s fair feedback. The theme Liquid docs can make this look like file_reference metafields should resolve the same way everywhere, but notification templates use a different Liquid surface, and this limitation isn’t called out super clearly right now.
I’ll pass this along as docs/product feedback so we can look at making that distinction clearer. For now, storing the CDN URL directly is still the reliable workaround for built-in notification templates.
