> For the complete documentation index, see [llms.txt](https://analog.groupthought.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://analog.groupthought.com/reference/metafields.md). # 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. {% hint style="info" %} 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. {% endhint %} ## The contract | Feature | Theme setting | Suggested key | Type / shape | What it drives | | --------------------------------------------------------------------- | --------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | [Siblings](/features/variants.md) | `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 | | [Sibling swatch image](/features/variants.md) | `metafield_sibling_image` | `theme.sibling_image` | **Product** → File (image) | Overrides the derived swatch image when **Customize swatch and label** is on | | [Sibling color name](/features/variants.md) | `metafield_sibling_label` | `theme.sibling_label` | **Product** → single-line text | Overrides the derived swatch label when **Customize swatch and label** is on | | [Option media](/features/variants.md) | `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 | | [Paired product upsells](/features/product.md#paired-product-upsells) | `metafield_upsell_list` | `theme.upsell_list` | **Product** → list of products | Keeps a product's promoted upsells available across product and cart blocks | | [Free shipping limit](/features/cart.md) | `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 | | [Custom badges](/features/merchandising.md) | `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 | | [Preorder](/features/cart.md) | `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 | | [Line item property](/features/cart.md) | `metafield_line_item_property` | `theme.line_item_property` | **Product** → single-line text | Adds extra detail to cart lines, such as a sibling color name | | [Star rating](/features/merchandising.md) | *(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](/features/variants.md). `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](/features/product.md#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](/features/cart.md#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. {% hint style="warning" %} Star ratings have no key setting. Analog always reads `reviews.rating` and `reviews.rating_count`. A reviews app must write the values. Enable the display under Theme settings → Cards → Show star rating. {% endhint %} ## 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 * [Siblings & grouped variants](/features/variants.md): siblings and option media * [Merchandising](/features/merchandising.md): badges and star ratings * [Cart](/features/cart.md): preorder, upsell, and line item properties