Search patterns

Prepare and get flow

In v3 the search controller handles prepare and execute automatically. When you call get(), the controller prepares the query if needed and retries a 425 response until results are ready.

const search = sdk.search({ query: 'ring' })

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

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

For advanced use cases, you can call prepare() directly to cache expensive work before calling get().

const search = sdk.search({ query: 'ring' })

const { error: prepareError } = await search.prepare()
if (prepareError) {
  console.error('Prepare failed:', prepareError.message)
}

// Later, perhaps after the shopper adjusts filters
const { data, error } = await search.get({
  filterGroup: filter(eq('your-attribute', 'your-value')),
})

Reusing a prepared search across pages

Configure storage when you want the results page to reuse a prepared search ID. The SDK stores the prepared ID by the canonical query and request parameters, then resolves it automatically on the next page.

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

if (sdkError) {
  console.error('SDK init failed:', sdkError.message)
} else {
  const search = sdk.search({ query: 'ring' })
  const { error: prepareError } = await search.prepare()

  if (prepareError) {
    console.error('Prepare failed:', prepareError.message)
  } else {
    window.location.href = '/search?q=ring'
  }
}

Await prepare() before navigating so the search_id is written to storage. If navigation happens first, the request is likely cancelled and the results page prepares again, which is correct but slower. On the results page, create sdk.search({ query }) with the same request parameters and call get(). Do not read a search ID from the URL or pass one to get().

const search = sdk.search({ query: 'ring' })
const { data, error } = await search.get()

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

Debouncing autocomplete

For search-as-you-type, use autocomplete() and debounce the input in your framework or with createDebounce() from the SDK.

import { createSDK, createDebounce } 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)
} else {
  const autocomplete = sdk.autocomplete()
  let controller

  const { call: debouncedSearch } = createDebounce(async (query) => {
    if (controller) controller.dispose()
    controller = sdk.autocomplete()

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

    if (error) {
      console.error('Autocomplete failed:', error.message)
    } else if (data) {
      renderSuggestions(data.matchedQueries)
    }
  }, 150)

  input.addEventListener('input', (event) => {
    debouncedSearch(event.target.value)
  })
}

The deprecated suggest() method also debounces, but new integrations should use autocomplete() with their own debounce logic.

Concurrent API calls

Call search.prepare() and autocomplete.get() concurrently for a fast search-as-you-type experience.

const search = sdk.search({ query: 'ring' })
const autocomplete = sdk.autocomplete()

const [prepareResult, autocompleteResult] = await Promise.all([
  search.prepare(),
  autocomplete.get({ query: 'ring' }),
])

if (autocompleteResult.data) {
  renderSuggestions(autocompleteResult.data.matchedQueries)
}

const { data, error } = await search.get()
if (error) {
  console.error('Search failed:', error.message)
} else if (data) {
  renderProducts(data.products)
}

Aborting stale requests

Controllers are tied to a single request lifecycle. To abort a previous request (for example, when the shopper types a new character), dispose the old controller and create a new one.

let autocompleteController

input.addEventListener('input', (event) => {
  if (autocompleteController) {
    autocompleteController.dispose()
  }

  autocompleteController = sdk.autocomplete()
  autocompleteController.get({ query: event.target.value }).then(({ data, error }) => {
    if (error) {
      console.error('Autocomplete failed:', error.message)
    } else if (data) {
      renderSuggestions(data.matchedQueries)
    }
  })
})

Overview

SDK Reference

SDK Guides

Changelog & Upgrades

AI Enablement

Search patterns

Prepare and get flow

Reusing a prepared search across pages

Debouncing autocomplete

Concurrent API calls

Aborting stale requests

Next steps

Caching

Performance

​Prepare and get flow

​Reusing a prepared search across pages

​Debouncing autocomplete

​Concurrent API calls

​Aborting stale requests

​Next steps

Caching

Performance

Prepare and get flow

Reusing a prepared search across pages

Debouncing autocomplete

Concurrent API calls

Aborting stale requests

Next steps