Integrate with Zoovu

This is for:

Developer

In this article

Prerequisites
Common search-to-configuration pattern
The catalog data contract
Set up the handoff
Considerations

You can connect a Coveo-powered commerce implementation into a Zoovu guided selling experience so that, when a shopper reaches a configurable product, your storefront launches the matching Zoovu assistant, which guides the shopper to a valid configuration.

This article describes the search-to-configuration handoff pattern between Coveo and Zoovu. Coveo surfaces and ranks the right product, catalog data on the result indicates whether configuration is required, and your storefront launches the corresponding Zoovu experience. Your transactional system of record remains authoritative for validating the configuration, confirming the current price and availability, and creating the order.

Prerequisites

You have a working Coveo for Commerce implementation with at least one search, product listings, or recommendations product discovery solution set up and rendering your catalog data on your storefront.
You have a published Zoovu guided-selling experience for the products that shoppers configure.
You have access to your product catalog so that you can add and govern the configuration metadata fields.
You have the privileges to create and manage source mappings and fields in your Coveo organization.

Common search-to-configuration pattern

The pattern separates four responsibilities, each answering a specific question, so that every system does what it’s best at:

The Coveo Platform answers "What is the most relevant product for the user?" through search, product listings, and recommendations.
Catalog data answers "Is configuration required?" through Coveo fields.
Your storefront answers "Which Zoovu experience should launch, and how?"
Zoovu answers "What valid configuration does the shopper need?" through its guided-selling or configuration flow.

At runtime, a Coveo and Zoovu integration looks like the following:

1	A shopper searches or browses a Coveo-powered commerce storefront.
2	Coveo returns ranked products that carry configuration fields, indicating whether each product is configurable.
3	The shopper selects a configurable product, and the result card or product detail page (PDP) shows a Configure option because the product is marked configurable.
4	Your storefront reads the configuration fields returned with the selected product to determine which Zoovu experience to launch.
5	Your storefront resolves which Zoovu experience matches the selected product and locale.
6	Your storefront mounts the Zoovu assistant, passing in the requirements the shopper already gave the Coveo search experience (through their query or facet selection) so Zoovu doesn’t ask for them again.
7	Zoovu runs the guided-selling or configuration flow, asking the shopper only the questions that remain.
8	Zoovu returns the completed configuration, which your storefront passes to your commerce backend or configure-price-quote (CPQ) system to validate the configuration, confirm the current price and availability, and create the order.
9	The commerce backend or CPQ returns the validated quote, cart, or order to the shopper.
10	Your storefront sends commerce events for the shopper’s actions, including the purchase and its final price, so Coveo can attribute the sale and its revenue to the discovery that led to it.

The catalog data contract

Whether a Zoovu configuration experience launches is determined by the metadata available on each product returned by Coveo.

This means that you must add a set of custom fields to your Coveo product data that indicate whether a product requires a Zoovu configuration, and which configuration to return for it. These fields aren’t standard Coveo fields: you define, name, and populate them yourself. The names in this article are examples, so use whatever names fit your product data.

Example key Example value Data type Required? Purpose

Example key	Example value	Data type	Required?	Purpose
`requires_configuration`	`true`	`string`	Yes	Flags whether a product needs a Zoovu configuration.
`configuration_experience_key`	`EXCAVATOR_30_40T`	`string`	Yes, when configuration is required	Selects which Zoovu experience to launch.
`configuration_family`	`MID_RANGE_EXCAVATOR`	`string`	Optional	Add it only if you want several products to share one configuration journey.
`configuration_provider`	`zoovu`	`string`	Optional	Add it only if you use more than one configuration provider and need to tell them apart.

requires_configuration

true

string

Yes

Flags whether a product needs a Zoovu configuration.

configuration_experience_key

EXCAVATOR_30_40T

string

Yes, when configuration is required

Selects which Zoovu experience to launch.

configuration_family

MID_RANGE_EXCAVATOR

string

Optional

Add it only if you want several products to share one configuration journey.

configuration_provider

zoovu

string

Optional

Add it only if you use more than one configuration provider and need to tell them apart.

You set this information in your catalog data when pushing or updating it. Once it’s available, create Coveo fields for these metadata keys and define the matching mappings. See Commerce fields and mapping for how to create fields and set their type.

