Installation

This page documents @commerce-blocks/sdk v3 (3.x). For v2 integrations, see Upgrade to v3.

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. Use this 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'

  // The tag has id="layers-config", type="application/json", and contains both token fields.
  const configEl = document.getElementById('layers-config')
  if (!configEl) throw new Error('Layers config tag not found — is the app embed enabled?')
  const layersConfig = JSON.parse(configEl.textContent)

  const { error } = createSDK({
    storefrontAccessToken: layersConfig.storefrontApiToken,
    trackingToken: layersConfig.apiToken,
    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>

The token sources map to createSDK() options as follows:

`createSDK()` option	Primary source	Alternative Liquid source
`storefrontAccessToken`	`storefrontApiToken` in the `#layers-config` JSON tag emitted by the app embed	`shop.metafields.commerce_blocks.layers_token`
`trackingToken`	`apiToken` in the `#layers-config` JSON tag	`shop.metafields.commerce_blocks.layers_tracking_token`

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 storefront token (listed as Storefront Token on the API Access page in the Layers dashboard)
`trackingToken`	`string`	Yes	Layers analytics tracking token, used for analytics events (listed as Analytics Tracking Token on the API Access page)

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
`identity`	`IdentitySource`	Shared shopper identity applied to every request: a static `Identity` object or a `() => Identity` resolver read live per call (see Identity)
`currencyCode`	`string`	Currency for price formatting
`formatPrice`	`(amount: number, currencyCode: string) => string`	Custom price formatter
`swatches`	`Swatch[]`	Color and image swatch definitions
`cache`	`{ ttl?: number; maxSize?: number }`	In-memory cache TTL (ms) and max entries
`storage`	`StorageBackend`	Storage backend for prepared search ID persistence
`transforms`	`Transforms`	Post-process response data before it is cached and returned

Identity

Using the Layers app embed? Leave identity unset. On a Shopify theme with the app embed enabled, the Storefront Pixel adds the device, session, and customer identifiers to every Layers request the page makes, including the SDK’s. It only fills identity when the request doesn’t already carry one, so an identity you pass replaces the pixel’s values instead of adding to them. Don’t read the pixel’s cookies and pass them back in. The example below is for headless and custom storefronts that don’t load the app embed.

identity carries the device, session, and customer identifiers attached to every request and tracking event. Pass a static Identity object or a () => Identity resolver. A resolver is read live per call, so a login or session rotation is picked up automatically. Per-call identity overrides the config fields.

// Headless or custom storefront only (no Layers app embed).
import { createSDK } from '@commerce-blocks/sdk'

const { data: sdk, error } = createSDK({
  storefrontAccessToken: 'your-storefront-token',
  trackingToken: 'your-tracking-token',
  identity: () => ({
    deviceId: getDeviceId(),
    sessionId: getSessionId(),
    customerId: getCustomerId(),
  }),
})

if (error) {
  console.error('SDK init failed:', error.message)
}

Context

Using the Layers app embed? Don’t hand-build context. With the app embed enabled, the Storefront Pixel wraps fetch and fills context on every Layers request: market, locale, and currency from Shopify, productsInCart and productsPurchased, the customer profile, B2B company location, and marketing (UTM parameters and click IDs). Layers fills geo from the shopper’s location on the server. The request’s own context wins field by field, so a hand-built market, geo, or productsInCart replaces the embed’s value and can disagree with it (for example, a cart snapshot that goes stale after an add to cart).Fields a theme still sends itself, because the embed doesn’t:

freeShippingThreshold, in store currency (not cents), for free-shipping blocks.
custom keys your merchandising rules target. The pixel merges your custom keys with the ones it captures instead of replacing them.
priorSearches, only if you use search-anchored blocks.
shoppingChannel: 'app' from a mobile app webview that Layers doesn’t detect on its own. Requests default to web.

The full example below is for headless and custom storefronts that don’t load the app embed.

Pass market and shopper context on each request to personalize results. Context is a per-request parameter: set it when you create the controller, pass it to get(), or both. get() options merge with the controller’s initial params at the top level, so a context passed to get() replaces the controller’s context value entirely.

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)
} else {
  const collection = sdk.collection({
    collectionHandle: 'shirts',
    context: {
      market: 'US',
      geo: { country: 'US' },
      shoppingChannel: 'web',
    },
  })
  // Replace the whole context for one request — market and shoppingChannel
  // must be re-declared since the controller's context is not merged field-by-field.
  const { error: queryError } = await collection.get({
    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
`tags`	`string[]`	Shopify customer tags on the shopper’s profile

Set context on the controller for values that rarely change within a session (market, channel, customer profile). Use per-query context in get() 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',
  transforms: {
    product: ({ raw }) => ({
      description: raw['your-attribute'] ?? '',
    }),
  },
})

if (error) {
  console.error('SDK init failed:', error.message)
} else {
  const collection = sdk.collection({
    collectionHandle: 'shirts',
    attributes: ['your-attribute'],
  })
  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 prepared search ID persistence

The SDK keeps controller responses in an in-memory LRU cache with TTL eviction for the life of the page. storage is optional and persists prepared search IDs for reuse across pages. Pass localStorage, sessionStorage, or a custom storage backend when you need cross-page prepare reuse.

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 delivered by the app embed as a <script id="layers-config" type="application/json"> tag in the theme <head> (backed by the embed_settings metafield). If the tag is missing or its storefrontApiToken is empty:

Confirm the Layers app is installed and the theme app extension is enabled in Online Store → Themes → Customize → App embeds.
Trigger a resync from Settings → Integrations in the Layers dashboard so the metafield is written. See Collection & app metafields.
View the page source and confirm #layers-config now contains a non-empty storefrontApiToken.

If the tag 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

Identity

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

​Identity

​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

Identity

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."`