Response types and error handling

Controller state

All controllers expose reactive state via a ReadonlySignal<QueryState<T>>:

interface QueryState<T> {
  data: T | null
  error: ClientError | null
  isFetching: boolean
}

Query result

Collection, search, blocks, and image search controllers all return the same base QueryResult shape in data:

interface QueryResult {
  products: Product[]
  totalResults: number
  totalPages: number
  page: number
  facets: Record<string, Record<string, number>>
  priceRange?: PriceRange
  attributionToken?: string
}

priceRange requires { name: 'Price', code: 'variants.price' } in your facets configuration. Without it, priceRange will be undefined. facets is a value-count map keyed by facet code (for example, facets['options.color']). If it comes back empty from a controller such as client.collection(), check that:

Each facet you expect is declared in createClient({ facets: [...] }). Facet counts are only returned for codes registered on the client.
Each facet has Enable as Storefront Facet turned on in the Layers dashboard. See Attribute options.
The code value is spelled and cased exactly as it appears in the dashboard (for example, options.color, not Options.Color). An invalid code returns an ApiError: "The selected facets.N is invalid." See SDK troubleshooting.

Blocks result

Blocks results extend QueryResult with block metadata:

interface BlocksResult extends QueryResult {
  block?: BlocksInfo
}

interface BlocksInfo {
  id: string
  label: string
  title: string
  anchor_type: 'product' | 'collection' | 'cart' | 'none'
  strategy_type: 'interaction' | 'collection_interaction' | 'similar_products' | 'manual'
  strategy_key: string
}

Suggestions result

The suggest controller returns a different shape:

interface Suggestions {
  matchedQueries: string[]
  originalQuery: string
  normalizedQuery: string
}

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
  tags: string[]
  image: ArticleImage | null
  publishedAt: string
}

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

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

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

  // Metadata
  metafields: Record<string, 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 client 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
}

On shallow products (the default), featuredMedia is sourced from the matched variant’s featured media. It falls back to the product-level featured media when the variant has none. Account for this fallback in product cards so missing variant media does not appear as a missing image.

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
}

NamedTag

interface NamedTag {
  name: string
  value: string | number | boolean | string[]
}

Error handling

All methods return { data, error } instead of throwing. Errors are discriminated by _tag:

const result = await collection.execute()

if (result.error) {
  switch (result.error._tag) {
    case 'NetworkError':
      break
    case 'ApiError':
      break
    case 'ValidationError':
      break
    case 'ConfigError':
      break
  }
}

Error types

type ClientError = NetworkError | ApiError | ValidationError | ConfigError

NetworkError

Raised when a request fails before receiving a response.

interface NetworkError {
  readonly _tag: 'NetworkError'
  readonly code: NetworkErrorCode
  readonly message: string
  readonly retryAfterMs?: number
  readonly cause?: unknown
}

type NetworkErrorCode =
  | 'TIMEOUT'
  | 'CONNECTION_FAILED'
  | 'DNS_FAILED'
  | 'SSL_ERROR'
  | 'ABORTED'
  | 'OFFLINE'

ApiError

Raised when the Layers API returns an error response.

interface ApiError {
  readonly _tag: 'ApiError'
  readonly code: ApiErrorCode
  readonly source: 'layers'
  readonly message: string
  readonly status?: number
  readonly retryAfterMs?: number
  readonly cause?: unknown
}

type ApiErrorCode =
  | 'UNAUTHORIZED'
  | 'FORBIDDEN'
  | 'NOT_FOUND'
  | 'NOT_READY'
  | 'RATE_LIMITED'
  | 'SERVICE_UNAVAILABLE'
  | 'PARSE_ERROR'
  | 'UNKNOWN'

ValidationError

Raised when pre-request validation fails (for example, a required parameter is missing or out of range).

