Response types and error handling

Controller state

All controllers expose reactive state through a plain state getter:

interface QueryState<T> {
  data: T | null
  error: Error | null
  loading: boolean
  /** @deprecated Use `loading` instead */
  isFetching: boolean
}

Read controller.state synchronously or subscribe to changes with controller.subscribe(callback) or the standalone subscribe(controller, callback) utility.

Query result

Collection, search, blocks, image search, similar products, and facets controllers all return a paginated QueryResult shape in data:

interface QueryResult<T> {
  products: T[]
  totalResults: number
  totalPages: number
  page: number
  facets?: Record<string, Record<string, number>>
  facetRanges?: Record<string, { min: number; max: number }>
  attributionToken: string
}

Blocks result

Blocks results extend QueryResult with block metadata:

interface BlocksResult extends QueryResult<Product> {
  block: {
    id: string
    title: string
    anchor_type: 'product' | 'collection' | 'cart' | 'none'
    strategy_type: string
    strategy_key: string
  }
}

Autocomplete result

The autocomplete controller returns a different shape:

interface AutocompleteResponse {
  matchedQueries: Array<{ query_text: string; num_searches: number }>
  originalQuery: string
  normalizedQuery: string
  _meta?: {
    redirect?: { url: string }
  }
}

Sort orders result

interface SortOrder {
  code: string
  nickname: string
}

interface SortOrdersResponse {
  sortOrders: SortOrder[]
}

interface FacetsResponse extends QueryResult<unknown> {
  facets?: Record<string, Record<string, number>>
  facetRanges?: Record<string, { min: number; max: number }>
}

Content search result

The searchContent controller returns articles:

interface SearchContentResult {
  articles: Article[]
  query: string
  contentType: string | null
  totalResults: number
  page: number
  resultsPerPage: number
}

interface Article {
  title: string
  handle: string
  summary: string
  author: string | null
  tags: string[]
  image: ArticleImage | null
  publishedAt: string
}

interface ArticleImage {
  url: string
  width: number
  height: number
  altText: string
}

Product types

Product

The Product type represents a fully built product returned by the SDK. It extends ProductBase and can be further extended via the transforms.product configuration.

type Product = ProductBase & Record<string, unknown>

interface ProductBase {
  // Identifiers
  id: CommerceBlocksID
  gid: ProductGID
  numericId: number

  // Core
  title: string
  handle: string
  vendor: string
  type: string
  availableForSale: boolean
  tags: string[]

  // Media
  images: Image[]
  featuredMedia: FeaturedMedia | null

  // Pricing
  price: Price
  compareAtPrice: Price | null
  priceRange: PriceRange | null

  // Options and variants
  options: RichProductOption[]
  selectedOptions: ProductOption[]
  variants: ProductVariant[]
  selectedVariant: ProductVariant | null

  // Metadata
  metafields: Record<string, unknown>
  calculated: Record<string, unknown>

  // Taxonomy
  category: ProductCategory | null

  // Combined listings
  combinedListingParentProductId: number | null
  combinedListingRole: string | null

  // Breakout
  breakoutOptions: ProductOption[]
  breakoutVariantId: number | null
}

CommerceBlocksID is a string in the format layers-{numericId}. ProductGID is a Shopify Global ID string like gid://shopify/Product/123.

ProductVariant

interface ProductVariant {
  id: CommerceBlocksID
  gid: VariantGID
  numericId: number
  title: string
  sku: string | null
  position: number
  availableForSale: boolean
  price: Price
  compareAtPrice: Price | null
  image: Image | null
  selectedOptions: ProductOption[]
  inventoryLevels: Record<string, number>
  inventoryPolicy: 'DENY' | 'CONTINUE' | null
  inStockLocationIds: number[]
  requiresSellingPlan: boolean
  hasSellingPlan: boolean
}

VariantGID is a Shopify Global ID string like gid://shopify/ProductVariant/456.

Price and PriceRange

interface Price {
  amount: number
  currencyCode: string
  formatted: string
}

interface PriceRange {
  min: Price
  max: Price
}

The formatted value is generated by the SDK using the formatPrice function you provide at SDK init, or a default formatter based on Intl.NumberFormat.

Image and FeaturedMedia

interface Image {
  url: string
  alt: string
  width: number
  height: number
  position: number
  variantIds: number[]
}

interface FeaturedMedia {
  mediaContentType: string | null
  url: string
  alt: string
  width: number
  height: number
}

Options

interface ProductOption {
  name: string
  value: string
}

interface RichProductOption extends ProductOption {
  code: string
  swatch?: Swatch
}

