File reference (image) Shop metafield not usable in email notifications

Online Store and Theme Development
1

Short description of issue

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 :

  • <img src=“{{ shop.metafields.custom_fields.email_header_image.value.src | image_url: width: 600 }}”
  • {{ shop.metafields.custom_fields.email_header_image | image_url: width: 1200 | image_tag }}
  • {{ shop.metafields.custom_fields.email_header_image | metafield_tag }}

Additional info

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 :

  • <img src=“{{ shop.metafields.custom_fields.email_header_image.value.src | image_url: width: 600 }}”
  • {{ shop.metafields.custom_fields.email_header_image | image_url: width: 1200 | image_tag }}
  • {{ shop.metafields.custom_fields.email_header_image | metafield_tag }}

And so on.

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.

What type of topic is this

Bug report

Upload screenshot(s) of issue

Screenshot 2026-04-17 184702.png
Screenshot 2026-04-17 184702.png622×346 6.05 KB

2

Hey @Alex-OddBrew -

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.

I’ll loop back when I have more info!

3

Hi @Alan_G,

Thank you for this !
Out of curiosity, why would this be expected behavior ?