Liquid context reference

This is the complete set of objects your theme can read. The platform builds this context and hands it to your Liquid - you never fetch data yourself. A machine-readable version is available at /context-schema.json (see the API reference).

Global objects

Available in every template and section.

Per-page extras

• Product page - product
• Collection page - collection (with products[] + facets), paginate, active_filters
• Search page - search, active_filters
• Content page - page

shop

Storefront-wide information.

settings

The merchant’s global theme settings, keyed by the ids you declare in config/settings_schema.json. Access as {{ settings.color_primary }}, {{ settings.logo }}, and so on. See Sections & settings.

Some well-known ids (color_bg, color_primary, color_surface, color_fg, color_border, color_accent, font_body_family, font_heading_family) also brand the merchant’s cart / account pages when your theme is live - use these exact ids to opt in for free.

product

Available on the product page, and nested inside collection.products[] and search.results[].

product.options[] and variants

Every product surfaces a structured options[] array. Use it for swatches and size pickers - never split variant.title on /.

Each option group:

Each option value:

Each variant:

Rendering option pickers

Branch on option.kind:

{% for option in product.options %}
  {% if option.kind == 'COLOR' %}
    {% for v in option.values %}
      <button class="swatch" style="--swatch: {{ v.swatch_hex | default: '#ccc' }};"
              data-option-value-id="{{ v.id }}" aria-label="{{ v.label }}"></button>
    {% endfor %}
  {% elsif option.kind == 'SIZE' %}
    {% for v in option.values %}
      <button class="chip" data-option-value-id="{{ v.id }}">{{ v.label }}</button>
    {% endfor %}
  {% endif %}
{% endfor %}

product.custom_fields[]

Merchant-defined typed metafields. Two access patterns:

{# iterate every attached field #}
{% for f in product.custom_fields %}
  <h3>{{ f.label }}</h3>
  {% if f.type == 'RICH_TEXT' %}{{ f.value_text }}
  {% elsif f.type == 'IMAGE' %}<img src="{{ f.value_image }}" alt="{{ f.label }}">
  {% elsif f.type == 'IMAGE_LIST' %}{% for img in f.value_images %}<img src="{{ img }}">{% endfor %}
  {% elsif f.type == 'NUMBER' %}{{ f.value_number }}
  {% else %}{{ f.value_text }}{% endif %}
{% endfor %}
 
{# look up a specific field by key #}
{% assign care = product.custom_fields_by_key.fabric_care %}
{% if care %}<div class="rte">{{ care.value_text }}</div>{% endif %}

Each field: { id, key, label, type, description, position, value, value_text, value_image, value_images, value_number, value_json }. type is one of TEXT | RICH_TEXT | IMAGE | IMAGE_LIST | VIDEO | URL | NUMBER | JSON_LIST.

collection

Available on collection pages, and every entry in the global collections list.

On the global collections list, each entry carries metadata only - .products is [] unless a section/block on the current page references that collection, or it is the page’s own collection. Use products_count for counts on collection-list tiles.

collection.facets

The canonical source for the filter sidebar. Read from this - do not compute facets client-side from products[].

facets: {
  sizes:      [{ label, hex, count }],   // hex always null for sizes
  colors:     [{ label, hex, count }],   // hex = override || canonical || null
  priceRange: { min, max },              // in RUPEES (not paise)
  categories: [{ label, count }]
}

paginate

{ current_page, pages, items, page_size, next, previous }

active_filters

Parsed active filter state - read from this rather than parsing the query string:

{ sortBy, sizes[], colors[], minPrice, maxPrice, inStockOnly, onSaleOnly,
  categoryHandles[], minRating, q }

minPrice / maxPrice are in RUPEES (render raw as ₹{{ active_filters.maxPrice }}).

Filter forms must submit as GET so the URL is shareable. Recognised query params: size, color, min_price, max_price, on_sale, in_stock, category, min_rating, sort_by, page.

cart

Always present. All prices in paise - render with the money filter.

Each line item: { id, product_id, variant_id, quantity, title, variant_title, sku, url, image, price, final_price, original_price, unit_price, line_price, final_line_price, original_line_price }.

{{ item.line_price | money }}

linklists

Navigation menus keyed by handle. Your theme must iterate linklists['main-menu'].links for the header and linklists['footer-menu'].links for the footer. Both handles are platform-guaranteed to resolve. See Navigation.

{% for link in linklists['main-menu'].links %}
  <a href="{{ link.url }}">{{ link.title }}</a>
  {% if link.links.size > 0 %}
    <ul class="dropdown">
      {% for child in link.links %}
        <li><a href="{{ child.url }}">{{ child.title }}</a></li>
      {% endfor %}
    </ul>
  {% endif %}
{% endfor %}

Each link: { title, url, type, resource, links[] }. Child links live on link.links (not link.children). type is one of COLLECTION | PRODUCT | PAGE | URL | CATALOG.

customer

null when signed out. When signed in:

{ id, name, first_name, email, phone, logged_in }

search

On the /search page:

{ terms, performed, results: product[], results_count }

performed is true when a non-empty query ran. Render a styled empty state when results_count == 0.

page

On a content page (templates/page.json):

{ title, handle, content }

content is rich-text body HTML. Render {{ page.content }}. The platform-seeded legal pages (About us, Privacy Policy, Terms of Service, Cookie Policy) rely on this.

request, template, routes

request  = { path, page_type, locale, host }
template = { name }                  // alias for request.page_type
routes   = { root, cart_url, search_url, collections_url, account_url, account_login_url }

Use routes.* for account-app links rather than hardcoding paths.