Use Liquid theme variables

Fluid supplies global variables and template-scoped variables when it renders Liquid. Global variables describe the storefront, request, localization, attribution, and shared resources. Template variables describe the resource or experience being rendered. Use this reference to choose the correct scope before you build a section.

Understand variable scope

Global variables are available to rendered storefront templates. Template variables are available only in their matching context. For example, product is available in a product template, while post is available in a post template. An unavailable value renders blank. Guard optional values and arrays before you use them:

{% if product and product.images.size > 0 %}
  <img
    src="{{ product.images.first.src }}"
    alt="{{ product.title | escape }}"
  >
{% endif %}

Use default for presentation fallbacks:

<h1>{{ product.title | default: 'Featured product' }}</h1>

Do not use a fallback to hide a misspelled field. Confirm the variable’s context and name first.

A template marked as static content receives a reduced global set. It keeps settings, your own template variables, routes, username, share_guid, and company.id, along with its template variables, navbar, footer, and sections. It loses request, params, localization, country, affiliate, sharing_id, external_id, affiliate_guid, the policy paths, the rest of company, and every on-demand resource collection. Test anything that reads those values in a rendered storefront context.

Global variables

The following top-level values are shared across rendered storefront templates. Some values can still be blank when the current visitor or company does not provide the underlying data.

Variable	Useful fields
`company`	`id`, `name`, `logo_url`, `subdomain`, `company_color`, `base_url`, `home_page_url`, `shop_page_url`, `join_page_url`, `checkout_url`, `portal_url`, `points_label`, and the social URLs `facebook_url`, `twitter_url`, `instagram_url`, `pinterest_url`, `youtube_url`
`request`	`path`, `host`, `full_url`, `page_type`, `query_parameters`
`params`	Request parameters for the current render
`localization`	`country`, `language`, `available_countries`, `available_languages`, `market`
`country`	The active country value
`affiliate`	`name`, `email`, `avatar`, `initials`, `my_site_url`, `logged_in_rep_for_store`, `web_rep_store_enabled`, `client_hydration`, `sign_in_url`, `sign_out_url`
`username`	The attributable storefront handle or its hydration sentinel
`sharing_id`	The affiliate sharing identifier
`external_id`	The affiliate’s configured external identifier
`share_guid`	The current share attribution value
`affiliate_guid`	The affiliate handle used by attributable links
`routes`	`root_url`, `cart_url`, `collections_url`
`privacy_policy_path`	Storefront privacy-policy path
`terms_conditions_path`	Storefront terms-and-conditions path
`library_navigation`	Playlist navigation state — see Playlist navigation
`content_for_header`	Markup Fluid injects into `<head>`. Render it once in your layout
`products`	On-demand product collection
`collections`	On-demand collection collection
`categories`	On-demand category collection
`enrollment_packs`	On-demand enrollment-pack collection
`posts`	On-demand post collection
`most_popular_posts`	On-demand popular-post collection
`settings`	Values from the theme’s root settings

navbar, footer, and sections are also assembled for the current template. Use their settings within the corresponding theme structure.

On-demand resource collections are not populated for static content renders. Test a resource loop in a rendered storefront context.

Company points labels

Use company.points_label.singular and company.points_label.plural instead of hard-coding a rewards label. Variants expose the same pair, as do product entries read from a resource collection. A product template’s own product value exposes product.points but not product.points_label, so read the label from company.

{% if product.points == 1 %}
  Earn 1 {{ company.points_label.singular }}.
{% else %}
  Earn {{ product.points }} {{ company.points_label.plural }}.
{% endif %}

Select the singular or plural form yourself. The value does not choose a form based on the number.

Affiliate hydration

Cached storefront HTML can contain sentinel values that the FairShare client replaces after it resolves attribution. Do not treat affiliate.name as a reliable server-rendered sign-in check. Use affiliate.logged_in_rep_for_store for the sign-in state. See affiliate hydration before you branch on affiliate fields or build attributable URLs.

Localization

localization.country is the selected country object. localization.language is the selected language object. Country entries include iso_code, iso, name, selected, unit_system, and a currency object with iso_code, name, symbol, and decimal_places. Language entries include iso_code, iso, name, endonym_name, locale, and selected.

<html lang="{{ localization.language.iso_code | default: 'en' }}">

Two values are reserved and always empty: localization.market, and available_languages on an individual country entry. Read localization.available_languages for the storefront’s language list. library_navigation is present only while a playlist item is being viewed. It carries library_index, total_count, title, library_path, previous_url, next_url, active_product_ids, and any_shared_products.

