Basic To Advanced Shopify Metafield Implementations To Nail Your Year-end Sales

Ellie Ho
Jun 7, 2024
3 min read

Metafields allow you to customize the functionality and appearance of your Shopify store by storing specialized data that isn't normally captured in the Shopify admin. It can be used to track internal data or to display specialized information on your online store in a variety of ways.

Therefore, this was one of the most discussed topics during Shopify Unite 2022. Shopify also published a workshop to guide users to create, render, and automate tasks with Metafields.

This article will go through the Metafield guides in the Shopify workshop. However, we’ll make a few changes here and there so it'll be more beginners' friendly. Trust us, even the advanced guides are not difficult to follow!

New to Shopify Metafields? Or you want to better understand:

  • What are Shopify Metafields?
  • What is the structure of Metafields?
  • What are the available types of Metafields?

Check out the full Shopify Metafields Guide.

How to create a metafield definition: Beginners’ and Experts' Guide

Basic: Head to the Shopify store admin

The easiest and most native way to add new Metafield definitions is from the Shopify admin. In this example, we’ll create a Products Metafield to add customers' image feedback of the product.

For full instructions, check out this Metafield guide. To make it brief, you'll need to go to Settings > Custom data > Choose Products.

create metafield in shopify admin

Click on Add definition to begin creating a new metafield definition with the following properties:

  • Name: Choose a value that lets you identify the definition easily in the future. In this example, we will use Special image.
  • Namespace and key: This is the internal identifier for this metafield definition. In this example, we will use custom.special_image.
  • Description: Optionally add any additional information here about the field.
  • Content Type: Choose File. This option allows you to select the metafield type for your definition. A type defines what kind of information a metadata definition can store. Metafield types have built-in validation and Liquid support.

Click on Save to store the new metafield definition. You can leave the options in the Validation section set to their default values.

Advanced: Use GraphiQL app

The free Shopify GraphiQL app allows you to interact with your store's Admin and Storefront APIs. It features an easy-to-use editor so you can create the payload of your API calls, as well as documentation and auto-completion with ease.

As it manipulates APIs, you can set metafield definitions on thousands of products programmatically. Such a huge time-saver! Moreover, Shopify GraphiQL can utilize much more advanced applications of Shopify Metafields such as creating a basic “recommended products” section to showcase similar or related products. However, the downside is you need to learn some basic programming syntax.

In this example, we'll show you how to create new metafield definitions and product data for product recommendations in Shopify GraphiQL.

Step 1: Install the Shopify GraphiQL app

To install the app click on this link and follow the instructions.

Step 2: Create a product recommendation metafield definition

We start by using the GraphiQL app to create a new metafield definition for storing one or more product recommendations. In this example, the GraphiQL app will make a GraphQL metafieldDefinitionCreate mutation call to create a new metafield definition.

To do so, start by launching the GraphiQL app. Make sure to have the API Schema toggle switched to Admin and choose the latest version from the API version dropdown menu (1).

create metafield using shopify graphiQL

Add the following payload to the top left window of the editor (2):

mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {

metafieldDefinitionCreate(definition: $definition) {

createdDefinition {




userErrors {







The $definition value is built by adding JSON into the Query variables part of the GraphiQL app. It's located at the bottom left of the screen and might be collapsed when you first load the page (3).


"definition": {

"name": "Recommendations",

"namespace": "custom",

"key": "recommendations",

"description": "Recommended products",

"type": "list.product_reference",

"ownerType": "PRODUCT"



After the mutation has been made, you can check the Settings > Metafields menu to see the new definition.

Assign the metafield to a product: 2 ways you can do it

Basic: Manually add values to each product

In this step, we'll add values for the metafields we just created. In the basic instruction to create Shopify Metafields in Shopify Admin, we have a metafield definition for “special image”. So, let’s add some images here.

When you open the product editor in the admin, you will find the metafield section at the bottom of the page. If not all metafields are visible, click on Show all.

Upload an image that you want to display additionally with the product. Click on Save to finalize your changes.

So simple, isn't it? But how about if you have several hundred or thousands of products? All this manual work will be extremely time-consuming.

Advanced: Manipulate GraphiQL app

Using the Shopify GraphiQL app, you can assign values for a metafield without visiting every single page. You still need to have the ID of the page (products, collections, etc) you want to add values to. An ID exporter app can help you with this. Or you can find the ID in the URL when hovering in the editor.

how to find product ID in Shopify admin

In this step, we will populate the product recommendation metafield for the product with ID: 6987538464955. The related items will have these IDs: 6987538858171, and 6987539153083.

The payload for this is as below (1):

mutation metafieldsSet($metafields: [MetafieldsSetInput!]!) {

metafieldsSet(metafields: $metafields) {

metafields {







userErrors {







In the query variables section, we will pass variables that are necessary for the mutation, such as the main product and the recommended products (2).

Replace the target product ID in the ownerId field with yours, then change the IDs in the value field with that of the recommended. Note that the type field is list.product_reference and a list of recommendations will be built using a comma-separated string of IDs.


"metafields": [


"key": "recommendations",

"namespace": "custom",

"ownerId": "gid://shopify/Product/6987538464955",

"type": "list.product_reference",

"value": "[\"gid://shopify/Product/6987538858171\", \"gid://shopify/Product/6987539153083\"]"



Running this mutation successfully will create a new metafield definition that you can see in both the API response in GraphiQL and in the admin Metafield menu (3).

assign values for shopify metafield using shopify graphiQL

Additionally, if you open the product in the Shopify Admin, you'll also see the new product recommendations metafield.

Show metafield data in the online store

Unfortunately, there currently isn’t a no-code way to display Shopify Metafields on your storefront. You'll need to access the code editor and use Liquid to get this done. Liquid is Shopify's templating language. Metafields are accessible as Liquid objects in Shopify themes, by wrapping the full definition in curly brackets. Below is the Liquid template to connect metafields with the Shopify storefront.

{{ product.metafields.my_fields.instructions.value }}

For example, this syntax {{%- if product.metafields.custom.special_image != blank -%}} will refer to the “special image" we’ve created (!= mean “is not").

In this section, you will add some Liquid code and HTML to your theme. This will allow us to display the metafields we've set up using Shopify Admin and Shopify GraphiQL app.

To access the code editor, navigate to the Online Store under the Sales channel section on the left-hand side. Choose Edit code in the Action dropdown menu in the main content area.

Note: To prevent any problems with your live site that can affect your sales, we highly recommend you do these steps on a duplicated theme or on a test store.

The code below was written for Dawn, the default development store theme. If you are using a different theme, you will need to make the appropriate changes.

Open the Sections/main-product.liquid file and find the snippet that displays the product description on the product detail page.

{%- if product.description != blank -%}

<div class="product__description rte">

{{ product.description }}


{%- endif -%}

  • Paste the following snippet directly underneath to display the image metafield that we've set up in the Shopify Admin:

{%- if product.metafields.custom.special_image != blank -%}


<img src="{{ product.metafields.custom.special_image | img_url: '250x' }}" />


{%- endif -%}

This snippet will render the additional product image. By using an if statement, the additional image will only show if the metafield is set for that product. Also, note the use of the img_url filter, in our case, they will determine the dimensions of the image.

  • The below code snippet is to display recommended products created by using GraphiQL app.

{%- if product.metafields.custom.recommendations != blank -%}


<strong>Recommended products</strong>


{% for product in product.metafields.custom.recommendations.value %}

<li><a href="{{ product.url }}">{{ product.title }}</li>

{% endfor %}



{%- endif -%}

The code will check if the metafield isn't empty and then iterate over the list of recommended products.

Now, when you navigate to the product detail page of your demo store, you should see the new metafields rendered.

Let's expand on the concept

We've shown just some examples of how to use metafields with Shopify Admin and the Shopify GraphiQL app to modify how your store looks and feels. Some other applications to alter metafields for your needs are to showcase:

  • part numbers
  • color swatches
  • launch dates
  • related products
  • blog post summaries
  • files for download
  • lists of ingredients

Let's expand your ideas on that and share with us how you are utilizing this Shopify weapon on our social channels including Facebook, Twitter, Linkedin, and Youtube.

Ellie Ho
Content Marketing Specialist
June 29, 2024
7 min read