Liquid integration

Overview

Layers metaobjects and metafields are accessible in your Shopify theme via Liquid. Use them to render the structure of custom sort order selectors, facet filters, and recommendation blocks (names, codes, and settings) server-side, without JavaScript. The live data that fills them, such as facet values and counts or the products in a recommendation block, comes from the Layers APIs, so you still need JavaScript (or the SDK) to fetch it. All Layers metaobjects have public storefront access, so they are available in any Liquid template.

Namespace reference

Layers uses the following namespaces for metaobjects:

Resource	Namespace
Sort Orders	`app--278936322049--sort_order`
Facets	`app--278936322049--facet`
Blocks	`app--278936322049--block`
Collection Metafields	`layers`
App Installation Metafields	`layers`

Accessing sort orders

Sort order metaobjects represent the sort orders configured in your Layers dashboard.

Basic access

{% assign layers_sort_metaobjects = shop.metaobjects['app--278936322049--sort_order'] %}

<select name="sort_order">
  {% for sort_order in layers_sort_metaobjects %}
    <option value="{{ sort_order.code.value }}">
      {{ sort_order.name.value }}
    </option>
  {% endfor %}
</select>

Available fields

Field	Type	Description
name	string	Display name of the sort order
code	string	Unique code identifier
scope	array	Contexts where available (search, collection)
order	integer	Display order

Filtering by scope

Display only sort orders available for specific contexts:

{% assign layers_sort_metaobjects = shop.metaobjects['app--278936322049--sort_order'] %}

<!-- Collection page sort orders -->
<select name="sort_order">
  {% for sort_order in layers_sort_metaobjects %}
    {% assign scopes = sort_order.scope.value %}
    {% if scopes contains 'collection' %}
      <option value="{{ sort_order.code.value }}">
        {{ sort_order.name.value }}
      </option>
    {% endif %}
  {% endfor %}
</select>

Ordering by display order

{% assign layers_sort_metaobjects = shop.metaobjects['app--278936322049--sort_order'] %}
{% assign sorted_orders = layers_sort_metaobjects | sort: 'order' %}

<ul class="sort-options">
  {% for sort_order in sorted_orders %}
    <li data-code="{{ sort_order.code.value }}">
      {{ sort_order.name.value }}
    </li>
  {% endfor %}
</ul>

Using collection default sort order

Access the default sort order assigned to a collection:

{% assign default_sort_code = nil %}
{% if collection.metafields.layers.default_sort_order %}
  {% assign default_sort_code = collection.metafields.layers.default_sort_order.value.code.value %}
{% endif %}

{% assign layers_sort_metaobjects = shop.metaobjects['app--278936322049--sort_order'] %}

<select name="sort_order">
  {% for sort_order in layers_sort_metaobjects %}
    <option 
      value="{{ sort_order.code.value }}"
      {% if sort_order.code.value == default_sort_code %}selected{% endif %}
    >
      {{ sort_order.name.value }}
    </option>
  {% endfor %}
</select>

Facet metaobjects represent filterable attributes configured in Layers.

Basic access

{% assign layers_facet_metaobjects = shop.metaobjects['app--278936322049--facet'] %}

<div class="facet-list">
  {% for facet in layers_facet_metaobjects %}
    <div class="facet" data-code="{{ facet.code.value }}">
      <h3>{{ facet.name.value }}</h3>
    </div>
  {% endfor %}
</div>

Available fields

Field	Type	Description
name	string	Display name of the facet
code	string	Unique code identifier

{% assign layers_facet_metaobjects = shop.metaobjects['app--278936322049--facet'] %}

<aside class="filters">
  <h2>Filter by</h2>
  {% for facet in layers_facet_metaobjects %}
    <div class="filter-group">
      <h3>{{ facet.name.value }}</h3>
      <div class="filter-options" data-facet="{{ facet.code.value }}">
        <!-- Facet values populated via JavaScript from Layers API -->
      </div>
    </div>
  {% endfor %}
</aside>

Facet metaobjects only provide the facet configuration (name and code). Actual facet values, counts, and numeric ranges must be fetched with JavaScript from the Facets API. Browse responses include the same facets and facetRanges fields. See Rendering facets in Liquid.

Accessing blocks

Block metaobjects represent recommendation blocks configured in Layers.

The metaobject’s system handle is not the block ID. Layers generates handles in the form layers-<lowercase block ID> (for example, layers-01j8abcd1234xyz), and the block ID itself is not exposed as a field. To get the ID the Blocks API expects, strip the prefix and uppercase the remainder:

{{ block.system.handle | remove_first: 'layers-' | upcase }}

Passing the raw system.handle as the blockId returns no products. The handle never matches a block ID, so the request silently misses the block instead of surfacing an error.

Basic access