{% if library_navigation and library_navigation.next_url %}
  <a href="{{ library_navigation.next_url }}">Next</a>
{% endif %}

navbar carries base_url, logo_url, cart_url, shop_page_url, seller_name, current_selected_locale, current_country_iso, current_country_name, current_language_name, language_options, and countries. Inside a navbar template, these fields are also available directly. See navbar locale selector for the Liquid markup and JavaScript update flow. footer carries base_url and logo_url.

Product template

Use product for the current product.

Group	Fields
Identity	`id`, `sku`, `title`, `url`, `active`, `tags`
Content	`short_description`, `description`, `feature_text`, `metadata`, `metafields`, `metafields_collection`, `category`, `collections`
Pricing	`price`, `unit_price`, `subscription_price`, `unit_subscription_price`, `saved_on_subscription`, `saved_percentage_on_subscription`, `points`, `price_inclusive_of_tax`, `price_inclusive_tax_name`
Availability	`available_for_country`, `out_of_stock`, `buyable_quantity`
Media	`images`, `media`, `featured_media`, `ratings`, `reviews`
Options	`available_values`, `options_available`, `options_with_values`, `variants`, `selected_or_first_available_variant`, `has_only_default_variant`
Subscriptions	`allow_subscription`, `subscription_only`, `subscription_plans`, `selected_subscription_plan_id`
Recommendations	`recommendations`
Bundles	`bundle`, `bundle_config`, `product_bundles`, `product_bundle_groups`, `track_inventory_on_bundle_items`, `bundle_in_stock`, `bundle_available_quantity`

category and collections are trimmed summaries with id, title, and handle. Images expose id, src, url, position, media_type, alt, width, height, aspect_ratio, and preview_image. media is the same list as images, and featured_media is its first entry. Bundle groups include their selection constraints, pricing configuration, images, and items. product.vendor resolves but is always blank in a product template. Read vendor and type from a product entry in a resource collection instead.

<article>
  <h1>{{ product.title }}</h1>
  <p>{{ product.price }}</p>

  {% for image in product.images %}
    <img src="{{ image.src }}" alt="{{ product.title | escape }}">
  {% endfor %}
</article>

A product template also exposes a sibling recommendations value with products, products_count, and performed.

Variants and per-country pricing

Each entry in product.variants carries:

Group	Fields
Identity	`id`, `sku`, `title`, `display_name`, `is_master`, `metafields`
Availability	`active`, `buyable`, `available`, `available_for_country`
Options	`option_values` with `id`, `presentation`, `option_id`, `option_name`, `selected`
Media	`images`, `image`, `image_url`
Points	`points`, `points_label`
Pricing	`variant_countries`

variant_countries is the variant’s per-country price table. It lists every active row for the variant, not only the visitor’s country, so filter it by country_iso when you want one market:

Field	Description
`id`	Row identifier
`country_iso`	Country ISO code
`country_name`	Country name
`currency_code`	Currency for this row
`price`	Numeric price
`display_price`	Formatted price
`wholesale`	Numeric wholesale price
`display_wholesale`	Formatted wholesale price
`compare_price`	Numeric compare-at price
`display_compare_price`	Formatted compare-at price
`subscription_price`	Numeric subscription price
`display_subscription_price`	Formatted subscription price
`cv`	Commissionable volume
`qv`	Qualifying volume
`points`	Reward points for this country

{% assign variant = product.variants.first %}

{% for row in variant.variant_countries %}
  {% if row.country_iso == localization.country.iso_code %}
    <p>{{ row.display_price }}</p>
  {% endif %}
{% endfor %}

selected_or_first_available_variant is a lighter summary with available, id, sku, price, points, images, and metafields. It carries no variant_countries, so read the price table from product.variants.

Legacy top-level product values

A product template still copies part of the product onto the top level for themes built before product existed. These include title, description, short_description, feature_text, price, unit_price, subscription_price, images, available_values, ratings, reviews, thumbnail_image, limited_stock, selected_variant_id, shop_path, and all_products. Read product.* in new themes. thumbnail_image and limited_stock exist only at the top level and have no product equivalent.

Products read from a resource collection

Product entries in products, collection.products, category.products, and product.recommendations use the same field names as product, plus these extras: handle, content, available, image, image_url, featured_image, compare_at_price, price_min, price_max, price_varies, points_label, first_available_variant, type, selected_variant_id, mutually_exclusive_groups, and is_enrollment. A collection entry also returns the real vendor value rather than the blank one a product template exposes, and its selected_or_first_available_variant adds url, title, and image_url. Its variants carry the same fields, variant_countries included. Four product-template values are not available on a collection entry: price_inclusive_of_tax, price_inclusive_tax_name, metafields_collection, and recommendations.