RichProductOption is used for the product’s top-level options array. It includes the attribute code (the internal Layers identifier) and an optional swatch with color or image data if defined for that option.

ProductCategory

interface ProductCategory {
  id: string
  name: string
  fullName: string
  isLeaf: boolean
  isRoot: boolean
}

Error handling

All SDK methods and controllers return { data, error } instead of throwing. Errors are plain Error instances or ApiError instances for HTTP failures.

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

const result = await collection.get()

if (result.error) {
  if (result.error instanceof ApiError) {
    console.error('HTTP error:', result.error.status, result.error.message)
    console.error('Response body:', result.error.body)
  } else {
    console.error('SDK error:', result.error.message)
  }
}

ApiError

Raised when the Layers API returns a non-2xx response.

Field	Type	Description
`status`	`number`	HTTP status code
`statusText`	`string`	HTTP status text
`message`	`string`	Human-readable description
`body`	`unknown`	Parsed JSON error body, raw text, or `undefined`

A 401 usually means the storefrontAccessToken is missing or invalid. Messages like "The selected sort order code is invalid." or "The selected facet is invalid." mean a sort or filterGroup references an attribute that is not configured in Layers. See Troubleshooting for fixes.

ConfigError

Raised during createSDK() when the SDK is misconfigured or used in an unsupported environment (for example, fetch or localStorage is missing and no custom implementation was provided).

Other errors

Network failures, timeouts, aborted requests, and unexpected thrown values are normalized to Error instances. The original cause is preserved on error.cause when available.

Error handling with reactive state

Handle errors reactively using the controller’s subscribe method. This approach works with any framework:

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

collection.subscribe(({ data, error, loading }) => {
  if (loading) {
    showLoading()
    return
  }

  if (error) {
    showError('Something went wrong. Please try again.')
    return
  }

  if (!data || data.products.length === 0) {
    showEmpty('No products found.')
    return
  }

  renderProducts(data.products)
})

await collection.get()

Exported types

The SDK exports all types from @commerce-blocks/sdk:

import type {
  // SDK
  SdkConfig,
  Transforms,
  CreateSDKResult,

  // Controllers
  Controller,
  QueryState,
  Unsubscribe,

  // Product-bearing responses
  CollectionData,
  SearchData,
  BlocksData,
  ImageSearchData,
  SimilarProductsData,

  // API params
  CollectionParams,
  SearchParams,
  SearchBaseParams,
  BlocksParams,
  ImageSearchParams,
  SimilarProductsParams,
  SearchContentParams,
  SearchFeedbackParams,
  UploadImageParams,
  AutocompleteParams,
  FacetsParams,

  // Context
  Context,
  GeoContext,
  MarketingContext,
  CustomerContext,
  CartProduct,
  PriorSearch,

  // Product card
  ProductCardController,
  ProductCardOptions,
  ProductCardState,
  OptionGroup,
  OptionValue,
  OptionStatus,
  PriceData,
  PriceRangeData,

  // Product
  Product,
  ProductBase,
  ProductVariant,
  Image,
  FeaturedMedia,
  Price,
  PriceRange,
  ProductOption,
  RichProductOption,
  Swatch,
  ProductCategory,

  // Filters
  FilterGroup,
  FilterExpression,

  // Storage
  StorageBackend,

  // Errors
  ApiError,
  SdkError,
  ConfigError,
} from '@commerce-blocks/sdk'

Overview

SDK Reference

SDK Guides

Changelog & Upgrades

AI Enablement

Response types and error handling

Controller state

Query result

Blocks result

Autocomplete result

Sort orders result

Facets result

Content search result

Product types

Product

ProductVariant

Price and PriceRange

Image and FeaturedMedia

Options

ProductCategory

Error handling

ApiError

ConfigError

Other errors

Error handling with reactive state

Exported types

Next steps

​Controller state

​Query result

​Blocks result

​Autocomplete result

​Sort orders result

​Facets result

​Content search result

​Product types

​Product

​ProductVariant

​Price and PriceRange

​Image and FeaturedMedia

​Options

​ProductCategory

​Error handling

​ApiError

​ConfigError

​Other errors

​Error handling with reactive state

​Exported types

​Next steps

Controller state

Query result

Blocks result

Autocomplete result

Sort orders result

Facets result

Content search result

Product types

Product

ProductVariant

Price and PriceRange

Image and FeaturedMedia

Options

ProductCategory

Error handling

ApiError

ConfigError

Other errors

Error handling with reactive state

Exported types

Next steps