Installation

npm install @commerce-blocks/sdk

Loading from a CDN

The SDK ships as a pure ES module with no Node-only dependencies, so it works in the browser with no build step. Use this when you’re integrating directly into a Shopify theme, a static HTML page, or any environment where you don’t run npm install.

unpkg (recommended)

unpkg serves the published npm package directly. Add the ?module query string and unpkg rewrites the SDK’s imports into sibling unpkg URLs, so the browser resolves the entire module graph without a bundler.

<script type="module">
  import { createSDK } from 'https://unpkg.com/@commerce-blocks/sdk?module'

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

  if (error) {
    console.error('Layers init failed:', error.message)
  } else {
    window.layers = sdk
  }
</script>

Pin the version explicitly in production so a new release never silently changes behavior on your storefront. unpkg accepts a major (@3), minor (@3.0), or exact (@3.0.0) tag - for example, https://unpkg.com/@commerce-blocks/sdk@3?module. See the SDK changelog for the latest version.

esm.sh

esm.sh is an alternative ESM CDN that pre-bundles the SDK and its dependencies into a single file.

<script type="module">
  import { createSDK } from 'https://esm.sh/@commerce-blocks/sdk@3'
</script>

jsDelivr

jsDelivr mirrors npm with its own ESM transform. Use the +esm suffix to get a browser-compatible bundle.

<script type="module">
  import { createSDK } from 'https://cdn.jsdelivr.net/npm/@commerce-blocks/sdk@3/+esm'
</script>

Import maps

If you load multiple modules from a CDN and want to keep imports short, declare an import map once and use bare specifiers everywhere else:

<script type="importmap">
{
  "imports": {
    "@commerce-blocks/sdk": "https://unpkg.com/@commerce-blocks/sdk@3?module"
  }
}
</script>

<script type="module">
  import { createSDK, getSDK } from '@commerce-blocks/sdk'
  // ...
</script>

Reusing the SDK across modules

createSDK registers the SDK in a singleton, so any later <script type="module"> block can pull it back with getSDK. This is the cleanest pattern for theme integrations where one snippet boots the SDK and many other sections consume it.

<!-- Boot once in theme.liquid -->
<script type="module">
  import { createSDK } from 'https://unpkg.com/@commerce-blocks/sdk@3?module'

  const { error } = createSDK({
    storefrontAccessToken: '{{ shop.metafields.layers.embed_settings.value.storefrontApiToken }}',
    trackingToken: '{{ shop.metafields.layers.embed_settings.value.trackingToken }}',
    currencyCode: 'USD',
  })

  if (error) {
    console.error('SDK init failed:', error.message)
  }
</script>

<!-- Consume anywhere -->
<script type="module">
  import { getSDK } from 'https://unpkg.com/@commerce-blocks/sdk@3?module'

  const { data: sdk, error } = getSDK()
  if (error) {
    console.error('SDK not initialized:', error.message)
  } else {
    const collection = sdk.collection({ collectionHandle: 'shirts' })
    await collection.get()
  }
</script>

When pulling the SDK from a CDN, also add <link rel="modulepreload" href="https://unpkg.com/@commerce-blocks/sdk@3?module" /> to your <head>. The browser then starts fetching the module during HTML parse instead of waiting for the first <script type="module"> to execute.

Configuration

Required configuration

Option	Type	Required	Description
`storefrontAccessToken`	`string`	Yes	Layers API public storefront token
`trackingToken`	`string`	Yes	Layers tracking token used for analytics events

Optional configuration

Option	Type	Description
`baseUrl`	`string`	Custom API URL
`fetch`	`FetchFn`	Custom fetch implementation (SSR, testing)
`headers`	`Record<string, string>`	Additional headers sent with every request
`attributes`	`string[]`	Product attributes to fetch
`currencyCode`	`string`	Currency for price formatting
`formatPrice`	`(amount: number, currencyCode: string) => string`	Custom price formatter
`swatches`	`Swatch[]`	Color and image swatch definitions
`context`	`Context`	Default market and shopper context applied to every controller (see Context)
`cache`	`{ ttl?: number; maxSize?: number }`	In-memory cache TTL (ms) and max entries
`storage`	`StorageBackend`	Custom storage backend for cache persistence (defaults to `localStorage` in the browser)
`transforms`	`Transforms`	Post-process response data before it is cached and returned

Context

Pass market and shopper context to personalize results across all controllers. Set it globally on the SDK config, per-query on get(), or both. Per-query context shallow-merges with and overrides the global context.

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

