PLP Pages

This guide walks through the end-to-end steps required to power a Product List Page (PLP) using XGen's Search Service. The approach is implementation-agnostic — whether you are calling the API directly or using the XGen SDK, the platform-side configuration steps are the same.

Overview

A PLP in XGen is powered by the Search Service operating in a mode where the "query" is just the name of the category page, and the results are scoped to a specific category through a dynamic filter. The steps are:

1. Create a Hybrid Search engine
2. Create a category filter with dynamic context for the cateogry page
3. Create a Search Experience (deployment) and attach the engine and filter
4. Call the Search API using the deployment
5. Pass the category context at request time to scope results

Step 1: Create a Hybrid Search Engine

PLPs benefit from the Hybrid Search model, which blends GenSearch's semantic, natural-language capabilities with additional product metadata.

Creating the Engine

1. Navigate to XSearch → Engines in the XGen Platform.
2. Click New Engine and give it a descriptive name (e.g., PLP Engine).
3. Under Model Selection, choose Hybrid Search.
4. Configure the Product Fields to include in the training dataset. These fields define what the model uses to understand and rank products. Include all fields relevant to your catalog (e.g., prod_name, category, product_types, description, custom fields, etc.).
5. Save the engine configuration.

Step 2: Create a Category Filter with Dynamic Context

To scope a PLP to a specific category, you need a filter that uses a dynamic context variable rather than a hardcoded category value. This allows the same filter to serve every category page on your site — the actual category is injected at request time.

Prerequisites: Product Data

Your products must have a field that identifies which category page(s) they belong to. For example:

{
  "prod_code": "abc123",
  "prod_name": "Floral Wrap Dress",
  "category": "dresses"
}

The exact field name (e.g., category, plp_category, collections) is up to your data model — just ensure it is consistently populated across your product catalog and synced to XGen.

Creating the Filter

1. Navigate to Filters in the XGen Platform (found under the Merchandising or Search configuration sections).
2. Click New Filter and give it a name (e.g., PLP Category Filter).
3. Create a condition that matches products using the category field and a context variable (rather than a hardcoded value):

{
  "property": "category",
  "operator": "equals",
  "variable": "plp_category"
}

In this configuration:

• property is the field on your product data that holds category information.
• variable is the context key that will be supplied at request time.
• The operator should reflect how your category data is structured — use equals for exact string matches, contains for array fields, etc. Refer to the Filter Operators reference for the full list.

4. Save the filter.

How dynamic context works: When this filter is evaluated, the engine replaces variable: "plp_category" with whatever value is passed in the context object of the API request. This means one filter can serve all of your category pages — /dresses, /jackets, /shoes — simply by changing the context value per request.

Tip — Wildcard Bypass: If you ever need the filter to pass everything (e.g., for a top-level "all products" page), you can pass "*" as the context value. The condition will match all products, effectively disabling the category filter for that request.

Step 3: Create a Search Experience (Deployment)

An XGen Search Experience is a named deployment that ties together an engine, a filter, and other configuration. Each Experience has a unique Deployment ID that is referenced in all API calls.

Creating the Experience

1. Navigate to XSearch → Deployments in the XGen Platform.
2. Click New Deployment and provide a descriptive name (e.g., PLP Experience).
3. Select API Version as the experience type. The API Version is the correct choice for custom-rendered implementations — you control the rendering and layout; XGen supplies the ranked product data.
4. Once the experience is created, configure the following:
   • Search Engine: Select the Hybrid Search engine created in Step 1.
   • Primary Filter: Select the category filter created in Step 2.
5. Click Save.

Important: Changes to a published experience take effect immediately. The Update button must always be clicked to persist any configuration change, even after toggling the published state.

Retrieve the Deployment ID

Once saved, the Deployment will have an associated Deployment ID. This ID is required for all API calls and can be found in the deployment detail view within the XGen Platform.

Step 4: Call the Search API

Request Body

{
  "deployment_id": "<your_deployment_id>",
  "query": "",
  "collection": "<your_collection>",
  "page": 1,
  "context": {
    "plp_category": "<category_slug>"
  }
}

Key fields:

Response

A successful 200 response includes:

• products_list — the ranked, filtered list of products for the category
• total_result — total number of matching products (use for pagination)
• page — the current page number
• facet — facet/filter counts (if perform_faceting was true)
• sorted_by — the sort field applied
• is_filter_applied — confirms whether the filter was evaluated

Step 5: Pass Category Context to Scope Results

The key mechanism that makes a single deployment reusable across all category pages is the context object passed in each API request.

When a user navigates to a category page (e.g., /category/dresses), your application determines the category identifier for that page and includes it in the context payload:

{
  "deployment_id": "<your_deployment_id>",
  "query": "",
  "collection": "en-us",
  "context": {
    "plp_category": "dresses"
  }
}

The filter created in Step 2 has the condition:

{
  "property": "category",
  "operator": "equals",
  "variable": "plp_category"
}

At runtime, the filter engine resolves variable: "plp_category" → "dresses" from the context, and only products with category === "dresses" are included in the result set.

Navigating to /category/jackets requires only changing the context value:

{
  "context": {
    "plp_category": "jackets"
  }
}

No additional deployments, filters, or engine configurations are needed per category.

Context Key Naming

The context key (e.g., plp_category) must exactly match the variable name defined in your filter condition. This is case-sensitive.

Summary

Additional References

• XSearch Engines Introduction
• Hybrid Search Model Training
• XSearch Experiences
• Filter Syntax
• Filter Operators
• Search API Reference