{% assign layers_blocks = shop.metaobjects['app--278936322049--block'] %}

{% for block in layers_blocks %}
  <div class="recommendation-block" data-block-id="{{ block.system.handle | remove_first: 'layers-' | upcase }}">
    <h2>{{ block.title.value }}</h2>
    <!-- Block content populated via JavaScript from Layers API -->
  </div>
{% endfor %}

Available fields

Field	Type	Description
label	string	Display label (formatted as “Title - AnchorType”)
title	string	Block title
anchor_type	string	Anchor type (product, collection, cart, none)

Filtering by anchor type

Display blocks based on the current page context:

{% assign layers_blocks = shop.metaobjects['app--278936322049--block'] %}

<!-- Collection pages -->
{% if template == 'collection' %}
  {% for block in layers_blocks %}
    {% if block.anchor_type.value == 'collection' %}
      <div class="recommendation-block" data-block-id="{{ block.system.handle | remove_first: 'layers-' | upcase }}">
        <h2>{{ block.title.value }}</h2>
      </div>
    {% endif %}
  {% endfor %}
{% endif %}

<!-- Product pages -->
{% if template == 'product' %}
  {% for block in layers_blocks %}
    {% if block.anchor_type.value == 'product' %}
      <div class="recommendation-block" data-block-id="{{ block.system.handle | remove_first: 'layers-' | upcase }}">
        <h2>{{ block.title.value }}</h2>
      </div>
    {% endif %}
  {% endfor %}
{% endif %}

Accessing app configuration

The Layers theme app embed writes your storefront configuration into every page as a JSON script tag in the <head>. This tag is the recommended source, so you don’t need to read metafields to get it:

<script id="layers-config" type="application/json">
  { "apiToken": "...", "storefrontApiToken": "...", "integrations": {...} }
</script>

Parse it from JavaScript:

const layersConfig = JSON.parse(
  document.getElementById('layers-config').textContent,
)
// layersConfig.apiToken — analytics tracking token
// layersConfig.storefrontApiToken — storefront token

Available fields

Field	Type	Description	`createSDK()` option
apiToken	string	Analytics tracking token	`trackingToken`
storefrontApiToken	string	Storefront token	`storefrontAccessToken`
integrations	object	Enabled integrations and their configurations	Not passed to `createSDK()`
sessionCookieFallbacks	array	Cookie names for session identification	Not passed to `createSDK()`

Reading the tokens in Liquid

If you need the tokens server-side in Liquid instead, Layers also writes them to shop metafields:

Value	Liquid path
Full configuration (same JSON as the tag)	`shop.metafields.layers.embed_settings.value`
Storefront token	`shop.metafields.commerce_blocks.layers_token`
Analytics tracking token	`shop.metafields.commerce_blocks.layers_tracking_token`

If these metafields are empty on an older installation, trigger a resync from Settings → Integrations in the Layers dashboard. See Collection & app metafields.

Best practices

Performance

Cache metaobject queries when possible using Liquid variables
Minimize the number of metaobject iterations in your templates
Use JavaScript to fetch dynamic data (facet values, recommendations) rather than making multiple Liquid queries

Error handling

Always check if metaobjects exist before accessing them:

{% if shop.metaobjects['app--278936322049--sort_order'] %}
  {% assign layers_sort_metaobjects = shop.metaobjects['app--278936322049--sort_order'] %}
  <!-- Your code here -->
{% endif %}

Namespace consistency

Use the exact namespace values provided in this documentation. The namespace includes the Layers app ID and must match exactly:

{% comment %} Correct {% endcomment %}
{% assign layers_sort_metaobjects = shop.metaobjects['app--278936322049--sort_order'] %}

{% comment %} Incorrect - missing the app ID prefix {% endcomment %}
{% assign layers_sort_metaobjects = shop.metaobjects['sort_order'] %}

Always use the full namespace (app--278936322049--<type>) when accessing Layers metaobjects via Liquid. Short forms or aliases will not resolve.

Troubleshooting

Metaobjects not appearing

If metaobjects are not accessible in Liquid:

Verify the sort order has Enable as Storefront Sort enabled in Layers
Verify the facet has Enable as Storefront Facet enabled in Layers
Check that the metaobject was created (visible in Shopify admin under Content → Metaobjects)
Ensure you’re using the correct namespace

Empty values

If metaobject fields return empty values:

Verify the field exists in the Layers dashboard
Check that the metaobject has been synced (may take a few seconds after creation)
Use .value to access field values: {{ sort_order.name.value }}

Collection default sort order not found

If the collection’s default sort order is not accessible:

Verify a default sort order is assigned in the Shopify admin (Products → Collections → [Collection] → Metafields) or on the collection’s page in the Layers dashboard
Check that the referenced sort order still exists in Layers
Ensure you’re using the correct metafield namespace