Client methods

All methods return { data, error } controllers, except searchFeedback() and trackingEvent() which return a single direct { data, error } result. Controllers expose get(), subscribe(), and dispose(). get(query?) accepts query overrides only, not an options argument or AbortSignal. When you call get() again on the same controller, only the latest call updates its state and notifies subscribers. Earlier requests still run, and each returned promise resolves with its own result.

SDK instance creation

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

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

if (error) {
  console.error('SDK init failed:', error.message)
}

collection

Browse products in a collection.

const collection = sdk.collection({
  collectionHandle: 'shirts',
  pagination: { page: 1, limit: 24 },
})

const { data, error } = await collection.get()

if (error) {
  console.error('Collection fetch failed:', error.message)
} else if (data) {
  console.log(data.products, data.totalResults, data.totalPages, data.page)
}

The get() call accepts a shallow merge of the initial params, so you can change pagination, sort, or filters after the controller is created:

await collection.get({
  sort: 'price-asc',
  pagination: { page: 2, limit: 24 },
})

Full params for sdk.collection():

Param	Type	Description
`collectionHandle`	`string`	Collection handle (required). Use `'all'` for the whole catalog, even without a synced `/collections/all` collection. See Browse API.
`sort`	`string`	Sort order code
`pagination`	`{ page?: number; limit?: number }`	Pagination
`filterGroup`	`FilterGroup`	Filter group from the filter DSL
`dynamicLinking`	`{ products: Array<{ productId: string; position?: number }> }`	Products to pin on the first page. See Dynamic linking.
`defaultSelectedOptions`	`SearchSelectedOption[]`	Default option selections
`discounts`	`SearchDiscountEntitlement[]`	Discount entitlements
`forceHideOutOfStock`	`boolean`	Hide out-of-stock products
`previewId`	`string`	Preview identifier
`identity`	`Identity`	Device and session identity
`context`	`Context`	Session context
`responseOptions`	`ResponseOptions`	Response options
`facets`	`string[]`	Facets to include
`retrieveFacetCount`	`boolean`	Include facet counts
`includeFacetRanges`	`boolean`	Include facet ranges
`attributes`	`string[]`	Additional product attributes to request
`transformBody`	`function`	Mutate the request body before sending

Dynamic linking

dynamicLinking.products pins products on the first page. Each entry is a { productId, position? } object, where productId is a product handle or a numeric product ID as a string:

const collection = sdk.collection({ collectionHandle: 'summer' })
const { data, error } = await collection.get({
  dynamicLinking: {
    products: [
      { productId: 'summer-dress-blue', position: 1 },
      { productId: '8234567890123', position: 4 },
      { productId: 'classic-tee-white' },
    ],
  },
})

if (error) {
  console.error('Browse failed:', error.message)
}

The SDK sends dynamicLinking to the Browse API unchanged. position is the exact 1-based slot for that product on the first page, so in the example above summer-dress-blue lands at position 1 and product 8234567890123 at position 4, with regular results in positions 2 and 3. Products without a position are pinned in array order from the top of the page. If the same product appears more than once, the first explicit position wins. Products that don’t exist or aren’t available are skipped. If the store turns on out-of-collection linking, linked products that aren’t in the collection are also placed, and a position past the page size lands on a later page; send the same dynamicLinking value with every page request. With the Layers app embed enabled, the Storefront Pixel adds dynamicLinking itself when a shopper lands with a utm_products URL parameter, so you only pass it for pins your theme decides on.

search

Execute a full-text search. The search query is fixed when the controller is created. You can then update pagination, filters, and sort with get().

const search = sdk.search({
  query: 'running shoes',
  pagination: { page: 1, limit: 24 },
})

const { data, error } = await search.get()

if (error) {
  console.error('Search failed:', error.message)
} else if (data) {
  console.log(data.products, data.totalResults, data._meta?.redirect?.url)
}

The search controller automatically prepares the query before execution and retries when the API returns a 425 (not prepared yet).

searchContent

Search for non-product content such as articles.

const contentSearch = sdk.searchContent({
  query: 'shipping policy',
  contentType: 'article',
})

const { data, error } = await contentSearch.get()

if (error) {
  console.error('Content search failed:', error.message)
} else if (data) {
  console.log(data.articles, data.totalResults)
}

autocomplete

Fetch search suggestions as the shopper types. Unlike search, get() accepts a new query each call.

const autocomplete = sdk.autocomplete()

const { data, error } = await autocomplete.get({ query: 'run' })

if (error) {
  console.error('Autocomplete failed:', error.message)
} else if (data) {
  console.log(data.matchedQueries, data.originalQuery, data.normalizedQuery)
}

suggest (deprecated)

suggest() is a debounced wrapper around autocomplete(). It is retained for v2 compatibility but is deprecated. New code should use autocomplete() with createDebounce() or your framework’s debouncing utility.

const suggest = sdk.suggest()

const { data, error } = await suggest.get({ query: 'run' })

imageSearch

Search for products using an image ID returned by uploadImage().

const imageSearch = sdk.imageSearch({
  imageId: 'uploaded-image-id',
  pagination: { page: 1, limit: 24 },
})

const { data, error } = await imageSearch.get()

if (error) {
  console.error('Image search failed:', error.message)
} else if (data) {
  console.log(data.products)
}

You can also pass imageData (a base64 string or Blob) and the SDK uploads it for each get() call.

uploadImage

