Shopify just expanded the power of file reference metafields. As of API version 2027-01, these metafields can now hold direct links to YouTube and Vimeo videos, turning a simple metadata field into a dynamic video embed solution. For both developers building custom themes and apps, and merchants looking to showcase product videos without extra apps, this change opens a streamlined path to richer content. In this post we’ll break down what’s new, who needs to pay attention, and exactly how to start using video file reference metafields in your store.
What the Update Introduces
Previously, file reference metafields only accepted images, PDFs, or generic files stored on Shopify’s CDN. The 2027-01 release adds explicit support for YouTube and Vimeo URLs, treating them as first‑class file references. When you query a metafield of type "file_reference" with a video URL, the API returns a structured object that includes the video platform, video ID, and a ready‑to‑embed thumbnail URL. This means you can retrieve a video’s metadata directly from the metafield without having to parse raw URLs or rely on third‑party embed services.
How It Impacts Developers
For developers, the change is twofold: schema definition and data handling. When defining a metafield through the Admin API, GraphQL, or REST, you now set "type": "file_reference" and can optionally add "validation": {"file_type": ["youtube", "vimeo"]}. The response payload includes a "reference" object with fields like "platform", "video_id", and "thumbnail_url". Existing code that assumed only image URLs will need a quick guard clause to detect the "platform" value and render the appropriate embed markup. The update also respects the same permission model – only apps or custom scripts with read/write metafield scopes can create or modify these values.
How It Impacts Merchants
From the merchant side, the new capability appears as an extra option in the metafield UI within the Shopify admin. When adding a file reference metafield, you can now paste a YouTube or Vimeo link and see a preview thumbnail instantly. This eliminates the need for separate video‑hosting apps or manually embedding iframe code on product pages. Merchants can associate a video with any resource – products, collections, pages, or even custom objects – and trust that the storefront theme will render it consistently.
Implementing Video File Reference Metafields
Below is a minimal GraphQL mutation that creates a video metafield for a product. Replace the placeholder IDs with your own values.
graphql
mutation CreateVideoMetafield($productId: ID!) {
metafieldsSet(input: {
ownerId: $productId,
metafields: [{
namespace: "media",
key: "demo_video",
type: "file_reference",
value: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
description: "YouTube demo video for the product"
}]
}) {
metafields {
id
namespace
key
type
reference {
... on VideoReference {
platform
videoId
thumbnailUrl
}
}
}
userErrors { field message }
}
}
In a Liquid theme you can then render the video using the returned reference fields:
liquid
{% assign video = product.metafields.media.demo_video.reference %}
{% if video.platform == "youtube" %}
<iframe width="560" height="315"
src="https://www.youtube.com/embed/{{ video.video_id }}"
title="YouTube video player" frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen></iframe>
{% elsif video.platform == "vimeo" %}
<iframe src="https://player.vimeo.com/video/{{ video.video_id }}"
width="640" height="360" frameborder="0"
allow="autoplay; fullscreen; picture-in-picture" allowfullscreen></iframe>
{% endif %}
Best Practices & Considerations
Next Steps & Migration Tips
If you already have image file reference metafields that you’d like to replace with videos, the migration is straightforward. Query existing metafields, extract any stored YouTube/Vimeo URLs, and re‑save them with the "file_reference" type – the platform will automatically treat them as video references. For stores that used third‑party video apps, consider deactivating those apps after confirming the new metafields render correctly, simplifying your tech stack and reducing monthly fees.
Conclusion & Call to Action
The 2027-01 API update turns file reference metafields into a powerful, native video embed tool for Shopify stores. By updating your metafield schemas, adjusting Liquid templates, and following the best‑practice checklist, you can deliver richer product storytelling without extra apps or custom JavaScript. Ready to add video to your product pages? Start by creating a test metafield with a YouTube link, preview it in the admin, and then roll out the change across your catalog. Need help integrating the new metafield type? Reach out to our Shopify development team or drop a comment below – we’re happy to guide you through the process.