const { data: sdk, error } = createSDK({
  storefrontAccessToken: 'your-storefront-token',
  trackingToken: 'your-tracking-token',
  context: {
    market: 'US',
    geo: { country: 'US' },
    shoppingChannel: 'web',
  },
})

if (error) {
  console.error('SDK init failed:', error.message)
} else {
  // Per-query override - merges with global context
  const collection = sdk.collection({ collectionHandle: 'shirts' })
  const { error: queryError } = await collection.get({
    context: { geo: { country: 'CA', province: 'ON' } },
  })
  // Effective context: { market: 'US', geo: { country: 'CA', province: 'ON' }, shoppingChannel: 'web' }
}

Context fields:

Field	Type	Description
`geo`	`GeoContext`	Geographic location: `{ country, province, city }`
`market`	`string`	Market identifier
`productsInCart`	`CartProduct[]`	Products currently in the shopper’s cart
`productsPurchased`	`CartProduct[]`	Previously purchased products
`priorSearches`	`PriorSearch[]`	Recent searches: `{ searchQuery, hadClick, hasResults }`
`marketing`	`MarketingContext`	UTM-style attribution: `{ source, medium, campaign, term }`
`customer`	`CustomerContext`	Customer profile: `{ signedIn, returning, numberOfOrders, ... }`
`shoppingChannel`	`'web' \| 'app'`	Shopping channel the request originates from
`custom`	`Record<string, unknown>`	Custom key-value pairs forwarded to merchandising strategies

CartProduct:

Property	Type	Required	Description
`title`	`string`	Yes	Product title
`price`	`number`	No	Unit price
`type`	`string`	No	Product type
`productId`	`string`	No	Product ID
`variantId`	`string`	No	Variant ID
`quantity`	`number`	No	Quantity in cart
`options`	`Record<string, string>`	No	Selected options (for example, `{ Size: 'L' }`)

CustomerContext:

Property	Type	Description
`signedIn`	`boolean`	Whether the shopper is signed in
`returning`	`boolean`	Whether the shopper has visited before
`numberOfOrders`	`number`	Lifetime order count
`averageOrderValue`	`number`	Average order value
`daysBetweenOrders`	`number`	Average days between orders
`daysSinceLastOrder`	`number`	Days since the most recent order
`daysSinceOldestOrder`	`number`	Days since the first order
`totalSpent`	`number`	Lifetime spend

Use the global context for values that rarely change within a session (market, channel, customer profile). Use per-query context for values that vary by page or interaction (current cart, geo override).

Swatch configuration

Use swatches to map option values to colors or images. Swatches are matched by option name and value.

Option	Type	Description
`swatches`	`Swatch[]`	Color and image swatch definitions

Swatch:

Property	Type	Required	Description
`name`	`string`	Yes	Option name this swatch belongs to (for example, `Color`)
`value`	`string`	Yes	Option value to match (for example, `Red`)
`color`	`string \| null`	Yes	CSS color value (for example, `#ff0000`)
`imageUrl`	`string \| null`	Yes	URL to a swatch image. Use when a color alone is not sufficient.

Transforms

Transforms post-process response data before it is cached and returned.

Option	Type	Description
`transforms.product`	`({ base, raw }) => object`	Extend products with custom fields
`transforms.collection`	`(data: CollectionData) => CollectionData`	Transform collection results
`transforms.search`	`(data: SearchData) => SearchData`	Transform search results
`transforms.blocks`	`(data: BlocksData) => BlocksData`	Transform block results
`transforms.searchContent`	`(data: SearchContentResult) => SearchContentResult`	Transform content search results
`transforms.autocomplete`	`(data: AutocompleteResponse) => AutocompleteResponse`	Transform autocomplete results
`transforms.facets`	`(data: FacetsResponse) => FacetsResponse`	Transform facet results
`transforms.sortOrders`	`(data: SortOrdersResponse) => SortOrdersResponse`	Transform sort order results
`transforms.similarProducts`	`(data: SimilarProductsData) => SimilarProductsData`	Transform similar product results
`transforms.imageSearch`	`(data: ImageSearchData) => ImageSearchData`	Transform image search results

Once configured, transforms are applied automatically:

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

const { data: sdk, error } = createSDK({
  storefrontAccessToken: 'your-storefront-token',
  trackingToken: 'your-tracking-token',
  attributes: ['your-attribute'],
  transforms: {
    product: ({ raw }) => ({
      description: raw['your-attribute'] ?? '',
    }),
  },
})