Set up the handoff

Follow these steps to connect Coveo discovery to a Zoovu configuration experience and verify the end-to-end flow.

Step 1: Add and map the configuration metadata

On every product, set a field that flags whether configuration is required (for example, requires_configuration). For products that require configuration, also set a field that identifies which configuration to launch (for example, configuration_experience_key). Add fields for the optional configuration family and provider only if your implementation needs them (see The catalog data contract).

Add the configuration fields to the products in your catalog data through a Stream API push or update operation.
Create the required mappings and fields. Create each configuration field as a String field.
Make sure Coveo returns the fields with each product. How you do this depends on the API that powers your product discovery:
- Commerce API: Add the fields to the additionalFields array of the relevant configuration. The Commerce API only returns the standard commerce fields plus the fields listed there, so add the fields to every discovery surface where you want to show Configure. How you do this depends on the surface:
  
  Search and product listings: Add the fields to the additionalFields array of your query configuration. Search uses the global query configuration, while product listings can use the global configuration or a listing-specific one.
  
  Recommendations: Add the fields to the additionalFields array of the relevant recommendation configuration, which can be global or slot-specific.
- Search API: No configuration step is needed here. You request the fields from your result template in Step 2.
Use the Content Browser (platform-ca | platform-eu | platform-au) to confirm that the fields are indexed on the expected products.

Step 2: Render a configuration option only on configurable products

In Coveo Headless, register a template whose conditions evaluate the configuration fields you created in Step 1, so that the Configure action renders only on configurable products.

The template conditions mirror the launch rule: the product flags configuration and carries an experience key. Which template manager, helpers, and property names you use depends on the API that powers your product discovery.

With the Commerce API

Use the Headless commerce ProductTemplatesManager and ProductTemplatesHelpers. The custom fields you listed in your query configuration’s additionalFields in Step 1 are returned on each product’s additionalFields property, so you read them as product.additionalFields.<field_name>.

import { buildProductTemplatesManager, ProductTemplatesHelpers } from '@coveo/headless/commerce';

const templatesManager = buildProductTemplatesManager(); 

templatesManager.registerTemplates({
  conditions: [
    ProductTemplatesHelpers.fieldMustMatch('requires_configuration', ['true']), 
    ProductTemplatesHelpers.fieldsMustBeDefined(['configuration_experience_key']) 
  ],
  content: (product) => (
    <ProductCard
      product={product}
      actions={
        <ConfigureButton
          experienceKey={product.additionalFields.configuration_experience_key} /> 
      }
    />
  )
});

	Unlike the Search API templates manager, the commerce templates manager doesn’t request fields from the API. The fields are available because you added them to your query configuration in Step 1.
	`fieldMustMatch` compares values as case-insensitive strings, so `'true'` matches the String field value `"true"`.
	If a product requires configuration but has no experience key, hide the configuration option and offer the fallback path described in Step 3b.
	The Configure action carries the `configuration_experience_key`, which your launch middleware resolves against the experience registry (Step 3) to launch the matching Zoovu experience.

For more information about the commerce product templates manager, see the Coveo Headless ProductTemplatesManager reference.

With the Search API

Use the Coveo Headless ResultTemplatesManager and ResultTemplatesHelpers. Fields that you list in the template’s fields property are added to the fieldsToInclude of the search request, and the returned values are available on result.raw.

import { buildResultTemplatesManager, ResultTemplatesHelpers } from '@coveo/headless';

const templatesManager = buildResultTemplatesManager(engine); 

templatesManager.registerTemplates({
  fields: ['requires_configuration', 'configuration_experience_key'], 
  conditions: [
    ResultTemplatesHelpers.fieldMustMatch('requires_configuration', ['true']), 
    ResultTemplatesHelpers.fieldsMustBeDefined(['configuration_experience_key'])
  ],
  content: (result) => (
    <ProductCard
      result={result}
      actions={
        <ConfigureButton
          experienceKey={result.raw.configuration_experience_key} /> 
      }
    />
  )
});

	The search templates manager takes your Headless search engine so that it can register the fields to include in the query.
	Request the two required custom fields from Step 1 by name. Listing them here adds them to the search request so the Search API returns them with each result.
	`fieldMustMatch` compares values as case-insensitive strings, so `'true'` matches the String field value `"true"`.
	The Configure action carries the `configuration_experience_key` from `result.raw`, which your launch middleware resolves against the experience registry (Step 3).

