For the complete documentation index, see llms.txt. This page is also available as Markdown.

Metafields reference

Every metafield and metaobject Analog reads, the theme setting that names each key, and the exact data shape expected.

Siblings, option media, upsells, badges, preorder, ratings, and the free shipping limit read from metafields or metaobjects. Except for ratings, you set each key under Theme settings → Metafields. The fields are empty by default. Enter a namespace.key to enable the feature.

Create the metafield and metaobject definitions in Shopify admin. This page lists the key setting, expected type, and use inside Analog.

The placeholder in each setting (theme.siblings, theme.badge, …) is a suggested key. It isn't the current value. Leave the setting empty to keep the feature off. Analog splits the value at the first . into namespace and key.

The contract

Feature
Theme setting
Suggested key
Type / shape
What it drives

metafield_siblings

theme.siblings

Product → metaobject reference (a "Sibling" entry holding a product list)

Links separate products as siblings and shows them as swatches on cards and product pages

Sibling product list

metafield_siblings_inner_name

products (default)

Metaobject field name → list of products

Names the field inside the Sibling metaobject that contains the products

metafield_sibling_image

theme.sibling_image

Product → File (image)

Overrides the derived swatch image when Customize swatch and label is on

metafield_sibling_label

theme.sibling_label

Product → single-line text

Overrides the derived swatch label when Customize swatch and label is on

metafield_product_option_media

theme.product_option_media

Product → list of metaobject references ("Option media" entries)

Changes the product/card gallery when a matching option is selected

Option media swatch field

metafield_product_option_media_swatch

option (default)

Metaobject field name → Color metaobject reference

Names the field that maps the entry to an option value

Option media media field

metafield_product_option_media_list

media (default)

Metaobject field name → list of files (images + video)

Names the field that contains the entry's media

metafield_upsell_list

theme.upsell_list

Product → list of products

Keeps a product's promoted upsells available across product and cart blocks

metafield_free_shipping_limit

theme.free_shipping_limit

Market → integer

Sets a market threshold. Each cart section decides whether the value is already in the market's currency or needs conversion

metafield_badge

theme.badge

Product or variant → single-line text, or a list of single-line text

Renders custom badges on product cards. Use the variant for color-specific badges

metafield_preorder

theme.preorder

Product → boolean (true/false)

Changes the add-to-cart label to "Pre-order" and adds "Sale type: Pre-order" to the cart line

metafield_line_item_property

theme.line_item_property

Product → single-line text

Adds extra detail to cart lines, such as a sibling color name

(not a theme setting)

reviews.rating + reviews.rating_count

Product → rating + integer

Renders the card/product page rating. A reviews app populates the values

Common setup mistakes

Use either siblings or option media for one set of colorways. Siblings use a separate product, URL, and inventory for each color. Option media keeps one product and changes the gallery by option. See Siblings & grouped variants.

metafield_siblings_inner_name, metafield_product_option_media_swatch, and metafield_product_option_media_list are metaobject field names. They are not namespace.key metafield keys. Their defaults are products, option, and media.

Set metafield_badge on a variant when its badge should differ from the product badge. Analog checks the variant value first.

Use metafield_upsell_list to connect a product metafield with the List of products type. This is separate from connecting an Upsell block's "Products" setting to a dynamic source. A dynamic source controls that block. The shared key makes a product's paired upsells available to product and cart blocks.

Once the key is set, product blocks show "Use paired upsells" and Cart upsell blocks show "Prioritize paired upsells". On a product page, "Products" takes priority. In the cart, paired upsells appear before "Products". See Paired product upsells.

Use metafield_free_shipping_limit to connect a market metafield. Create the definition under Markets in Shopify admin, then add a value to each market that needs its own threshold.

Leave the key empty to use the cart section's "Minimum spend for free shipping" with automatic currency conversion. Once the key is set, each cart section shows "Convert metafield limit". Leave it off when the market value is already in the market's currency. Turn it on when the value uses the store's currency and should follow the shopper's currency selection.

The checkbox controls only the metafield value. When the key or market value is empty, Analog uses "Minimum spend for free shipping" and converts it from the store currency. See Currencies and markets.

"Store default" in the theme editor cannot supply a market metafield value. Select a market to preview theme.free_shipping_limit. The live storefront always has a market context.

Card content slots

Card title and price slots render other metafield content. Enable Set title slots or Set price slots, then set a metafield for each position above, beside, or below the value.

Slot metafield type
Rendering

Multi-line text

Output unescaped and unstyled. It is treated as your own HTML

Single-line text

Styled to match the surrounding card text

Rich text

Basic styling (heading, bold, italic) preserved

Use these for fit notes, brand names, sibling colors, or extra sale text without editing a template.

See also

Last updated

Was this helpful?