interface ValidationError {
  readonly _tag: 'ValidationError'
  readonly code: 'VALIDATION_FAILED'
  readonly message: string
  readonly operation: string
  readonly fields: ValidationFieldError[]
  readonly input?: unknown
}

interface ValidationFieldError {
  readonly field: string
  readonly code: 'REQUIRED_FIELD' | 'OUT_OF_RANGE'
  readonly message: string
  readonly value?: unknown
  readonly constraints?: { min?: number; max?: number }
}

ConfigError

Raised during createClient() when the SDK is misconfigured.

interface ConfigError {
  readonly _tag: 'ConfigError'
  readonly code: 'MISSING_CONFIG' | 'INVALID_CONFIG'
  readonly message: string
  readonly field: string
  readonly value?: unknown
  readonly expected?: string
}

Retry helpers

isRetryable classifies errors by tag, code, and status. Use it standalone or as a shouldRetry predicate:

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

if (result.error && isRetryable(result.error)) {
  const delay = result.error.retryAfterMs ?? 1000
  setTimeout(() => collection.execute(), delay)
}

Retryable errors include NetworkError with code TIMEOUT, CONNECTION_FAILED, or DNS_FAILED, and ApiError with code RATE_LIMITED or SERVICE_UNAVAILABLE.

Error type guard

isClientError can be used to check whether an unknown value is one of the SDK error types:

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

try {
  // external code that may throw
} catch (e) {
  if (isClientError(e)) {
    console.error(e._tag, e.message)
  }
}

Exported types

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

import type {
  // Client
  Client,
  ClientConfig,
  CreateClientResult,

  // Controllers
  Controller,
  CollectionController,
  CollectionOptions,
  CollectionQuery,
  CollectionResult,
  SearchController,
  SearchQuery,
  SearchResult,
  SearchPrepareResult,
  SuggestController,
  SuggestOptions,
  BlocksController,
  BlocksOptions,
  BlocksQuery,
  BlocksResult,
  UploadImageController,
  UploadImageOptions,
  UploadImageResult,
  SearchByImageController,
  SearchByImageQuery,
  SearchContentController,
  SearchContentQuery,
  SearchContentResult,
  Article,

  // Context
  Context,
  GeoLocation,
  CartProduct,
  PriorSearch,
  Marketing,
  CustomerContext,

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

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

  // State
  QueryState,
  QueryParams,
  RequestTransformer,
  Unsubscribe,

  // Errors
  ClientError,
  NetworkError,
  ApiError,
  ValidationError,
  ConfigError,

  // Filters
  FilterGroup,
  FilterExpression,

  // Signals
  Signal,
  ReadonlySignal,

  // Storage
  StorageAdapter,
  CacheOptions,

  // Fetch
  CustomFetch,
} from '@commerce-blocks/sdk'

Overview

SDK Reference

SDK Guides

Changelog & Upgrades

AI Enablement

Response types and error handling

Controller state

Query result

Blocks result

Suggestions result

Content search result

Product types

Product

ProductVariant

Price and PriceRange

Image and FeaturedMedia

Options

ProductCategory

NamedTag

Error handling

Error types

NetworkError

ApiError

ValidationError

ConfigError

Retry helpers

Error type guard

Exported types

Next steps

​Controller state

​Query result

​Blocks result

​Suggestions result

​Content search result

​Product types

​Product

​ProductVariant

​Price and PriceRange

​Image and FeaturedMedia

​Options

​ProductCategory

​NamedTag

​Error handling

​Error types

​NetworkError

​ApiError

​ValidationError

​ConfigError

​Retry helpers

​Error type guard

​Exported types

​Next steps

Controller state

Query result

Blocks result

Suggestions result

Content search result

Product types

Product

ProductVariant

Price and PriceRange

Image and FeaturedMedia

Options

ProductCategory

NamedTag

Error handling

Error types

NetworkError

ApiError

ValidationError

ConfigError

Retry helpers

Error type guard

Exported types

Next steps