For more information about Headless templates, see the Coveo Headless result templates reference.

Step 3: Build the launch middleware

Coveo and Zoovu don’t connect on their own. The launch middleware is the storefront logic that joins them, and you implement, host, and own it. It has two parts, built in the following sub-steps:

An experience registry that maps each experience key to a Zoovu deployment (Step 3a).
The launch logic that seeds context and mounts the experience (Step 3b).

At runtime, the middleware launches Zoovu in three moves:

The shopper selects a configurable product and clicks Configure, the action you rendered in Step 2.
Your launch logic reads that product’s configuration_experience_key and looks it up in the registry, which returns the Zoovu advisor code, locale, and render mode.
Your launch logic seeds the shopper’s known requirements, then mounts the matching Zoovu experience in that render mode. This is the moment the Zoovu experience launches.

Step 3a: Create the experience registry

The experience registry is a lookup table that resolves the configuration_experience_key Coveo returns on each product (from the fields you set up in Step 1 and evaluate in Step 2) into the Zoovu deployment your launch logic mounts in Step 3b.

Implement the registry as a server-side endpoint that your storefront calls with the selected product, rather than in the storefront bundle. This keeps each Zoovu advisor code, your rollout rules, and vendor choices off the client and out of the Coveo catalog.

Because you define this structure, treat the following example as a minimal illustration and add only the fields your storefront needs:

EXCAVATOR_30_40T: 
  advisorCode: <advisorCode> 
  locale: en-US 
  renderMode: inline-pdp 
  [...]

LOADER_WHEELED_SMALL:
  advisorCode: <advisorCode>
  locale: en-US
  renderMode: dedicated-page
  [...]

MID_RANGE_EXCAVATOR: 
  advisorCode: <advisorCode>
  locale: en-US
  renderMode: drawer
  [...]

# [...] one entry per configuration_experience_key you support

	The `configuration_experience_key` from Step 1. This value arrives on the Coveo result and is what your storefront looks up here.
	The `<advisorCode>` is the identifier Zoovu assigns to a published assistant, which you get from Zoovu when you publish it.
	The locale this mapping applies to (if any). Use it to route the same key to different deployments per locale and store.
	How the storefront renders the experience. For example, inline on the PDP, in a drawer, or on a dedicated configure page for long or complex flows.
	An entry shared by a product family. When several products carry the same `configuration_family`, point them at one `configuration_experience_key` so they reuse a single entry (here, the family’s shared journey).

You can store any other details your storefront needs in each entry, such as which context to seed in Step 3b.

Step 3b: Seed context and mount the Zoovu experience

This is the launch logic. Using the advisor code, locale, and render mode from Step 3a, your middleware seeds the shopper’s requirements, then mounts the Zoovu experience.

To seed a requirement, write it to the browser’s local storage, where Zoovu reads it on startup through the PROVIDED scope of its Context feature. Use this key pattern:

zoovu.<advisorCode>.<locale>.context.<attribute>

Where:

<advisorCode> is the Zoovu advisor code of the published experience you resolved in Step 3a.
<attribute> is the context attribute name.
The <locale> segment is optional. When you omit it, drop the segment and its dot so that the key becomes zoovu.<advisorCode>.context.<attribute>.

The <attribute> segment must match the exact name, including casing, of a context attribute defined with the PROVIDED scope in the assistant’s context schema (in Zoovu Conversation Studio, select the assistant and then Context). A key that doesn’t match an existing attribute has no effect on the experience, so double-check each name against your schema.

The following attributes illustrate the kind of context you can pass:

Attribute Example value How Zoovu can use it

Attribute	Example value	How Zoovu can use it
`selectedProduct`	`EXC-350`	Identifies the product the shopper selected.
`configurationFamily`	`MID_RANGE_EXCAVATOR`	Selects or branches the configuration journey.
`application`	`quarry_loading`	Skips or branches questions about the intended use.
`requestedDepthFt`	`22`	Pre-populates a known requirement.
`locale`	`en-US`	Drives experience selection and display.

