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

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, resultsPerPage: 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, resultsPerPage: 24 },
})

Full params for sdk.collection():

Param	Type	Description
`collectionHandle`	`string`	Collection handle (required)
`sort`	`string`	Sort order code
`pagination`	`{ page?: number; resultsPerPage?: number }`	Pagination
`filterGroup`	`FilterGroup`	Filter group from the filter DSL
`dynamicLinking`	`boolean`	Enable dynamic linking
`context`	`Context`	Session context
`attributes`	`string[]`	Additional product attributes to request
`transformBody`	`function`	Mutate the request body before sending

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, resultsPerPage: 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.redirect)
}

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, resultsPerPage: 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 will upload it automatically for each get() call.

uploadImage

Upload an image for visual search. The controller is uncached; each get() call uploads the image again.

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.imageId, data.url)
}

similarProducts

Fetch products similar to a given product.

const similar = sdk.similarProducts({
  searchProductId: 123456,
  pagination: { page: 1, resultsPerPage: 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({
  anchorId: 'homepage-featured',
  pagination: { page: 1, resultsPerPage: 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)
}

You can also fetch by blockId instead of anchorId. Fetch facet counts for a collection at runtime. This 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. This is a direct, non-controller call.

const { data, error } = await sdk.searchFeedback({
  searchId: 'search-execution-id',
  searchToken: 'search-token',
  productFeedback: [
    {
      productId: 'layers-123456',
      clicked: true,
      position: 1,
    },
  ],
})

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

trackingEvent

Send a custom analytics event. This is a direct, non-controller call.

const { data, error } = await sdk.trackingEvent({
  name: 'product_click',
  properties: {
    productId: 'layers-123456',
    position: 1,
  },
})

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

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 stop subscriptions, abort in-flight requests, and clean up cached references:

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
`client.searchFeedback`	`sdk.searchFeedback`	Now a direct call
`client.trackingEvent`	`sdk.trackingEvent`	Now a direct call
`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

See Upgrade to v3 for a complete migration guide.

Overview

SDK Reference

SDK Guides

Changelog & Upgrades

AI Enablement

Client methods

SDK instance creation

collection

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

​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

search

searchContent

autocomplete

suggest (deprecated)

imageSearch

uploadImage

similarProducts

blocks

facets

sortOrders

searchFeedback

trackingEvent

Subscribing to controller state

Disposing controllers

Deprecated v2 methods