Rendering blocks with the SDK

Overview

This is the SDK equivalent of Rendering blocks in Liquid. The shape of the section is the same: one Liquid section, one merchandiser-facing block-picker setting. The SDK’s blocks() controller does the HTTP call, deduplicates in-flight requests, caches responses in memory for the life of the page, and exposes the products on reactive state. The SDK sends exactly the values your code supplies and returns results with an attributionToken for tracking. Use this version when you have already installed @commerce-blocks/sdk in your theme. For a no-dependencies version, see the Liquid + Fetch guide.

Prerequisites

The Layers Shopify app installed and the theme app extension enabled in Online Store → Themes → Customize → App embeds.
The SDK installed and initialized in your theme. See SDK installation.

The section

sections/layers-recommendations.liquid is the same Liquid scaffold as the Fetch version: a section with a block-picker setting and a single placeholder element carrying the selected block ID.

{% assign selected_block_id = section.settings.block_id %}

{% if selected_block_id != blank %}
  <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": "select",
      "id": "block_id",
      "label": "Block",
      "info": "Choose a Layers recommendation block.",
      "options": [
        { "value": "", "label": "Select a block" }
      ]
    }
  ],
  "presets": [{ "name": "Layers Recommendations" }]
}
{% endschema %}

The select options are populated from block metaobjects. See the Fetch guide for the pattern that mirrors metaobjects into the dropdown so merchandisers select by name instead of pasting a ULID.

A block metaobject’s system handle is not the value to pass as blockId. 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 silently returns no products — the handle never matches a block ID.

Hydrating the section

For each rendered section, create an sdk.blocks() controller with the selected block ID and the page anchor. Subscribe to the state and render on data changes.

import { getSDK } from '@commerce-blocks/sdk'

const { data: sdk, error: sdkError } = getSDK()
if (sdkError) {
  console.error('SDK not initialized:', sdkError.message)
}

function hydrate(section) {
  const blockId = section.dataset.blockId
  const anchorId = section.dataset.anchorId || undefined
  const list = section.querySelector('.layers-recommendations__products')

  const blocks = sdk.blocks({ blockId, anchorId })

  blocks.subscribe(({ data, error }) => {
    if (error || (data && !data.products.length)) {
      section.hidden = true
      return
    }
    if (data) renderProducts(list, data.products)
  })

  blocks.get({ pagination: { limit: 12 } })
}

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.featuredMedia?.url ?? ''}" alt="" />
            <h3>${p.title}</h3>
            <span>${p.price?.formatted ?? ''}</span>
          </a>
        </li>
      `,
    )
    .join('')
}

That is the whole integration. Multiple sections on the same page each get their own controller, run independently, and reuse the SDK’s cache and dedup machinery.

Rendering cards with your theme’s own Liquid snippets

A client-side card renderer drifts out of sync with the theme’s product card (badges, ratings, swatches, variant logic). The more durable pattern is Shopify’s Section Rendering API: create one thin section per surface that renders your existing card snippet for a single product, then fetch it once per result handle.

{% comment %} sections/layers-card-search.liquid {% endcomment %}
{% render 'product-card',
  product: product,
  current_variant: product.selected_or_first_available_variant,
  show_rating: section.settings.show_rating
%}

async function fetchCards(products, sectionId) {
  const results = await Promise.allSettled(
    products.map((p) => {
      // Pass the matched variant through as a product-page ?variant= param so
      // the section renders the variant Layers selected, not the default
      const variantId = p.selectedVariant?.numericId
      const variantParam = variantId ? `?variant=${variantId}&` : '?'
      return fetch(`/products/${p.handle}${variantParam}sections=${sectionId}`)
        .then((r) => (r.ok ? r.json() : null))
        .then((json) => json?.[sectionId] ?? '')
    })
  )

  // Order follows `products` exactly; failed or empty cards drop out
  return results
    .map((r) => (r.status === 'fulfilled' ? r.value : ''))
    .filter((html) => html.trim())
}

Each request returns { "<sectionId>": "<rendered HTML>" } — a map of section ID to its HTML fragment. A missing product or a section that renders nothing produces an empty string or a missing key, which is why the helper filters blank cards.

One request per result, fired in parallel — a failed fetch drops that card instead of breaking the rail.
Pass the product’s selectedVariant.numericId as the product-page variant parameter so the section renders the variant Layers selected (filters, ranking, variant breakouts) — without it Shopify renders first_available_variant and two breakout tiles of one product collapse into identical cards. The SDK always requests the matched variant and exposes it as selectedVariant; use numericId, because id is the layers--prefixed SDK ID. If you call the API with Fetch instead, the raw result carries it as first_or_matched_variant.id.
?sections= accepts up to 5 comma-separated section IDs per request, so distinct surfaces can share a round trip.
Keep the section’s card arguments in sync with the native grid (rating settings, hide-tag skips, favorite button). The section is the single place that mapping lives.
Grid markup still comes from the Liquid section wrapping the rail; only the tile HTML is fetched.

Identity, context, and attribution

The app embed provides the storefront pixel and its standard theme tracking. Pass the values your block requests need through the SDK:

Identity: Pass identity to createSDK() as a static object or a resolver that runs on every request. On a pixel-driven storefront, read device and session identifiers from the storefront pixel and pass them through. The SDK does not read them for you.
Cart context and exclusions: Pass context and excludeProductIds on the request when you need cart-anchored blocks or cross-block product deduplication.
Click attribution: Results carry an attributionToken. The storefront pixel covers standard themes. For custom-rendered cards, forward attributionToken on your click and add-to-cart tracking.

Anchors

sdk.blocks({ blockId, anchorId }) resolves the right value based on template:

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

Both numeric IDs and Shopify GIDs are accepted on product anchors; both IDs and handles are accepted on collection anchors.

Search-anchored blocks

Blocks on the search anchor running searched_then_viewed or searched_then_purchased strategies do not read the query from anchor_id. They resolve the shopper’s query from context.priorSearches — specifically the last searchQuery — so the caller must record submitted search queries and pass them on the request:

blocks.get({
  pagination: { limit: 12 },
  context: {
    priorSearches: [{ searchQuery: submittedQuery }],
  },
})

Without context.priorSearches, a search-anchored block has no query to work from and falls through to its fallback chain. On a first visit before any search has been submitted there is nothing to anchor to — give the block a fallback (trending, manual, or bestsellers) that still produces a rail on cold opens.

Why the SDK over Fetch

Concern	Fetch version	SDK version
Driving the request	`fetch` to `/blocks/{id}/products`	`blocks.get()`
Re-renders	DIY DOM updates	`subscribe()` callback
Caching during the page	DIY	In-memory cache and request deduplication
Multiple blocks per page	Manual orchestration	Independent controllers, SDK dedupes identical requests

Both paths send exactly the cart context, exclusions, identity, and attribution values your code passes.

Troubleshooting

The section renders but the grid stays empty. The block fell through its fallback chain. Review fallback configuration in the dashboard. No Layers requests fire at all. Work this checklist in order: (1) <script id="layers-config"> is present in the page <head> with a non-empty storefrontApiToken — if the tag is missing or blank, enable the app embed (see SDK installation); (2) the block picker in the section settings is actually assigned — an unpicked setting silently no-ops; (3) the ID reaching blockId is the raw ULID, not the layers--prefixed metaobject handle (see the transform above). Block-picker dropdown is empty. Confirm block metaobjects are visible under Content → Metaobjects in Shopify admin, and that you have populated the section setting from those metaobjects (see the Fetch guide for the pattern). Cart-anchored blocks do not refresh on cart changes. The theme app extension re-runs cart-anchored blocks. Confirm it is enabled under Online Store → Themes → Customize → App embeds.

Liquid Integration

Liquid + Fetch guides

Liquid + SDK guides

Rendering blocks with the SDK

Overview

Prerequisites

The section

Hydrating the section

Rendering cards with your theme’s own Liquid snippets

Identity, context, and attribution

Anchors

Search-anchored blocks

Why the SDK over Fetch

Troubleshooting

See also

​Overview

​Prerequisites

​The section

​Hydrating the section

​Rendering cards with your theme’s own Liquid snippets

​Identity, context, and attribution

​Anchors

​Search-anchored blocks

​Why the SDK over Fetch

​Troubleshooting

​See also

Overview

Prerequisites

The section

Hydrating the section

Rendering cards with your theme’s own Liquid snippets

Identity, context, and attribution

Anchors

Search-anchored blocks

Why the SDK over Fetch

Troubleshooting

See also