{% for item in products %}
  <a href="{{ item.url }}">
    <img src="{{ item.featured_image.src }}" alt="{{ item.title | escape }}">
    <span>{{ item.title }}</span>
    <span>{% if item.price_varies %}From {{ item.price_min }}{% else %}{{ item.price }}{% endif %}</span>
  </a>
{% endfor %}

Shop template

Use these values in shop_page templates:

Variable	Contents
`collection`	`products_count`, `filters`, `sort_options`, and `products` for the current result set
`products`	Compact product summaries — `title`, `description`, `price`, `image`, `url`
`options`	Product-option summaries — `title` and `values` with `id`, `presentation`, `selected`
`categories`	Category choices — `id`, `title`, `count`, `selected`
`price_ranges`	Price choices — `lower_range`, `upper_range`, `lower_range_display`, `upper_range_display`, `selected`
`pagination`	`total_count`, `values`, `selected`, `current_page`, `per_page`
`url`	Attributable shop URL
`search_query`	Active search text
`sorted_by`	Active sort value

collection.sort_options is a fixed list of price sorts, price_desc and price_asc. Each collection.filters entry carries label, type, operator, param_name, presentation, values, active_values, and inactive_values.

Filter URLs are not composable. A value’s url_to_add is a query string containing only that one filter, so applying it discards every other active filter along with the current sort and page. A value’s url_to_remove is always empty. Build your own query strings from param_name and value whenever your theme supports more than one active filter.

The shop template’s products shadows the global product collection with lighter summaries. Read collection.products when you need full product fields on this page.

Collection template

Use collection for the current collection.

Field	Description
`id`	Collection identifier
`handle`	Collection handle
`title`	Collection title
`description`	Collection description
`position`	Collection position
`image`	Collection image
`featured_image`	Alias of `image`
`url`	Attributable collection URL
`products`	Products assigned to the collection
`products_count`	Number of products on the current page of results
`all_products_count`	Number of products in the whole collection

<section>
  <h1>{{ collection.title }}</h1>
  {% for item in collection.products %}
    <a href="{{ item.url }}">{{ item.title }}</a>
  {% endfor %}
</section>

Category template

Use category for the current category.

Field	Description
`id`	Category identifier
`handle`	Category handle
`title`	Category title
`description`	Category description
`position`	Category position
`image`	Category image
`products`	Products assigned to the category

A category value carries no url field. Build category links from the handle:

<a href="/{{ username }}/categories/{{ category.handle }}">{{ category.title }}</a>

Home template

Use these values in home_page templates:

Variable	Description
`base_url`	Storefront base URL
`logo_url`	Company logo or the default logo
`shop_url`	Attributable shop URL
`all_products`	On-demand product collection retained for home-template compatibility

Prefer the global products collection for new product loops.

Join template

Use these values in join_page templates:

Variable	Description
`url`	Attributable join URL
`collection.enrollment_packs`	Enrollment packs available in the join experience
`collection.enrollment_packs_count`	Number of enrollment packs in the rendered result set
`collection.all_enrollment_packs_count`	Number of matching enrollment packs
`pagination`	`total_count`, `values`, `selected`, `current_page`, `per_page`
`search_query`	Active search text
`sorted_by`	Active sort value

Each entry in collection.enrollment_packs uses the enrollment-pack shape described below.

Medium template

Medium templates expose the medium fields at the top level.

Group	Fields
Identity	`id`, `title`, `kind`, `description`, `poster`
Media	`embed_url`, `video_url`, `pdf_url`, `image_url`, `powerpoint_url`
Actions	`cta_url`, `cta_button_text`, `shop_path`, `learn_more_path`
Comments	`display_comments`, `comment_visibility`, `comment_submit_url`, `contact`, `comments`
Behavior	`display_shop`, `lead_captureable`, `visitable_on_click`, `video_shopping_enabled`, `video_status_url`
Sharing	`social_media`

contact carries id, full_name, email, and phone. Each comment carries id, name, initials, created_at, and body. Check kind before selecting a media-specific URL:

{% case kind %}
  {% when 'video' %}
    <video controls poster="{{ poster }}" src="{{ video_url }}"></video>
  {% when 'image' %}
    <img src="{{ image_url }}" alt="{{ title | escape }}">
{% endcase %}

Enrollment-pack template

An enrollment-pack template exposes its fields twice: at the top level, and under enrollment_pack. Read enrollment_pack.* so your markup also works when it renders a pack from another template.

