Rendering blocks in Liquid

Overview

A recommendation block in a Shopify theme is a Liquid section with a single setting: which Layers block to render. Your section fetches the products. The Layers app embed handles the cross-cutting work on that request: adding shopper identity and cart context, excluding products already shown on the page so blocks don’t repeat each other, and tracking clicks on the results. You only need to:

Add a metaobject section setting so merchandisers pick a Layers block by name, not by typing an ID.
Render a placeholder element with the selected block’s ID.
Call the Blocks API to fill it with products.

A block metaobject’s system handle is not the block ID the Blocks API expects. Layers generates handles as layers-<lowercase block ID> (for example, layers-01j8abcd1234xyz), and the raw block ID is not stored in any metaobject field. Derive the ID in Liquid:

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

Passing the raw system.handle as blockId silently returns no products. layers-01j... never matches a block ID, so the request misses the block without an error you can trace to it.

Use this version when you’re scripting against the storefront API directly with fetch. For the SDK version, see Rendering blocks with the SDK.

Prerequisites

The Layers Shopify app installed with the app embed enabled. The app embed adds cart context, cross-block deduplication, and click attribution to your requests automatically. Your section only needs to fetch products.
A storefront token. The app embed emits it on every page as a <script id="layers-config" type="application/json"> tag in the theme <head>. Parse it from JavaScript rather than reading metafields. See Liquid integration.

{% comment %} theme.liquid layout {% endcomment %}
<script>
  const configEl = document.getElementById('layers-config')
  if (!configEl) throw new Error('Layers config tag not found — is the app embed enabled?')
  const layersConfig = JSON.parse(configEl.textContent)
  window.layersConfig = {
    storefrontApiToken: layersConfig.storefrontApiToken,
    apiBase: 'https://app.uselayers.com/api/storefront/v1',
  }
</script>

The section

Create sections/layers-recommendations.liquid. The recommended block picker is a native Shopify metaobject setting that points at the Layers block metaobject definition. The theme editor then lists every Layers block by name, with no option list to maintain.

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

{% if layers_block != blank %}
  {% assign selected_block_id = layers_block.system.handle | remove_first: 'layers-' | upcase %}
  <section
    class="layers-recommendations"
    data-block-id="{{ selected_block_id }}"
    data-anchor-id="{% if template == 'product' %}{{ product.id }}{% elsif template == 'collection' %}{{ collection.handle }}{% endif %}"
  >
    {% if section.settings.heading != blank %}
      <h2>{{ section.settings.heading }}</h2>
    {% endif %}
    <ol class="layers-recommendations__products" data-loading="true"></ol>
  </section>
{% endif %}

{% schema %}
{
  "name": "Layers Recommendations",
  "settings": [
    {
      "type": "text",
      "id": "heading",
      "label": "Heading",
      "default": "You may also like"
    },
    {
      "type": "metaobject",
      "id": "layers_block",
      "label": "Block",
      "info": "Choose a Layers recommendation block.",
      "metaobject_type": "app--278936322049--block"
    }
  ],
  "presets": [{ "name": "Layers Recommendations" }]
}
{% endschema %}

metaobject_type takes the Layers block definition’s type, app--<app-id>--block. For the Layers app that’s app--278936322049--block, the same type you read with shop.metaobjects['app--278936322049--block']. Use the full string in a theme schema, not the app-scoped $app:block shorthand. The setting returns the selected metaobject, not a block ID. Derive the ID from its system handle with remove_first: 'layers-' | upcase, as in the section above. When no block is selected, the setting is blank and the section renders nothing.

Generating block options in the theme editor

Use one of these alternatives only if your theme can’t use a metaobject setting. Both generate options from the same block metaobjects. select setting. Shopify schema is static JSON, so a select setting can’t list blocks inline. Most themes that use one update the section schema through the Shopify Admin API when the app is installed, with option values already converted to block IDs:

{
  "type": "select",
  "id": "block_id",
  "label": "Block",
  "info": "Choose a Layers recommendation block.",
  "options": [
    { "value": "", "label": "Select a block" }
  ]
}

datalist with a text setting. For a Liquid-only path, render a <datalist> from the metaobjects and use a text setting with id block_id. The value is already a block ID, so read it with {% assign selected_block_id = section.settings.block_id %} instead of the handle transform:

{% comment %} snippets/layers-blocks-datalist.liquid {% endcomment %}
{% assign layers_blocks = shop.metaobjects['app--278936322049--block'] %}
<datalist id="layers-block-ids">
  {% for block in layers_blocks %}
    <option value="{{ block.system.handle | remove_first: 'layers-' | upcase }}">{{ block.title.value }} - {{ block.anchor_type.value }}</option>
  {% endfor %}
</datalist>

With any of the three, the merchandiser selects from the live list of Layers blocks instead of pasting a ULID.

Fetching products

The section renders an empty placeholder with the block ID and the current page’s anchor. A small script fetches products for each placeholder and hydrates it.

async function hydrate(section) {
  const blockId = section.dataset.blockId
  const anchorId = section.dataset.anchorId

  const response = await fetch(
    `${window.layersConfig.apiBase}/blocks/${blockId}/products`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Storefront-Access-Token': window.layersConfig.storefrontApiToken,
      },
      body: JSON.stringify({
        ...(anchorId ? { anchor_id: anchorId } : {}),
        pagination: { page: 1, limit: 12 },
      }),
    },
  )

  if (!response.ok) {
    section.hidden = true
    return
  }

  const { results } = await response.json()
  if (!results.length) {
    section.hidden = true
    return
  }

  renderProducts(section.querySelector('.layers-recommendations__products'), results)
}

document.querySelectorAll('.layers-recommendations').forEach(hydrate)

function renderProducts(list, products) {
  list.removeAttribute('data-loading')
  list.innerHTML = products
    .map(
      (p) => `
        <li>
          <a href="/products/${p.handle}">
            <img src="${p.featured_media?.preview_image?.src ?? ''}" alt="" />
            <h3>${p.title}</h3>
            <span>${p.price_range?.min_variant_price ?? ''}</span>
          </a>
        </li>
      `,
    )
    .join('')
}

Anchors

The section reads the right anchor automatically based on template:

Template	`anchor_id` sent
`product`	`{{ product.id }}`
`collection`	`{{ collection.handle }}`
Anything else	omitted (cart-anchored and global blocks resolve without one)

The Layers theme app extension supplies cart context and shopper identity to every Blocks request on the storefront, so cart-anchored blocks work without your section reading /cart.js or wiring up productsInCart.

What the app embed handles for you

Once the Layers theme app extension is installed and enabled, you do not need to:

Send context.productsInCart for cart-anchored blocks. The embed injects it.
Pass excludeProductIds between blocks. The embed adds its IDs to any excludeProductIds you send on every Blocks request, keeping your IDs and including products already on the page: results from other blocks, items in the cart, the product being viewed, and products from the search or collection grid. To turn this off, check Disable block deduplication in the Layers app embed settings in the theme editor.
Wire up click attribution or feedback. The embed listens for clicks on rendered cards and submits feedback automatically.
Provide identity (deviceId, sessionId). The storefront pixel manages it.

Your section only renders the placeholder and issues the products request.

Empty blocks and fallbacks

The Blocks API runs the block’s fallback chain server-side. If the chain doesn’t produce results, the response is { results: [] }. Hide the section (as the hydrate function in Fetching products does) rather than rendering an empty heading.

Troubleshooting

The section is empty in the theme editor. Make sure the merchandiser has selected a block in the section’s settings. The section hides itself when no block is selected. The block fetches but renders nothing. The block fell through its fallback chain. Review configuration in the dashboard. Cart recommendations look stale after /cart updates. The app embed keeps its cart context up to date when the Shopify cart changes, but it doesn’t re-request blocks that are already on the page. Call your hydrate function again after a cart change (for example, when your cart drawer updates) so the block is fetched with the new cart. If the new request still shows old cart contents, confirm the Layers theme app extension is enabled in Online Store → Themes → Customize → App embeds.

Liquid Integration

Liquid + Fetch guides

Liquid + SDK guides

Rendering blocks in Liquid

Overview

Prerequisites

The section

Generating block options in the theme editor

Fetching products

Anchors

What the app embed handles for you

Empty blocks and fallbacks

Troubleshooting

See also

​Overview

​Prerequisites

​The section

​Generating block options in the theme editor

​Fetching products

​Anchors

​What the app embed handles for you

​Empty blocks and fallbacks

​Troubleshooting

​See also

Overview

Prerequisites

The section

Generating block options in the theme editor

Fetching products

Anchors

What the app embed handles for you

Empty blocks and fallbacks

Troubleshooting

See also