Setting Up Catalog Search

Catalog Search provides fast, relevant product search capabilities for your storefront. This guide walks you through enabling and configuring search for your catalogs using the API.

tip

You can also configure Catalog Search using Commerce Manager. See Catalog Search in Commerce Manager for step-by-step instructions.

Overview

The Catalog Search service provides:

• Full-text search across product names, descriptions, SKUs, and custom fields
• Faceted navigation for filtering by categories, attributes, and price ranges
• Relevance ranking with customizable search profiles
• Multi-language support with locale-aware search
• Price filtering with automatic currency and price book support

Prerequisites

Before setting up catalog search, ensure you have:

• Catalog Search enabled for your store or organization (contact Customer Success to enable this feature)
• Search enabled for the catalogs you want to be searchable (see Enabling Catalog Search)
• A published catalog with products, hierarchies, and price books configured
• API credentials with appropriate permissions

What Happens When Search is Enabled

When you enable search for a catalog:

1. Automatic indexing: All future catalog releases are automatically indexed when published
2. Extended publishing: The publish process includes an indexing step that makes products searchable
3. Search availability: Once indexed, products are searchable via the Search API

note

Existing releases are not automatically indexed. You must publish a new release after enabling search for products to become searchable.

Understanding the Indexing Process

When you publish a catalog release, the following occurs:

1. The catalog release is processed and stored (shows as 99% complete)
2. An indexing job is created to make products searchable
3. Products are transformed and indexed with their:
   • Names and descriptions (per locale)
   • SKUs and other identifiers
   • Category/hierarchy associations
   • Prices from all configured price books
   • Custom indexable fields
4. The release is marked as PUBLISHED when indexing completes

Configuring Indexable Fields

By default, catalog search indexes standard product fields. You can extend this by configuring additional indexable fields from your product extensions (custom attributes).

List Available Searchable Fields

To see what fields are currently searchable:

curl https://useast.api.elasticpath.com/v2/pcm/catalogs/searchable-fields \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Add Custom Indexable Fields

To make custom product attributes searchable, create indexable fields:

curl -X POST https://useast.api.elasticpath.com/v2/pcm/catalogs/indexable-fields \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "catalog_search_indexable_fields",
      "attributes": {
        "fields": [
          {
            "name": "extensions.products(clothing).color",
            "facetable": true,
            "sortable": false
          },
          {
            "name": "extensions.products(clothing).brand",
            "facetable": true,
            "sortable": true
          },
          {
            "name": "extensions.products(specifications).rating",
            "facetable": true,
            "sortable": true
          }
        ]
      }
    }
  }'

Field options:

Option	Description
name	The field path in your product extensions (must match pattern extensions.products(<template>).<field>)
facetable	Enable faceting (aggregated counts) on this field
sortable	Enable sorting by this field
locale	Language for tokenization (default: en)

caution

After adding or modifying indexable fields, you must reindex your catalog releases for the changes to take effect. See Reindexing.

Setting Up Search Profiles

Search profiles control how search queries are executed. They define which fields to search, their relative importance, and business rules for filtering and boosting results.

Create a Search Profile

curl -X POST https://useast.api.elasticpath.com/v2/pcm/catalogs/search-profiles \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "catalog_search_profile",
      "attributes": {
        "slug": "default-search",
        "description": "Default search profile for storefront",
        "fields": [
          { "name": "name", "weight": 10 },
          { "name": "description", "weight": 5 },
          { "name": "sku", "weight": 8 },
          { "name": "meta.search.nodes.name", "weight": 3 }
        ],
        "text_match_type": "max_score"
      }
    }
  }'

Understanding Field Weights

Field weights control the relative importance of each field when ranking search results:

• Higher weights mean matches in that field contribute more to relevance
• A product with "laptop" in the name (weight 10) ranks higher than one with "laptop" only in description (weight 5)
• Weights are relative: 10:5:3 behaves the same as 100:50:30

Text Match Types

The text_match_type determines how scores from multiple fields are combined:

Type	Description	Best For
max_score (default)	Uses highest score from any matching field	General product search
max_weight	Uses score from highest-weighted matching field	When field importance matters more than match quality
sum_score	Sums weighted scores from all matching fields	Rewarding multi-field matches

Adding Filters

Profile filters are automatically applied to all searches using that profile:

{
  "filters": [
    "status:=live && visibility:=public"
  ]
}

Multiple filters are combined with OR logic, then ANDed with user filters:

Final Filter = (Profile Filter 1 || Profile Filter 2) && User Filter

Adding Boost Rules

Boost rules promote or demote products based on conditions:

{
  "boosts": [
    {
      "condition": "extensions.products(Details).is_featured:=true",
      "weight": 100
    },
    {
      "condition": "extensions.products(Details).on_sale:=true",
      "weight": 50
    },
    {
      "condition": "extensions.products(Details).stock_status:=out_of_stock",
      "weight": -100
    }
  ]
}

• Positive weights: Push products to the top
• Negative weights: Push products to the bottom (bury)

Set a Default Search Profile

Make a profile the default for all searches:

curl -X POST https://useast.api.elasticpath.com/v2/pcm/catalogs/search-profiles/{profile_id}/default \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Using the Search API

Basic Search

Perform a shopper search:

curl "https://useast.api.elasticpath.com/v2/pcm/catalog/search?q=laptop" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Search with Filters

Filter results by category, price, or custom attributes:

curl "https://useast.api.elasticpath.com/v2/pcm/catalog/search?q=laptop&filter_by=meta.search.nodes.name:=Electronics%20%26%26%20price.float_price:[500..2000]" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Search with Facets

Get aggregated counts for filtering UI:

curl "https://useast.api.elasticpath.com/v2/pcm/catalog/search?q=laptop&facet_by=meta.search.nodes.name,extensions.products(Details).brand" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Multi-Search

Execute multiple searches in a single request:

curl -X POST https://useast.api.elasticpath.com/v2/pcm/catalog/multi-search \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "searches": [
      {
        "q": "laptop",
        "filter_by": "meta.search.nodes.name:=Electronics",
        "per_page": 10
      },
      {
        "q": "laptop",
        "filter_by": "meta.search.nodes.name:=Accessories",
        "per_page": 5
      }
    ]
  }'

Using a Specific Search Profile

Override the default profile for a search:

curl "https://useast.api.elasticpath.com/v2/pcm/catalog/search?q=laptop&search_profile=b2b-wholesale" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Filter Syntax Reference

Comparison Operators

Operator	Description	Example
:=	Exact match	status:=live
:	Contains (word match)	name:laptop
:!=	Not equal (exact)	status:!=draft
:!	Does not contain	name:!refurbished
:>	Greater than	price.amount:>1000
:>=	Greater than or equal	price.amount:>=1000
:<	Less than	price.amount:<500
:<=	Less than or equal	price.amount:<=500

Combining Conditions

• AND: condition1 && condition2
• OR: condition1 || condition2
• Grouping: (condition1 || condition2) && condition3

Special Characters

Use backticks to escape special characters in values:

meta.search.nodes.name:=`Home & Garden`
meta.search.nodes.name:=[`Running Shoes, Men`, `Sneaker (Men)`]

Range Filters

price.float_price:[100..500]     // Between 100 and 500
price.float_price:[<100, >500]   // Less than 100 OR greater than 500

Reindexing Catalog Releases

If you modify indexable fields or need to rebuild indexes, you can trigger reindexing:

Reindex All Releases

curl -X POST https://useast.api.elasticpath.com/v2/pcm/catalogs/reindex-releases \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "force_reindex": true
    }
  }'

Check Index Status

View which indexes are out of sync:

curl "https://useast.api.elasticpath.com/v2/pcm/catalogs/search-indexes?out_of_sync=true" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Best Practices

Search Profile Design

1. Start with core fields: Always include name, description, and sku
2. Add category fields: Include meta.search.nodes.name for category-based discovery
3. Limit field count: Focus on 3-5 key fields to maintain relevance
4. Test incrementally: Start with small weight differences and adjust based on results

Indexable Fields

1. Index selectively: Only index fields that users will search or filter by
2. Enable faceting wisely: Facetable fields increase index size
3. Consider sorting needs: Enable sorting only for fields you'll sort by

Performance

1. Use specific filters: More specific filters improve query performance
2. Limit facet values: Use max_facet_values to limit facet result counts
3. Paginate results: Use page and per_page for large result sets

A/B Testing

Search profiles enable A/B testing without code changes:

1. Create variant profiles with different field weights or boost rules
2. Route traffic to different profiles based on user segments
3. Measure conversion rates and revenue per search
4. Iterate based on results

Related Resources

• Catalog Search API Reference
• Search Profiles API
• Indexable Fields
• Catalog API