Which Product Properties Should You Send to Recombee?

The quality of a Recombee recommendation model depends heavily on the product catalog supplied to it. Sending only a product ID and name gives the system limited context. Sending every WooCommerce field without a consistent design creates a noisy catalog that is difficult to maintain and can produce weak recommendations.

For most WooCommerce implementations, the right approach is to send a deliberately selected set of product properties. The catalog should describe what the product is, how it can be purchased, where it belongs in the store, and whether it is currently eligible for recommendation.

Start with a stable product identifier

Every item sent to Recombee needs a stable identifier. Use an identifier that remains unchanged when the product title, price, stock level, or permalink changes.

Use the WooCommerce product ID for parent-level recommendations.
Use the variation ID when customers select and purchase variations independently.
Do not use the product name or URL as the primary identifier.
Do not change the identifier when a product is migrated, translated, or renamed.

Agencies should decide early whether the recommendation unit is a parent product or a purchasable variation. Sending both without a clear strategy can cause duplicate-looking recommendations and inconsistent interaction data.

Core properties to send

Product name and descriptive content

Send a concise product name and, where useful, a cleaned version of the short or full description. These properties give the catalog semantic context and can help distinguish products with similar categories.

name: The customer-facing product title.
description: Plain text or controlled HTML converted to a consistent format.
sku: Useful as a business identifier, but it should not replace the item ID.

Strip editor markup, tracking parameters, and presentation-only content from descriptions. Do not send large page-builder payloads as product metadata.

URL and image URL

Send the canonical product URL and a usable image URL so the recommendation response can be rendered without additional catalog lookups.

url: The canonical, publicly accessible product URL.
imageUrl: The primary image URL used in recommendation cards.

For multilingual stores, send the URL for the same language and market context used by the visitor. If image transformations are handled by a CDN, use a stable image service URL rather than a temporary signed URL.

Taxonomy

Category and brand information is among the most useful product context for an ecommerce recommender. Send taxonomy as structured values rather than as one long display string.

categories: The product’s category or category path.
categoryIds: Stable category identifiers, when available.
brand: The normalized brand name or brand ID.
tags: Curated merchandising tags that describe meaningful attributes.

Keep category values consistent. For example, do not alternate between “Women > Shoes > Boots”, “Women’s Boots”, and a numeric category ID unless each is intentionally stored as a separate property.

Commercial properties

Recommendations are often filtered by commercial rules, so the catalog should include the values required to decide whether an item is eligible at request time.

price: The current numeric selling price.
regularPrice: The non-sale price, if price comparison is displayed.
currency: The currency associated with the price.
onSale: A boolean indicating whether the product is currently discounted.
stockStatus: A normalized value such as instock, outofstock, or onbackorder.
purchasable: A boolean representing whether the current storefront can accept a purchase.
visibility: A normalized catalog visibility state.

Price should be sent as a numeric property, not as a formatted string such as “$49.99”. Formatting belongs in the storefront. If a store operates across currencies or markets, decide whether each market receives its own catalog, market-specific item properties, or request-time filtering.

Attributes and variants

Product attributes are valuable when they influence customer choice. Good examples include color, size, material, compatibility, gender, fit, dietary classification, and technical specifications.

Normalize attribute names and values before sending them. “Black”, “black”, and “BLK” should not become three unrelated values unless the distinction is intentional. Multi-valued attributes can be represented as a set where the integration and catalog schema support that type.

For variable products, choose one of these patterns:

Parent-only catalog: Send the parent product and aggregate variation information into properties such as available colors, available sizes, and minimum price.
Variation catalog: Send each purchasable variation as an item and include a parent product ID so the frontend can group results.
Hybrid catalog: Use parent products for discovery recommendations and variation data for availability or selection logic.

The correct pattern depends on how interactions are tracked. If an add-to-cart event contains a variation ID but recommendations are generated for parent product IDs, the integration needs an explicit mapping between those identifiers.

Useful custom properties

Custom fields should be included when they support recommendation quality, filtering, or merchandising decisions. Examples include:

season or collection
product type
compatibility model or device family
estimated delivery group
subscription eligibility
membership tier eligibility
environmental or dietary labels
margin band or internal merchandising segment

Do not send confidential supplier data, customer-specific pricing, internal notes, or unrestricted operational metadata. A property that is not used by a model, filter, or presentation layer usually does not belong in the recommendation catalog.

Example product payload

The exact request wrapper depends on the Recombee client library and synchronization process. The item properties themselves should follow a stable, typed schema similar to this:

{
  "id": "product-1842",
  "name": "Waterproof Hiking Jacket",
  "description": "Lightweight waterproof jacket for three-season hiking.",
  "sku": "HJ-1842-BLK",
  "url": "https://example.com/product/waterproof-hiking-jacket/",
  "imageUrl": "https://cdn.example.com/images/hiking-jacket.jpg",
  "categories": ["Clothing", "Outdoor", "Jackets"],
  "brand": "North Ridge",
  "tags": ["waterproof", "breathable", "hiking"],
  "price": 129.95,
  "currency": "USD",
  "onSale": false,
  "stockStatus": "instock",
  "purchasable": true,
  "colors": ["black", "blue"],
  "materials": ["recycled polyester"],
  "season": "all-season"
}

Use the property types supported by the Recombee catalog schema consistently. A price should remain numeric, availability should remain boolean or a controlled string, and multi-valued fields should use a consistent set or array representation supported by the integration.

Properties that should usually stay out

Avoid sending fields that are volatile, duplicated, or unrelated to recommendation decisions. Common examples include formatted HTML fragments, admin edit URLs, import timestamps, WordPress post metadata, image attachment IDs, and every raw custom field collected by a plugin.

Also avoid using a rapidly changing property as a permanent product identity. Price and stock can change frequently; the item ID must not.

Keep the catalog synchronized

WooCommerce webhooks, action hooks, or a scheduled synchronization process should update Recombee when a product is created, edited, unpublished, repriced, or removed. A catalog export that runs only once will quickly produce invalid recommendations.

At minimum, test these events:

new product publication
product title, category, or attribute changes
price and sale-status changes
stock transitions to and from out of stock
product deletion or catalog exclusion
variation creation and removal

Before production launch, inspect a sample of synchronized items and verify property types, URLs, image availability, taxonomy values, and stock eligibility. Then compare the identifiers in view, click, cart, and purchase events with the identifiers in the catalog. Consistent product properties are useful only when the interaction stream uses the same product model.

Table of contents :