if (error) {
  console.error('SDK init failed:', error.message)
} else {
  const collection = sdk.collection({ collectionHandle: 'shirts' })
  const { data, error: queryError } = await collection.get()
  // Products now include `description` from the product transform
}

Cache configuration

Option	Type	Description
`cache.ttl`	`number`	In-memory cache TTL in milliseconds
`cache.maxSize`	`number`	Max entries in the in-memory cache
`storage`	`StorageBackend`	Storage backend for cache persistence (defaults to `localStorage` in the browser)

The SDK uses an in-memory LRU cache with TTL eviction. In the browser, it persists cache values to localStorage automatically when a storage backend is available and supported. Pass a custom storage backend if you need a different store shape or prefix.

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

const { data: sdk, error } = createSDK({
  storefrontAccessToken: 'your-storefront-token',
  trackingToken: 'your-tracking-token',
  cache: { ttl: 60000, maxSize: 100 },
  storage: localStorage,
})

Singleton access

After initialization, access the SDK anywhere:

import { getSDK, isInitialized, resetSDK } from '@commerce-blocks/sdk'

if (isInitialized()) {
  const { data: sdk, error } = getSDK()
  if (error) {
    console.error('SDK not initialized:', error.message)
  } else if (sdk) {
    // Use sdk
  }
}

// To reset the singleton state and clear the current SDK instance:
resetSDK()

Important notes

All SDK methods return an ApiResult type ({ data, error }) instead of throwing exceptions. Always check for error before accessing data.

Troubleshooting

`401 Unauthorized` on the first request

If the first get() returns an ApiError with status 401 (for example, POST /api/storefront/v1/browse/frontpage 401), the storefrontAccessToken passed to createSDK() is missing, invalid, or expired. On Shopify, the storefront token is read from the shop metafield shop.metafields.layers.embed_settings.value.storefrontApiToken. If that metafield is empty or absent in your theme:

Confirm the Layers app is installed and connected in Shopify admin.
Trigger a resync from Settings → Integrations in the Layers dashboard so the metafield is written to the shop. See Collection & app metafields.
Re-render the theme and confirm the metafield now returns a non-empty value.

If the metafield is still not populated after a resync, contact Layers support.

`"The selected sort order code is invalid."`

The sort you passed to get() does not match a sort order configured in Layers for the current collection, or the sort order no longer exists in the Layers dashboard.

Fetch available sort orders at runtime with sdk.sortOrders({ collectionHandle: 'shirts' }).
Use a code from the returned sort orders when calling collection.get() or creating a collection controller with sort.
Omit sort from get() to fall back to the collection’s default sort order.

A filterGroup you passed references an attribute that is not configured as a facet in Layers.

Fetch available facets at runtime with sdk.facets({ collectionHandle: 'shirts' }).
Attribute codes are case-sensitive and must exactly match the attribute code shown in the Layers dashboard (for example, your-attribute, not Your-Attribute).
Remove filters that reference attributes no longer configured as facets.

Overview

SDK Reference

SDK Guides

Changelog & Upgrades

AI Enablement

Installation

Installation

Loading from a CDN

unpkg (recommended)

esm.sh

jsDelivr

Import maps

Reusing the SDK across modules

Configuration

Required configuration

Optional configuration

Context

Swatch configuration

Transforms

Cache configuration

Singleton access

Important notes

Troubleshooting

`401 Unauthorized` on the first request

`"The selected sort order code is invalid."`

`"The selected facet is invalid."`

​Installation

​Loading from a CDN

​unpkg (recommended)

​esm.sh

​jsDelivr

​Import maps

​Reusing the SDK across modules

​Configuration

​Required configuration

​Optional configuration

​Context

​Swatch configuration

​Transforms

​Cache configuration

​Singleton access

​Important notes

​Troubleshooting

​401 Unauthorized on the first request

​"The selected sort order code is invalid."

​"The selected facet is invalid."

Installation

Loading from a CDN

unpkg (recommended)

esm.sh

jsDelivr

Import maps

Reusing the SDK across modules

Configuration

Required configuration

Optional configuration

Context

Swatch configuration

Transforms

Cache configuration

Singleton access

Important notes

Troubleshooting

`401 Unauthorized` on the first request

`"The selected sort order code is invalid."`

`"The selected facet is invalid."`