Index Structure

The unified extension is designed to work out of the box when your Bloomreach catalog follows certain field naming conventions. This guide explains what those conventions are, and what to do when your catalog differs.

For a quick-reference table of all expected fields, see the Reference page.

Products

Every search and product detail request asks Bloomreach for a set of core fields: pid (product ID), title, price, sale_price, thumb_image, url, description, and brand. The pid serves triple duty — it's used as the product ID, SKU, and URL slug.

Of these, pid, title, price, sale_price, and thumb_image are required. The rest are optional and safely handled when missing.

You can request additional fields from your index by adding them to productFields in your SearchApiConfig.

Per-Currency Pricing

When currencies is configured, the extension requests per-currency price fields using the convention price_<currency> and sale_price_<currency> (lowercase). For example, configuring currencies: ['EUR', 'USD'] adds price_eur, sale_price_eur, price_usd, and sale_price_usd to each request.

The normalizer picks the right price field based on the active vsf-currency cookie, falling back to the bare price / sale_price fields when the currency-specific one isn't available. Price-based sorting follows the same convention — sorting by price with EUR active uses price_eur desc.

Facets

Flat field names like color, size, and brand work out of the box. Add them to facetFields to request them and to facetConfig to assign types. The extension expects text facet values with name and count fields, and range facet values with start, end, and count.

Open-ended ranges use "*" as the boundary — for example, a range starting at 100 with no upper limit displays as "100+".

Category Hierarchy

The category facet expects each value to have a cat_name (display name) and optionally cat_id (identifier) and parent (parent category ID). The extension uses parent to build the tree structure. Top-level categories have no parent field.

When a user selects a category, the facet drills down to show its children. Setting categoryRoot in your config controls which level is treated as the visible top of the tree.

Variants

Product variants are read from the variants array on the product document. Each variant can have a skuid (SKU identifier), sku_color_group (displayed as a "Color" attribute), and sku_thumb_images (variant-specific images that get merged into the product gallery).

All variant fields are optional — products without variants work fine.

What If My Index Differs?

If your Bloomreach catalog uses different field names or structures, you have two paths:

Request additional fields

If you need fields beyond the defaults, add them to productFields in your middleware config. These fields will be available in the raw product document passed to custom normalizers.

configuration: {
  discoveryApi: {
    search: {
      productFields: ['custom_color', 'availability', 'material'],
    },
  },
}

Override normalizers

If your index uses different field names for standard data (e.g. product_name instead of title), override the relevant normalizer to map them. See the Normalizers documentation for the full guide and the Reference for the list of overridable normalizers.