Upload an image for visual search. The controller is uncached; each get() call uploads the image again. Uploads are rate limited, so reuse the returned imageId in imageSearch() instead of re-uploading the same image.

const uploader = sdk.uploadImage({ image: fileInput.files[0] })

const { data, error } = await uploader.get()

if (error) {
  console.error('Image upload failed:', error.message)
} else if (data) {
  console.log(data.status, data.imageId)
}

similarProducts

Fetch products similar to a given product.

const similar = sdk.similarProducts({
  searchProductId: 123456,
  pagination: { page: 1, limit: 12 },
})

const { data, error } = await similar.get()

if (error) {
  console.error('Similar products failed:', error.message)
} else if (data) {
  console.log(data.products)
}

blocks

Fetch product recommendations from a Layers block.

const blocks = sdk.blocks({
  blockId: 'your-block-id',
  anchorId: 'your-collection-handle',
  pagination: { page: 1, limit: 12 },
})

const { data, error } = await blocks.get()

if (error) {
  console.error('Blocks fetch failed:', error.message)
} else if (data) {
  console.log(data.products, data.block)
}

anchorId is required for product and collection anchored blocks and omitted otherwise. Fetch facet counts for a collection at runtime. sdk.facets() replaces the facets array that was configured at SDK init in v2.

const facets = sdk.facets({ collectionHandle: 'shirts' })

const { data, error } = await facets.get()

if (error) {
  console.error('Facet fetch failed:', error.message)
} else if (data) {
  console.log(data.facets, data.facetRanges)
}

sortOrders

Fetch available sort orders at runtime.

const sortOrders = sdk.sortOrders()

const { data, error } = await sortOrders.get()

if (error) {
  console.error('Sort orders fetch failed:', error.message)
} else if (data) {
  console.log(data.sortOrders)
}

searchFeedback

Send feedback about search results. searchFeedback() is a direct, non-controller call.

const { data, error } = await sdk.searchFeedback({
  searchId: 'search-execution-id',
  rating: 'positive',
  productFeedback: [
    {
      productId: 123456,
      rating: 'positive',
    },
  ],
})

if (error) {
  console.error('Search feedback failed:', error.message)
}

trackingEvent

Send a custom analytics event. trackingEvent() is a direct, non-controller call.

import type { TrackingEventInput } from '@commerce-blocks/sdk'

const event: TrackingEventInput = {
  eventType: 'product_click',
  productId: 123456,
  position: 1,
}

const { data, error } = await sdk.trackingEvent(event)

if (error) {
  console.error('Tracking event failed:', error.message)
}

Allowed eventType values are collection_view, product_click, product_view, product_impression, product_hover, product_touch, add_to_cart, search, autocomplete, and block_view. TrackingEventInput also permits eventId, timestamp, sessionId, deviceId, attributionToken, variantId, collectionHandle, blockId, searchId, query, and position.

Subscribing to controller state

Use subscribe or the controller’s subscribe method to react to state changes.

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

const unsubscribe = subscribe(collection, ({ data, error, loading }) => {
  if (loading) {
    showLoading()
    return
  }
  if (error) {
    showError('There was an error loading products.')
    return
  }
  if (data) {
    renderProducts(data.products)
  }
})

// Later
unsubscribe()

Disposing controllers

Call dispose() when a controller is no longer needed to clear subscriptions and reset its state. Pending results cannot update the disposed state, but their network requests continue and their promises still resolve. Disposing a controller does not clear the SDK’s shared response cache:

collection.dispose()

Deprecated v2 methods

v2	v3	Notes
`createClient()`	`createSDK()`	Returns `{ data, error }`
`getClient()`	`getSDK()`	Same singleton behavior
`client.collection({ handle })`	`sdk.collection({ collectionHandle })`	Param renamed
`client.blocks({ anchor })`	`sdk.blocks({ anchorId })`	Param renamed
`client.suggest()`	`sdk.autocomplete()`	Use `autocomplete()`; `suggest()` is deprecated
`client.searchByImage()`	`sdk.imageSearch()`	Method renamed
`controller.execute()`	`controller.get()`	`execute()` is deprecated
`controller.getState()`	`controller.state`	`getState()` is deprecated
`state.value`	`state`	`state` is now a plain getter
`state.isFetching`	`state.loading`	`isFetching` is deprecated

searchFeedback() and trackingEvent() are new in v3 and have no v2 equivalent. See Upgrade to v3 for a complete migration guide.

Overview

SDK Reference

SDK Guides

Changelog & Upgrades

AI Enablement

Client methods

SDK instance creation

collection

Dynamic linking

search

searchContent

autocomplete

suggest (deprecated)

imageSearch

uploadImage

similarProducts

blocks

facets

sortOrders

searchFeedback

trackingEvent

Subscribing to controller state

Disposing controllers

Deprecated v2 methods

​SDK instance creation

​collection

​Dynamic linking

​search

​searchContent

​autocomplete

​suggest (deprecated)

​imageSearch

​uploadImage

​similarProducts

​blocks

​facets

​sortOrders

​searchFeedback

​trackingEvent

​Subscribing to controller state

​Disposing controllers

​Deprecated v2 methods

SDK instance creation

collection

Dynamic linking

search

searchContent

autocomplete

suggest (deprecated)

imageSearch

uploadImage

similarProducts

blocks

facets

sortOrders

searchFeedback

trackingEvent

Subscribing to controller state

Disposing controllers

Deprecated v2 methods