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.

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.

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.

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. 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

Identity, context, and attribution

Anchors

Why the SDK over Fetch

Troubleshooting

See also

​Overview

​Prerequisites

​The section

​Hydrating the section

​Identity, context, and attribution

​Anchors

​Why the SDK over Fetch

​Troubleshooting

​See also

Overview

Prerequisites

The section

Hydrating the section

Identity, context, and attribution

Anchors

Why the SDK over Fetch

Troubleshooting

See also