SDK overview

This page documents @commerce-blocks/sdk v3 (3.x). For v2 integrations, see Upgrade to v3.

App embed installed? Then the theme only renders. On a Shopify theme with the Layers app embed enabled, the embed’s Storefront Pixel wraps every Layers request the SDK makes. It owns:

Identity: device, session, and customer IDs. Leave identity unset in createSDK().
Context: market, locale, currency, cart, purchase history, customer profile, and marketing parameters. Don’t hand-build these. See Context for the few fields a theme still sends.
Semantic redirects: the pixel follows _meta.redirect from search and autocomplete responses. Don’t navigate on it in theme code.
Block deduplication: the pixel sets excludeProductIds on every Blocks request to the products already on the page. Any excludeProductIds you send is replaced.
Attribution and tracking: product, block, banner, and search events, and the _layers_attribution add-to-cart property.

Your theme passes the tokens from #layers-config, calls the SDK with the request inputs (collection, query, filters, sort, page), and renders the results. The identity and context examples in these pages are for headless storefronts that don’t load the embed.

The Layers SDK (@commerce-blocks/sdk) is an ES module SDK for product discovery powered by the Layers API. It provides reactive state management, built-in caching, and a unified interface for browse, search, recommendations, and image search.

Key features

Layers API integration

Full access to Layers’ search, browse, recommendations, blocks, and image search APIs with built-in error handling.

Reactive state management

Framework-agnostic reactive controllers with subscribe() for automatic UI updates and in-flight request deduplication.

Product card controller

Reactive product card management with variant selection, availability logic, and automatic state updates.

Extensibility

Transform products, collections, search, blocks, and other responses with custom transforms. Build filters with a type-safe DSL.

Quick start

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

const { data: sdk, error } = createSDK({
  storefrontAccessToken: 'your-storefront-token',
  trackingToken: 'your-tracking-token',
  currencyCode: 'USD',
})

if (error) {
  console.error('SDK init failed:', error.message)
} else {
  const collection = sdk.collection({ collectionHandle: 'shirts' })
  const result = await collection.get()

  if (result.data) {
    console.log(result.data.products)
  }

  collection.dispose()
}

SDK methods

The SDK returns controllers for all Layers storefront APIs:

Method	Description
`sdk.collection()`	Browse and filter products within merchandised collections
`sdk.search()`	Semantic product search with prepare/get flow
`sdk.autocomplete()`	Predictive search suggestions
`sdk.suggest()`	Deprecated autocomplete wrapper with built-in debounce
`sdk.blocks()`	Product recommendations powered by Layers blocks
`sdk.uploadImage()`	Upload images for image-based search
`sdk.imageSearch()`	Search products using uploaded images
`sdk.searchByImage()`	Deprecated alias for `imageSearch()`
`sdk.searchContent()`	Search articles and blog content
`sdk.similarProducts()`	Find products similar to a given product
`sdk.facets()`	Fetch facet counts and ranges for a collection
`sdk.sortOrders()`	Fetch available sort options at runtime
`sdk.searchFeedback()`	Send search-quality feedback
`sdk.trackingEvent()`	Send analytics events via `sendBeacon` with a fetch fallback
`createProductCard()`	Reactive product card with variant selection and availability logic

Architecture

The SDK uses a controller pattern where each method returns a controller with reactive state and a get() method. All controllers support two ways to consume state:

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

const collection = sdk.collection({
  collectionHandle: 'shirts',
  sort: 'featured',
})

// 1. Controller subscribe (no extra import needed)
const unsubscribe = collection.subscribe(({ data, error, loading }) => {
  if (loading) console.log('Loading...')
  if (error) console.error('Error:', error.message)
  if (data) console.log('Products:', data.products)
})

// 2. Standalone subscribe utility
const unsubscribe2 = subscribe(collection, (state) => {
  console.log('State changed:', state)
})

// Read current state synchronously
const { data, loading, error } = collection.state

// Fetch results
await collection.get() // initial load
await collection.get({ pagination: { page: 2 } }) // pagination
await collection.get({ sort: 'price_asc' }) // change sort

// Cleanup
unsubscribe()
unsubscribe2()
collection.dispose()

Next steps

Installation

Learn how to install and configure the SDK in your project.

API reference

Explore the complete API reference for all SDK methods.

Framework integration

Patterns for React, Vue, Svelte, Lit, Alpine.js, and vanilla JS.

Error handling

Learn how to handle errors gracefully with the Result pattern.

Overview

SDK Reference

SDK Guides

Changelog & Upgrades

AI Enablement

Key features

Layers API integration

Reactive state management

Product card controller

Extensibility

Quick start

SDK methods

Architecture

Next steps

Installation

API reference

Framework integration

Error handling

​Key features

Layers API integration

Reactive state management

Product card controller

Extensibility

​Quick start

​SDK methods

​Architecture

​Next steps

Installation

API reference

Framework integration

Error handling

Key features

Quick start

SDK methods

Architecture

Next steps