Build Headless commerce interfaces with Shopify Liquid

This is for:

Developer
In this article

If you use a Shopify Liquid theme, we typically recommend using Coveo Atomic. 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 library with Shopify Liquid.

We typically recommend using Headless with Shopify Hydrogen 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) 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 to install the Coveo Shopify library.

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).

 
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 with the Search - Execute queries - Allowed and Analytics - Analytics data - Push privileges.
2 Your organization ID.
3 The target tracking ID.
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 logs cart, product view, and purchase events.

If you’re not using the Coveo AI Search and Discovery app and don’t have the Coveo app web pixel installed, you’ll need to create your own.

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.

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

    <!-- 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 endpoint that returns an object containing the access token, organization ID, client ID, and tracking ID, 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).

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

    {% 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, Vue, or Angular.

To build UI components within that framework, see Headless commerce usage (client-side rendering).