Reference fields

A reference type custom field is a specialized version of a 'Selection' type which will list all available objects of its type:

The values shown specifically for product and variant selections can be customized to show additional information, making it easier to search and filter for the correct items.

You can find the available options in your settings found in the admin side menu

Once a value is selected, the metafield will contain the referenced Shopify object's handle as its value (see special cases for file, resource and variant reference fields below). You can use this handle as a reference to a Shopify object via a Liquid global object depending on the type.

{{ blogs[product.metafields.accentuate.related_blog].title }}  
{{ articles[product.metafields.accentuate.related_article].title }}  
{{ pages[product.metafields.accentuate.related_page].title }}  
{{ collections[product.metafields.accentuate.related_collection].title }}  
{{ all_products[product.metafields.accentuate.related_product].title }}  
{{ linklists[product.metafields.accentuate.related_linklist].links }}

The above examples use Shopify Global Objects

Shopify global objects only return values for published products, collections, pages etc. Be sure to check if the returned object is valid in case the reference suddenly points to a deleted or archived object.

Shopify imposes a restriction on how many calls to "all_products" you can make from a single Liquid page. This is currently set to 20 unique handles per page

Using reference types, we can also get the metafields from the referenced objects using the handle. This is just as easy as getting the url or title as shown above.

{{ all_products[product.metafields.accentuate.related_product].metafields.accentuate.isbn }}

Multiple selections

As is the case for the basic type 'Selection', if you have opted for multiple selections for your reference type, each object's handle is listed with the "pipe" symbol ("|") as a separator token. You can use Liquid's 'split' filter on the metafield to separate the handles - like this:

{% assign selected_handles = product.metafields.accentuate.selection | split: '|' %}
{% for selected_handle in selected_handles %}
  <p><a href="{{ all_products[selected_handle].url }}">{{ all_products[selected_handle].title }}</a></p>
{% endfor %}

Variant reference fields

In Shopify, individual product variants don't have handles, so we need to rely on the product's handle combined with the id of the referenced variant. Therefore variant references are stored as product_handle:variant_id for easy access to both the product object and the underlying variant, like this:

{% assign product_handle = product.metafields.accentuate.referenced_variant | split: ':' | first %}
{% assign variant_id = product.metafields.accentuate.referenced_variant | split: ':' | last | plus: 0 %}

{% assign referenced_product = all_products[product_handle] %}
{% assign referenced_variant = referenced_product.variants | where: "id", variant_id | first %}

<p>The referenced variant is {{ referenced_product.title }} {{ referenced_variant.title }}</p>

Note the use of the Liquid filter "plus: 0" which converts a string to a number for use in the "where" filter.

Variant references cannot successfully be transferred to other stores due to the use of internal Shopify ids, which will vary across stores. Shopify does not offer a way to uniquely identify a specific product variant across store boundaries

File reference fields

Using a File reference field, you can reference a file or an image uploaded to Shopify (under Settings > Files) A file reference is stored as the filename, so you can get a fully qualified URL pointing the the file within Shopify's CDN using the Liquid filters file_url or file_img_url:

{% assign url = product.metafields.accentuate.referenced_file | file_url %}
<a href="{{ url }}">Click to download</a>

Also, the filename (of an image) can be used as a lookup value to the images global object in Liquid to get an image object of the file:

{{ assign image = images[product.metafields.accentuate.referenced_file] }}

Resource reference fields

Using a Resource reference field, you can reference any of the following Shopify objects: collections, products, pages, blog, or articles. A resource reference is stored as a partial url to the selected resource - like /products/example or /pages/contact, so you may redirect your visitor to the relevant page using links, buttons etc.:

{% assign url = product.metafields.accentuate.referenced_resource %}
<a href="{{ url }}">Please see here</a>

Media reference fields

Media references don't contain references to Shopify objects such as products and collections. Instead they contain internal references to ACF Media v2 type field values defined under either the "shop" or "globals" scope. Defining a media reference field allows you to reference a globally defined media from any scope like a specific product or collection. If, for example, you have a collection of vendor logos, icons or author avatars and would like to associate these with specific products or articles, you can define a Media v2 field under the "shop" or "globals" scope and use a media reference field to point to any of the uploaded medias, allowing for a single point of maintenance of the media itself. The media reference field itself will contain the referenced media's handle and you can do a lookup in Liquid like this:

{% assign referenced_media = shop.metafields.globals.vendor_logos | where: "handle", product.metafields.accentuate.vendor_logo_ref | first %}
<img src="{{ referenced_media.src }}" alt="{{ referenced_media.alt }}"/>

Or, if you have multiple media references selected:

{% assign selected_handles = product.metafields.accentuate.vendor_logo_ref | split: '|' %}
{% for selected_handle in selected_handles %}
  {% assign referenced_media = shop.metafields.globals.vendor_logos | where: "handle", selected_handle | first %}
  <img src="{{ referenced_media.src }}" alt="{{ referenced_media.alt }}"/>
{% endfor %}

Note the use of the Liquid filter "first" to pull the first element from the resulting array.

When updating a media being referenced by one or more media reference fields, you must ensure that the references stay valid by doing a "replace" operation rather than deleting and reloading the media (which will break the reference). This is available as an option button when hovering over the media:

When updating a media being referenced by one or more media reference fields, you must ensure that the references stay valid by doing a "replace" operation rather than deleting and reloading the media (which will break the reference). This is available as an option button when hovering over the media: