Documentation
Discussions
Start typing to search…

Catalog 2.0 - AI Discovery

Building an AI Discovery experience unlocks the ability for the end user to discover product options through conversation prompts.

This section allows the users to manage the AI Discovery experience of the new Catalog 2.0. This is one of the new features available in the new Catalog 2.0, and it is dependent on the other new features provided by the new catalog, such as attribute options, variants, and the prompts.

The new catalog is currently useful only for building AI Experiences. For all regular configuration needs you have to use the classic catalog.

Experience Query Filter Syntax

The Query Experience endpoint allows you to perform a filter on the variants before the semantic search is performed. You pass an array of filter objects which are combined using a logical AND.

Filter Types

There are 3 types of filters (details below):

  • Item / Variant Filter
    • support filtering on customId and name
    • for variant also on status
  • Configuration Filter
    • supports filtering on variants having specific attribute-option pairs
  • Price Filter
    • supports filtering on variants by associated currency and price

Simple Example

There are details on how to specify each type of filter below. However this simple example will help with understanding the general structure (even if you don’t read this whole document)

The following matches variants for:

  • the item Avena Shirt
  • Have a configuration where:
    • Color is Red
    • Size is Medium or Large
  • and costs ≥ 200 USD.
// Query Experience endpoint body
{
  "filters": [
    // Items Filter
    {
      "field": "items.name",
      "operator": "=",
      "value": "Avena Shirt"
    },
    // Configuration Filters
    {
      "attributes": {
        "field": "attributes.name",
        "operator": "=",
        "value": "Color"
      },
      "options": {
        "field": "options.name",
        "operator": "=",
        "value": "Red" // ex. Green, Blue -- excluded
      }
    },
    {
      "attributes": {
        "field": "attributes.name",
        "operator": "=",
        "value": "Size"
      },
      "options": {
        "field": "options.name",
        "operator": "=",
        "value": ["Medium", "Large"] // ex. Small -- excluded
      }
    },
    // Variants Price Filter
    {
      "field": "variants.price",
      "operator": ">=",
      "value": {
        "currency": "USD",
        "amount": 200
      }
    }
  ],
  "count": 4,
  "query": "I want new clothes."
}

Items/Variants Filters

Take the general form

{ field: string, operator: "=" | "!=", value: string | string[] }

Supported field

  • items.name , items.customId
  • variants.customId , variants.status
    • variants.status has to be one of the following values:"active", "deactivated", "invalid".

Supported value

  • a string - to match one value
  • a string array - to match ANY of the strings in the array
  • each string can be up to 255 characters (the limit for customId / name in the platform)

Supported operator

=(Equals)

// Match all active variants
{ "field": "variants.status", "operator": "=", "value": "active" }
// Match variants that belong to items that are named "Desk" OR "Chair"
{ "field": "items.name", "operator": "=", "value": ["Desk", "Chair"] }

!=(Not Equals)

// Match variants that do NOT have the customId 'SKU-DR-123'
{ "field": "variants.customId", "operator": "!=", "value": "SKU-DR-123" }
// Match variants that do NOT belong to items with customId 'DSK-123' OR 'DSK-456'
{ "field": "items.customId", "operator": "!=", "value": ["DSK-123","DSK-456"] }

Configuration Filters

Configuration filters allow you to match variants based on which attribute-option pairs they contain. They take the general form:

{
  attributes: { field: string, operator: "=" | "!=", value: string | string[] },
  options: { field: string, operator: "=" | "!=", value: string | string[] }
}

Note the “attributes” and “options” obejct look the same as the items filter, but with different fields.

Supported field

  • attributes.name , attributes.customId for the “attributes” object
  • options.name , options.customId for the “options” object

Supported value

  • a string - to match one value
  • a string array - to match ANY of the strings in the array
  • each string can be up to 255 characters (the limit for customId / name in the platform)

Supported operator

=(Equals)

// Match variants who have an attribute "Size" with the option values "medium" OR "large"
{
  "attributes": {
    "field": "attributes.name",
    "operator": "=",
    "value": "Size"
  },
  "options": {
    "field": "options.name",
    "operator": "=",
    "value": ["medium", "large"]
  }
}

!=(Not Equals - Attributes)

// Match variants where an attribute other than 'Interior Color'
// has the option value 'blue'
{
  "attributes": {
    "field": "attributes.name",
    "operator": "!=",
    "value": "Interior Color"
  },
  "options": {
    "field": "options.name",
    "operator": "=",
    "value": "blue"
  }
}

!=(Not Equals - Options)

// Match variants that have attributes "Interior Color" OR "Exterior Color"
// but an option value other than "blue"
{
  "attributes": {
    "field": "attributes.name",
    "operator": "=",
    "value": ["Interior Color", "Exterior Color"]
  },
  "options": {
    "field": "options.name",
    "operator": "!=",
    "value": "blue"
  }
}

Variant Price Filters

Variant Price filters allow you to find variants based on the price of the variant in a specified currency. It also lets you match variants with no price at all by passing null. Take the general form:

{
  field: "variants.price",
  operator: "=" | "!=" | ">" | "<" | ">=" | "<=" | "between",
  value: null | object
}

Supported field

  • "variants.price"

Supported value

  • null - Match all variants with no price.
  • {currency, amount}
    • currency must be a 3-letter ISO code (e.g. "USD", "EUR", "GBP", etc.)
    • amount must be a number (or an array of two numbers for between operator)

Supported operator

=(Equals)

Example: Match all variants with no price.

{ "field": "variants.price", "operator": "=", "value": null }

Example: Match all variants with a price of exactly 100 USD.

{
  "field": "variants.price",
  "operator": "=",
  "value": { "currency": "USD", "amount": 100 }
}

>(Greater Than)

Example: Match all variants with a price greater than 100 USD.

{
  "field": "variants.price",
  "operator": ">",
  "value": { "currency": "USD", "amount": 100 }
}

>=(Greater Than or Equal)

Example: Match all variants with a price greater than or equal to 100 USD.

{
  "field": "variants.price",
  "operator": ">=",
  "value": { "currency": "USD", "amount": 100 }
}

<(Less Than)

Example: Match all variants with a price less than 100 USD.

{
  "field": "variants.price",
  "operator": "<",
  "value": { "currency": "USD", "amount": 100 }
}

<=(Less Than or Equal)

Example: Match all variants with a price less than or equal to 100 USD.

{
  "field": "variants.price",
  "operator": "<=",
  "value": { "currency": "USD", "amount": 100 }
}

between— Matches prices within a range (inclusive)

Example: Match all variants with a price between 50 USD and 150 USD.

{
  "field": "variants.price",
  "operator": "between",
  "value": {
    "currency": "USD",
    "amount": [50, 150]
  }
}

Overall Example

{
  "count": 5,
  "query": "I am looking for a new desk for my home office.",
  "filters": [
    // Variants Status Filter
    {
      "field": "variants.status",
      "operator": "=",
      "value": "active"
    },
    // Items Filter
    {
      "field": "items.customId",
      "operator": "=",
      "value": ["SKU-DK-123", "SKU-DK-456"]
    },
    // Configuration Filter
    {
      "attributes": {
        "field": "attributes.name",
        "operator": "=",
        "value": "Desk Shape"
      },
      "options": {
        "field": "options.name",
        "operator": "!=",
        "value": "Round" //ex. Shape might be Square or Rectangle
      }
    },
    {
      "attributes": {
        "field": "attributes.name",
        "operator": "=",
        "value": "Size"
      },
      "options": {
        "field": "options.name",
        "operator": "=",
        "value": ["Small", "Large"]
      }
    },
    {
      "attributes": {
        "field": "attributes.name",
        "operator": "=",
        "value": "Style"
      },
      "options": {
        "field": "options.customId",
        "operator": "!=",
        "value": "minimalist"
      }
    },
    // Variants Price Filter
    {
      "field": "variants.price",
      "operator": "between",
      "value": {
        "currency": "USD",
        "amount": [300, 500]
      }
    }
  ]
}

This filter will match variants that:

  • Are active
  • Exist on item with the custom ID SKU-DK-123 or SKU-DK-456
  • Have a configuration where:
    • Desk Shape is not Round
    • Size is Small or Large
    • Style is not an option with custom ID minimalist
  • AND have a price between 300 and 500 in USD

A semantic search will be performed to find the top 5 most relevant results to the query “"I am looking for a new desk for my home office." that match the above filter.