selectedProduct

EXC-350

Identifies the product the shopper selected.

configurationFamily

MID_RANGE_EXCAVATOR

Selects or branches the configuration journey.

application

quarry_loading

Skips or branches questions about the intended use.

requestedDepthFt

22

Pre-populates a known requirement.

locale

en-US

Drives experience selection and display.

Then mount a Zoovu Digital Assistant (built in Conversation Studio) with Zoovu’s JavaScript loader, using the same locale in the loader URL and the context keys. To mount a Visual Configurator, build it as a configurator within an assistant so it inherits the seeded context.

// Seed known requirements before the Zoovu assistant initializes.
localStorage.setItem('zoovu.<advisorCode>.en-US.context.selectedProduct', 'EXC-350');
localStorage.setItem('zoovu.<advisorCode>.en-US.context.application', 'quarry_loading');
localStorage.setItem('zoovu.<advisorCode>.en-US.context.requestedDepthFt', '22');

<!-- Then mount the published Zoovu assistant. -->
<script src="https://orca-api.zoovu.com/advisor-fe-web/api/v1/advisors/<advisorCode>/js-loader?locale=en-US"></script>
<div id="zoovu-assistant"></div>

Seeding a value only has an effect when the assistant is configured with a matching context action that consumes it (for example, a Skip action on a question whose answer is already known), so define those context attributes and actions in Conversation Studio as part of the assistant. For the provided-context key pattern, the context actions, and the embed loader, see the Zoovu context reference, Zoovu context configuration, and Zoovu embed documentation.

Build a fallback mechanism for when the registry has no active entry for the product’s configuration_experience_key or the Zoovu experience fails to load.

For example, you could offer an alternative path (such as request a quote), and block direct purchase of a product that still requires configuration.

Step 4: Handle completion and transact

When the shopper completes the configuration, the configured result is captured in the Zoovu assistant. Handling completion (reading the configured product and passing it onward) is specific to your Zoovu experience and is typically implemented with Zoovu’s Custom Code Integration, for example add-to-cart or CRM/ERP handoff logic. Pass that result to your commerce backend or CPQ, which validates the configuration, confirms the current price and availability, and creates the cart item, quote, or order. That transactional system of record remains authoritative for these steps.

Keep using the Coveo commerce event tracking you already have in place for the shopper’s real actions (product clicks, product views, cart updates, and purchases). When the shopper completes a purchase, send the purchase event with the product and price they actually ordered, following the Attribution logic guidelines.

Step 5: Validate the end-to-end flow

Test the handoff with published Zoovu experiences for the products and locales you intend to support.

Test	Expected behavior
Supported product	Configure opens the mapped experience for the selected product and locale.
Known requirements	The experience uses the seeded values and asks only the remaining questions.
Completed configuration	Your commerce backend receives the required identifiers and state, validates the selection, and creates the intended cart item or quote.
Missing or inactive mapping	The product page stays usable and offers the fallback path.
Zoovu unavailable	The storefront handles the loading failure and prevents purchase of a product that still requires a valid configuration.
Tracking	Commerce events reflect actual shopper actions, and the purchase event carries the configured product and price.

Test

Expected behavior

Supported product

Configure opens the mapped experience for the selected product and locale.

Known requirements

The experience uses the seeded values and asks only the remaining questions.

Completed configuration

Your commerce backend receives the required identifiers and state, validates the selection, and creates the intended cart item or quote.

Missing or inactive mapping

The product page stays usable and offers the fallback path.

Zoovu unavailable

The storefront handles the loading failure and prevents purchase of a product that still requires a valid configuration.

Tracking

Commerce events reflect actual shopper actions, and the purchase event carries the configured product and price.

Considerations

You build and own the integration.

This is a storefront-mediated pattern: you design, build, and maintain the storefront logic, the experience registry, and the Zoovu embed.
Conversational Product Discovery isn’t the launch point today.

Launch Zoovu from Coveo search, product listings, or the PDP. Invoking Zoovu from inside Conversational Product Discovery isn’t supported, so let Conversational Product Discovery surface the product, then let the shopper follow the product route where your storefront evaluates the metadata.