Why won't my file reference metafield show up in order confirmation emails?
Order confirmation emails run on a limited Liquid context that often can't resolve file reference metafields into a usable link, even though the same metafield works fine on your storefront.
What's going on
You've added a metafield of type file reference to a product or order so a PDF, size chart, warranty card, or custom proof can travel with the sale, and it works fine when you preview it in the admin or pull it into your theme. But when you try to reference that same metafield inside a notification email (order confirmation, shipping update, etc.) using standard dot notation, nothing shows up, or you get a raw internal ID instead of a clickable link.
This trips up merchants constantly because it looks like a bug: the metafield clearly has data, the namespace and key are correct, and the exact same reference resolves perfectly on the storefront or in the admin. The difference is where the Liquid is running. Shopify's notification templates (under Settings, Notifications) execute in a separate, more restricted Liquid environment than your theme. That environment exposes only a curated subset of fields on each object, and it has historically been inconsistent about resolving reference-type metafields (file reference, product reference, page reference, and similar) into their underlying object. You often end up with the internal identifier rather than a URL you can drop into a link.
Why it happens
Shopify's notification (email) templates use a separate Liquid rendering context from your storefront theme. It's intentionally minimal for performance and security reasons, and it exposes a smaller, fixed set of fields per object rather than the full data graph a theme template can walk.
Reference-type metafields (file reference, product reference, variant reference, page reference, metaobject reference) store a pointer to another resource rather than the final value. Resolving that pointer into something usable, like a file's public link, requires an extra lookup step. Theme Liquid and the storefront and admin APIs handle that lookup automatically; the notification Liquid engine has not consistently done the same, so the reference either renders as an empty string or as the raw unresolved ID.
5 ways to fix it
Add a plain URL metafield that mirrors the file, and use that in the email
Create a second metafield of type URL (not file reference) on the same resource, and populate it with the file's public link, either by hand or with a small Flow or script trigger that copies the URL whenever the file reference changes. Reference that URL metafield in your notification Liquid instead of the file reference one. Plain URL and text metafields render reliably in notification templates, so this sidesteps the resolution problem entirely and is the fix most merchants land on.
Check whether the metafield is actually in scope for that notification
Before assuming it's a bug, confirm the metafield is defined on the resource that notification actually receives (order, product, customer, line item, shop) and that its namespace and key match exactly. Notification templates only expose a limited, hand-picked subset of each object's data, and a metafield defined on the wrong resource, or with a typo in namespace.key, silently renders blank rather than throwing an error, which looks identical to the unsupported-type problem.
Try resolving the reference manually before giving up on it
For file reference metafields, the value stored under the hood is a pointer to the file object, not a ready-to-use link. Depending on your API and theme version, there are sometimes ways to dereference that pointer into a usable URL, but support for doing this inside notification Liquid specifically has been inconsistent. If you can't get it to resolve after a reasonable attempt, don't keep fighting the notification engine; fall back to the URL-metafield approach above.
Move the file link out of the transactional email and onto the order status or account page
Order status pages and customer account pages run on a fuller Liquid or app-extension environment than transactional email templates, with more consistent support for metafields and file references. If the file (spec sheet, warranty card, custom proof) doesn't strictly need to land in the inbox, linking it from the order status or account page sidesteps the email limitation completely, and it's often a better experience anyway since the file can be swapped after the email has already gone out.
If this is a recurring need, consider a dedicated post-purchase email step
Native Shopify notifications are meant for lightweight transactional content. If you're regularly attaching product manuals, licenses, or custom files to confirmation emails, a purpose-built post-purchase email or attachment app will handle file references and deliver the actual file more reliably than hand-editing notification Liquid every time a new file type comes up.
Bottom line
This is a Liquid-context limitation, not a broken metafield: Shopify's notification templates expose a trimmed-down set of objects and don't reliably resolve file reference metafields into a live link the way theme templates do. The most dependable native fix is to store a companion URL-type metafield and reference that in your email. If file delivery becomes a routine part of your post-purchase flow, a purpose-built app for that will save you from re-solving this every time you add a new file-based metafield.
Browse the rest of the problem library, run a free storefront scan to catch issues like this automatically, or email us and we'll work out a custom solution for it.