---
title: Build Headless commerce interfaces with Shopify Liquid
slug: oc2d1158
canonical_url: https://docs.coveo.com/en/oc2d1158/
collection: coveo-for-commerce
source_format: adoc
---
# Build Headless commerce interfaces with Shopify Liquid

If you use a [Shopify Liquid theme](https://shopify.dev/docs/storefronts/themes), we typically recommend using [Coveo Atomic](https://docs.coveo.com/en/oc2d1156#coveo-atomic-with-shopify-liquid).
The Coveo Atomic components are pre-built and let you quickly create product discovery interfaces that are compatible with Shopify Liquid.

However, if you want to create a more customized interface, you can use the [Coveo Headless](https://docs.coveo.com/en/p1oe2163/) library with Shopify Liquid.

We typically [recommend using Headless](https://docs.coveo.com/en/oc2d1156#coveo-headless-with-shopify-hydrogen) with [Shopify Hydrogen](https://hydrogen.shopify.dev/) to create a high-performance, customizable search interface.
However, you can also use it with Shopify Liquid if you have a legitimate reason to use a Liquid theme.
For example, you might already use a React-based component library embedded in your Shopify Liquid theme.
In this case, you can integrate Coveo Headless into that library instead of starting a new project from scratch with Shopify Hydrogen.
This article provides a high-level overview of how to use Coveo Headless with Shopify Liquid.

## Headless commerce usage

> **Important**
>
> When working with Shopify Liquid, initialize your engine using `buildShopifyCommerceEngine` from the Coveo Shopify package, as shown below.
> Avoid the general Headless initialization described in [Headless commerce usage (client-side rendering)](https://docs.coveo.com/en/o6r70022/) to build UI components.
> That method won’t enable Shopify-specific commerce features and can lead to missing functionality or integration issues.

### Install Coveo Shopify

Use [npm](https://docs.npmjs.com/getting-started) to install the Coveo Shopify library.

```bash
npm install @coveo/shopify
```

### Build the commerce engine

> **Tip**
>
> All controllers depend on a single `CommerceEngine` instance.
> This instance is responsible for managing the state across all commerce solutions (such as search, recommendations, listings).

```ts
import { buildShopifyCommerceEngine } from '@coveo/shopify/headless/commerce';

export const getEngine = () => {
  if (_engine !== null) {
    return _engine;
  }

  _engine = buildShopifyCommerceEngine({
    commerceEngineOptions: {
      configuration: {
        accessToken: '<ACCESS_TOKEN>', <1>
        organizationId: '<ORGANIZATION_ID>', <2>
        analytics: {
          enabled: true,
          trackingId: '<TRACKING_ID>' <3>
        },
        context: { <4>
          country:{{ localization.country.iso_code | json }},
          currency: {{ localization.country.currency.iso_code | json }},
          language: {{ request.locale.iso_code | json }},
          view: {
            url: {{ canonical_url | json }}
          },
          cart: {{ cart.items | json }}.map(function (item) {
            return {
              productId: `gid://shopify/ProductVariant/${item.variant_id}`,
              name: item.title,
              price: item.final_price,
              quantity: item.quantity,
            };
          }),
        }
      },
    },
  });

  return _engine;
};
```
<1> An [access token](https://docs.coveo.com/en/o8ld0051/) with the **Search - Execute queries - Allowed** and **Analytics - Analytics data - Push** privileges.
<2> Your [organization ID](https://docs.coveo.com/en/n1ce5273/).
<3> The target [tracking ID](https://docs.coveo.com/en/n8tg0567/).
<4> The `context` object containing the country, currency, view,language, and cart information, extracted from the Shopify store.


### Initialize the web pixel

The [Coveo app web pixel](https://docs.coveo.com/en/oc2d1152#coveo-app-web-pixel) logs cart, product view, and purchase events.

> **Note**
>
> If you're not using the [**Coveo AI Search and Discovery**](https://docs.coveo.com/en/p2la0421/) app and don't have the Coveo app web pixel installed, you'll need to [create your own](https://docs.coveo.com/en/p2la0423/).

To ensure that Headless and the web pixel are synchronized across your entire store, create an initialization snippet and include it in every page of your Shopify store.

. Create a snippet named `initialize-analytics.liquid` and paste the following code:

```html
<!-- snippets/initialize-analytics.liquid -->

<script type="module">
  import {init, fetchAppProxyConfig} from 'https://static.cloud.coveo.com/shopify/v1/headless/commerce.esm.js';

  const config = await fetchAppProxyConfig({ <1>
    marketId: {{ localization.market.id | encode_url_component }},
  });

  init(config); <2>
</script>
```
<1> The Coveo app contains an [App Proxy](https://shopify.dev/docs/api/shopify-app-remix/v2/authenticate/public/app-proxy) endpoint that returns an object containing the [access token](https://docs.coveo.com/en/o8ld0051/), [organization ID](https://docs.coveo.com/en/n1ce5273/), [client ID](https://docs.coveo.com/en/masb0234/), and [tracking ID](https://docs.coveo.com/en/n8tg0567/), which are required to initialize the web pixel.
If you're not using the Coveo app, pass the `accessToken`, `organizationId`, `clientId`, and `trackingId` parameters directly to the `init` function below.
<2> The `init` function initializes the web pixel (see [@coveo/shopify](https://www.npmjs.com/package/@coveo/shopify)).

. Include this snippet in your `theme.liquid` file, just before the closing `</head>` tag:

```html
{% render 'initialize-analytics' %}
```

### Create UI components

If you're using Coveo Headless with Shopify Liquid, you’ve likely implemented your Shopify Liquid theme using a framework such as [React](https://react.dev/), [Vue](https://vuejs.org/), or [Angular](https://angular.dev/).

To build UI components within that framework, see [Headless commerce usage (client-side rendering)](https://docs.coveo.com/en/o6r70022/).