Group	Fields
Identity	`id`, `title`, `url`
Content	`description`, `images_array`
Pricing	`price`, `enrollment_fee`, `enrollment_fee_in_currency`
Availability	`available_for_country`
Products	`membership_products`, `subscription_products`
Timing	`membership_after_one_month`, `first_payment_date`
Agreements	`agreements`

Both product lists carry title, price, cv, options_with_values, variant_id, product_bundles, product_bundle_groups, bundle_config, and mutually_exclusive_groups. The two lists name their image differently: a membership product uses image_url, and a subscription product uses image and adds learn_more_path. Agreement entries carry id, title, description, and required. Enrollment packs read from the global enrollment_packs collection answer images as well as images_array, and their product entries carry a larger set that adds id, sku, skus, first_variant_id, variant_countries, selected_variant_type_sku, image, and learn_more_path.

Library template

Library templates expose:

Variable	Description
`id`	Library identifier
`title`	Library title
`library_items`	Product, enrollment-pack, and medium cards
`active_product_ids`	Active product variant identifiers for the current library context
`social_media`	Company sharing URLs
`contact`	Current contact details when available
`comments`	Visible comments
`comment_submit_url`	Comment submission URL

Every library item includes id, type, title, description, image, and url. Product items add product, display_price, and price. Enrollment-pack items add enrollment_pack and price. Medium items add kind, video_url, pdf_url, image_url, and powerpoint_url.

My Site template

Use fluid_affiliate in mysite templates.

Group	Fields
Profile	`name`, `bio`, `image`
Social links	`facebook_url`, `twitter_url`, `instagram_url`, `linkedin_url`, `youtube_url`, `tiktok_url`, `pinterest_url`, `whatsapp_url`, `wechat_url`
Custom links	`links` with `text` and `url`
Display cards	`my_site_displayables`

Each display card carries id, favoriteable_type, favoriteable_id, and a favoriteable object. The nested object provides id, type, title, description, and image, plus resource-specific fields. Product cards add display_price, price, and url. Enrollment-pack cards add enrollment_pack, price, and url. Medium cards add kind, the matching media URLs, and url. Page, promotion, and playlist cards add url. Personal-site renders are per-affiliate, so affiliate values resolve to real values here rather than hydration sentinels.

Cart template

Use cart in cart_page templates.

Group	Fields
Identity	`id`, `cart_token`, `email`, `phone`, `state`, `type`
Currency	`currency_code`, `currency_symbol`, `currency_decimal_places`
Amounts	`sub_total`, `subtotal_after_discounts`, `discount_total`, `shipping_total`, `tax_total`, `amount_total`, plus formatted `_in_currency` values
Display totals	`shipping_total_for_display`, `tax_total_for_display`, `totals`
Tax	`price_inclusive_of_tax`, `price_inclusive_tax_name`, `tax_exempt`, `inclusive_shipping_tax`
Discounts	`discount_codes`, `product_discount_codes`, `shipping_discount_codes`, `shipping_discount`, `discount_breakdown`
Points	`points_enabled`, `points_applied`, `customer_total_points`, `remaining_customer_points`, `max_applicable_points`, and their `_in_currency` siblings
Enrollment	`enrollment_fee`, `enrollment_fee_in_currency`, `enrollment_pack`, `agreements`
Volume	`cv_total`, `qv_total`
Lines	`items`, `recurring`
Shipping	`shipping_method`, `available_shipping_methods`, `ship_to`, `bill_to`
Payment	`payment_method`, `available_payment_methods`, `requires_payment_method`, `requires_3ds`
Context	`company`, `country`, `attribution`, `digital_only`, `valid_for_checkout`
Checkout	`checkout_url`

Cart items contain the line’s resource, quantity, pricing, and option data supplied to the storefront cart. Guard optional product or enrollment-pack details because the item shape depends on its resource. Amounts are decimals, and every _in_currency sibling is a formatted string. Use the _for_display fields where a total may not be calculated yet — they render a placeholder instead of a misleading zero.

Post template

Use post for the current post.

Group	Fields
Identity	`title`, `slug`, `preview_url`, `active`
Content	`description`, `summary`, `image_url`
Dates and author	`created_at`, `updated_at`, `post_date`, `post_author`
Taxonomy	`category`, `collections`

A post template’s post carries no id. Its category and collection summaries are trimmed to id, title, description, and image_url. Posts read from the posts and most_popular_posts collections carry more: id, status, scheduled_at, the aliases handle, url, image, content, excerpt, author, and published_at, and full category and collection values rather than trimmed summaries.

Page template

Use page in page templates.

Field	Description
`title`	Page title
`page_content`	Page body
`content`	Alias of `page_content`

Error page template

