Supported resources expose storefront-visible metafields as namespace/key values. For example, product.metafields.details.material reads the material key in the details namespace. Only definitions marked storefront-visible are included. Check for missing namespaces and values before rendering them.
{% assign details = product.metafields.details %}
{% if details.material %}
<p>Material: {{ details.material }}</p>
{% endif %}Definition type |
Value in CTX |
|---|---|
string, url, date, datetime |
String |
integer, decimal |
Number for a valid stored numeric value |
boolean |
Boolean |
json |
Parsed JSON value |
list.string, list.url |
Array of strings |
single_select |
Localized display label when the choice is available |
list.single_select |
Array of choice labels |
file_reference |
File object with id, url, and alt_text when the file resolves |
list.file_reference |
Array of resolved file objects |
product_reference |
Product card on supported detail contexts; otherwise an identifier |
list.product_reference |
Product-card list on supported detail contexts; otherwise identifiers |
variant_reference, list.variant_reference |
Variant identifier or identifiers |
Translations and missing choices#
Translatable values use the shopper's language when a translation is available, and the store's base-language value when it is not. Select values resolve to their translated or source display labels. A value saved before its choice was removed keeps the stored value; update those metafields when you change the available choices.
References#
On supported detail contexts, product references resolve to product cards that are visible on the current storefront. An unavailable single reference is null; unavailable entries drop from a reference list. Lightweight card contexts retain reference identifiers instead of expanding another set of cards. Variant references currently remain identifiers. Do not assume every reference is a complete product or variant object.
A missing file, or a value that no longer matches its definition, may not resolve to the expected typed object. Keep metafield values consistent with their definitions, and render optional values only when they have the required shape. Use the dedicated product and cart price fields for purchasing, rather than treating a custom numeric metafield as a price.
See Shared data shapes for product cards and money objects, and Theme documentation for section settings and resource pickers.