Skip to main content
All CollectionsCustomer FieldsTechnical Stuff
Metafield data in Liquid
Metafield data in Liquid

Use Metafields to access custom data on the storefront, or Shopify's email notifications

Kyle Weiskopf avatar
Written by Kyle Weiskopf
Updated over a month ago

Where is the data for custom fields stored?

Customer Fields stores custom data in two places; the app's database and Shopify’s customer metafields.

When a customer record is created or updated by Customer Fields, and the data being saved contains values for custom data columns, then our app will store this additional information on the Customer resource/object in Shopify using metafields. A customer's metafield data can be accessed in several ways:

  1. Directly in the Shopify admin using metafield definitions

  2. Via Shopify's Admin APIs

  3. On the storefront or in Shopify's email notifications using Liquid

The rest of this article focuses on #3 - using Liquid to access metafield data.

Note: Metafields are only used for custom fields and data columns

Please keep in mind that the data for standard fields and data columns (e.g. first_name, email, phone, etc) will be saved to the normal fields/properties for customers within Shopify -- not metafields. We suggest using Shopify's documentation if you need help displaying standard customer data in Liquid:

Liquid: Customer object

Metafield strategy

Prior to April 2022, the app stored all custom data in a single metafield using a JSON string. Shopify recently released metafield definitions, so we’ve introduced a new way to store metafield data that is compatible with Shopify's new metafield types and definitions. With this new strategy, Customer Fields will save all custom data column values into their own separate metafields.

You can control the app's metafield strategy within the app admin by going to Settings > Metafields. There are two options to choose from:

Liquid output

With the power of Liquid, you can use customer metafields to access the custom data collected by Customer Fields. The most common way to use metafields in Liquid is when editing the code for a store's theme or email notification templates.

To access custom data on the storefront or in email notifications, you'll need to use one of the syntaxes below. Notice there are multiple different syntaxes, so depending on which metafield strategy you're using and where you want to access metafield data the syntax will vary:

Shopify admin-compatible

Theme (storefront) syntax:

customer.metafields.NAMESPACE.DATA_COLUMN_KEY.value

Email template syntax:

customer.metafields.NAMESPACE.DATA_COLUMN_KEY

By default, the app will use customer_fields as the namespace for all custom fields, however this default value or individual fields can be changed to use a different namespace.

Bundled JSON metafield

General syntax:

customer.metafields.customer_fields.data["DATA_COLUMN_KEY"]

❗ Note for all syntaxes: Make sure to replace NAMESPACE and DATA_COLUMN_KEY with the actual values you wish to use. The syntaxes above are just for reference purposes.

Liquid-friendly data types

Since each data column in Customer Fields has its own specific data type, you can apply type-specific Liquid filters to format the output, or even scope out certain attributes in an object of data.

Specific examples

Below you'll find several different examples of how to display metafield data for a logged-in customer on the storefront. Please note that each example uses the syntax for the app's new metafield strategy and the default app--960624--helium namespace.

1) Display value for a custom single_line_text data column with the key of favorite_color: 

Favorite color: {{ customer.metafields.app--960624--helium.favorite_color.value }}

<!-- Outputs:
Favorite color: Orange
-->

2) Display value for a custom date data column using a Liquid date filter to control the format: 

Your Birthday: {{ customer.metafields.app--960624--helium.birthday.value | date: "%b %d, %Y" }}

<!-- Outputs:
Your Birthday: February 6, 1945
-->

3) Display value for a custom list data column using a Liquid filter to convert the array into a comma-separated string:

Your Hobbies: {{ customer.metafields.app--960624--helium.hobbies.value | join: ", " }}

<!-- Outputs:
Your Hobbies: Cycling, Hiking, Video Games
-->

4) Display value for a custom file data column using the URL attribute to embed an image: 

Profile pic: <img src="{{ customer.metafields.app--960624--helium.profile_pic.value.url }}" style="max-width: 150px;">

<!-- Outputs:
Profile pic: <image> (150px max width)
-->

5) Display values for a custom file data column using the URL and name attributes for a hyperlink:

PDF agreement: <a href="{{ customer.metafields.app--960624--helium.contract.value.url }}" target="_blank">{{ customer.metafields.app--960624--helium.contract.value.name }}</a>

<!-- Outputs:
PDF agreement: <filename> (hyperlink that opens file URL in a new tab)
-->

6) Display values for a custom group_list data column using a for-loop to output certain data attributes in the array of objects:

{% for pet in customer.metafields.app--960624--helium.pets.value %}
<p>Pet name: {{ pet.name }}</p>
<p>Pet weight: {{ pet.weight }}</p>
<br>
{% endfor %}

<!-- Outputs:
Pet name: Franklin
Pet weight: 30 lbs

Pet name: Winston
Pet weight: 2 lbs
--->

7) (Advanced) Display values for a custom group_list column using a variable, multiple filters, iteration, and some control flow logic:

{% assign pets = customer.metafields.app--960624--helium.pets.value %}
  <h4>Your Pets ({{ pets | size }} total)</h4>
{% for pet in pets %}
  <ul>
    <li>{{ pet.name | capitalize }} ({{ pet.type | downcase }}), {{ pet.energy_level | downcase }}></li>
    {% if pet.birthday != nil %}<li> Born: {{ pet.birthday | date: "%b %d, %Y" }}</li>{% endif %}
   <br>
  </ul>
{% endfor %}

<!-- Outputs:
Your Pets (2 total)

Franklin (dog), lazy
Born: October 10th, 2015

Winston (hamster), active
--->

Looking for more technical details? 🤓

Learn more about the app's metafields using our Developer Documentation.

Did this answer your question?