Use these values in error_page templates:

Variable	Description
`error.status_code`	HTTP status code
`error.status_message`	Status message
`base_url`	Storefront base URL
`logo_url`	Company logo or the default logo
`shop_url`	Attributable shop URL

Member page templates

Templates of type members_dashboard and members_page render on every request for the signed-in member. They receive these values on top of the global variables:

Variable	Useful fields
`member`	`first_name`, `last_name`, `full_name`, `email`, `status`
`member_routes`	`root`, `sign_out`, `csrf_token`
`settings.menu`	The member site’s navigation: `title`, `handle`, and `menu_items` with `title`, `url`, and `sub_menu_items`

The members_login template renders for guests. It receives member_routes.sign_in_url and member_routes.root, and no member value. Storefront templates never receive member. Use the member helpers described in Member-aware sections there, and see Member page templates for the member area.

Index templates

The category_page, collection_page, and post_page templates add no variables of their own. Read the global categories, collections, and posts collections instead.

{% for collection in collections %}
  <a href="{{ collection.url }}">{{ collection.title }}</a>
{% endfor %}

Tag-scoped variables

Two tags introduce a variable that exists only inside the tag. {% paginate %} sets paginate with current_page, pages, items, page_size, current_offset, end_offset, previous, next, and parts:

{% paginate collection.products by 12 %}
  {% for item in collection.products %}
    <a href="{{ item.url }}">{{ item.title }}</a>
  {% endfor %}

  {% if paginate.next %}
    <a href="{{ paginate.next.url }}">Next</a>
  {% endif %}
{% endpaginate %}

paginate.previous, paginate.next, and each paginate.parts entry carry title, url, and is_link. previous and next are blank at the ends of the range. {% form %} sets form with errors, posted_successfully?, and the submitted field values.

Use variables from schema settings

Resource settings resolve saved identifiers into Liquid values. For example, a product setting makes the selected product available at section.settings.featured_product.

{% assign featured_product = section.settings.featured_product %}

{% if featured_product %}
  <a href="{{ featured_product.url }}">
    {{ featured_product.title }}
  </a>
{% endif %}

Use the setting ID as the key under section.settings or block.settings. An unresolvable identifier produces an empty value, so guard the setting before you read a field. Each resolving setting type produces a predictable shape:

Setting type	Resolved value
`product`	A product entry, matching products read from a resource collection
`variant`	A variant with identity, availability, option values, localized pricing, images, and points
`collection`	A collection value with its products
`category`	A category value with its products
`enrollment_pack`	An enrollment-pack value
`media`	A medium value
`link_list`	A menu with `title`, `handle`, and nested `menu_items`
`product_list`	An array of compact product entries
`color_scheme`	A scheme with `id` and a `settings` object of color values

A color value answers red, green, blue, alpha, hue, saturation, lightness, rgb, and rgba, and renders as its original string.

{% assign scheme = section.settings.color_scheme %}

<section style="background: rgb({{ scheme.settings.background.rgb }})">
  {{ section.settings.heading }}
</section>

See schema components for supported resource setting types.

Get Started

Core Concepts

Guides

Migration guides

Website & Themes

FairShare SDK

Files SDK

Portal & Widgets

Use Liquid theme variables

Understand variable scope

Global variables

Company points labels

Affiliate hydration

Localization

Playlist navigation

Navbar and footer

Product template

Variants and per-country pricing

Legacy top-level product values

Products read from a resource collection

Shop template

Collection template

Category template

Home template

Join template

Medium template

Enrollment-pack template

Library template

My Site template

Cart template

Post template

Page template

Error page template

Member page templates

Index templates

Tag-scoped variables

Use variables from schema settings

​Understand variable scope

​Global variables

​Company points labels

​Affiliate hydration

​Localization

​Playlist navigation

​Navbar and footer

​Product template

​Variants and per-country pricing

​Legacy top-level product values

​Products read from a resource collection

​Shop template

​Collection template

​Category template

​Home template

​Join template

​Medium template

​Enrollment-pack template

​Library template

​My Site template

​Cart template

​Post template

​Page template

​Error page template

​Member page templates

​Index templates

​Tag-scoped variables

​Use variables from schema settings

Understand variable scope

Global variables

Company points labels

Affiliate hydration

Localization

Playlist navigation

Navbar and footer

Product template

Variants and per-country pricing

Legacy top-level product values

Products read from a resource collection

Shop template

Collection template

Category template

Home template

Join template

Medium template

Enrollment-pack template

Library template

My Site template

Cart template

Post template

Page template

Error page template

Member page templates

Index templates

Tag-scoped variables

Use variables from schema settings