Product ranking should reflect more than a product’s catalog relevance. For a WooCommerce store, recent sales, product views, add-to-cart activity, and completed orders provide useful evidence about what shoppers are likely to buy. Vespa can combine those signals with text relevance, category filters, price, inventory, and business rules in one ranking expression.
Choose signals that represent shopper intent
Start by defining the events that will be exported from WooCommerce and the time windows that matter to the business. Typical product-level signals include:
- Orders: completed orders containing the product, preferably split into seven-day, thirty-day, and lifetime totals.
- Units sold: useful when one order can contain multiple units.
- Product views: a denominator for estimating demand and conversion.
- Add-to-cart events: a stronger intent signal than a view.
- Conversion rate: completed orders or units divided by qualified views.
- Recency: a decay factor that prevents old sales from dominating current results.
- Inventory status: an eligibility constraint or ranking boost, depending on the store’s policy.
Use completed or paid WooCommerce orders for sales signals. Exclude cancelled, failed, and refunded orders according to the store’s reporting rules. Keep the event definitions consistent across products; a conversion rate calculated from product-detail views should not be compared directly with one calculated from all search impressions.
Export ranking features with the product document
For operational simplicity, calculate stable aggregates in the WooCommerce data pipeline and store them as Vespa product fields. A product document might contain fields such as:
{
"id": "sku-1842",
"title": "Waterproof Hiking Jacket",
"sales_7d": 18,
"sales_30d": 74,
"views_30d": 1460,
"add_to_cart_30d": 119,
"conversion_rate_30d": 0.0507,
"sales_velocity": 0.82,
"inventory_available": 23,
"updated_at": 1717000000
}
Use numeric Vespa fields that are available as attributes when they participate in ranking. Attributes are kept in memory and can be evaluated efficiently during matching and ranking. A simplified schema could look like this:
field sales_30d type int {
indexing: attribute | summary
}
field conversion_rate_30d type double {
indexing: attribute | summary
}
field sales_velocity type double {
indexing: attribute | summary
}
field inventory_available type int {
indexing: attribute | summary
}
If the store has a large catalog, avoid updating every product for every individual event. Aggregate WooCommerce events in a scheduled job or stream processor, then send partial document updates to Vespa. The update process should be idempotent and should record the aggregation window and calculation timestamp so stale metrics can be detected.
Use Bayesian smoothing for conversion rate
Raw conversion rates are unstable for products with little traffic. A product with one order from two views has a measured conversion rate of 50 percent, but that is weaker evidence than a product with 500 orders from 10,000 views.
A practical smoothed rate is:
smoothed_rate = (orders + prior_views * store_conversion_rate)
/ (views + prior_views)
For example, if the store conversion rate is 3 percent and the prior represents 100 views, a product with two orders and ten views is scored using 102 effective views rather than treating the 20 percent raw rate as conclusive. Calculate this value in the WooCommerce aggregation layer, or express the calculation in a Vespa rank profile when the required fields are available.
Combine relevance with sales and conversion evidence
A useful ranking function should preserve search relevance while allowing performance signals to influence ordering. Normalise signals before combining them. Logarithmic transforms are useful for counts because they reduce the effect of very large catalogs or bestseller outliers.
For example, the following profile uses query-level weights and product attributes. The exact weights should be tuned with offline judgments and production metrics rather than copied unchanged between stores.
rank-profile sales_conversion inherits default {
inputs {
query(w_text): 1.0
query(w_sales): 0.35
query(w_conversion): 0.45
query(w_velocity): 0.20
}
first-phase {
expression: query(w_text) * nativeRank
+ query(w_sales) * log(1 + attribute(sales_30d))
+ query(w_conversion) * attribute(conversion_rate_30d)
+ query(w_velocity) * attribute(sales_velocity)
}
}
In this example, nativeRank supplies the lexical and field-based relevance score, while the query features control the influence of commercial signals. The application can select the profile and send the weights with the query, or the rank profile can define fixed defaults.
When scores have very different ranges, use bounded or normalised features. For example, conversion rate may be between zero and one, while sales counts may be in the thousands. Without normalisation, a count can overwhelm text relevance even when its configured coefficient appears small.
Separate eligibility from ranking
Do not use a ranking boost to solve an eligibility problem. If an out-of-stock product must never appear for a particular shopping experience, filter it in the query or enforce the rule before ranking. If backorders are permitted, keep the product eligible and apply a business-specific penalty or boost.
A Vespa query can combine a user’s text query with structured constraints. For example, the application can send a YQL expression that restricts results to a product category and available inventory, while the rank profile determines the order:
yql=select * from product where \
({"targetNumHits":100}userInput(@query)) and \
category_id contains "jackets" and \
inventory_available > 0
Use the query parser and escaping rules appropriate for the deployed Vespa application. Category, brand, price, stock, and visibility filters should normally be represented as structured fields rather than embedded in free text.
Account for freshness and promotions
Sales signals are historical. A product that sold well last year may be less useful than a newly launched product with strong recent engagement. Store separate time windows, such as seven-day and thirty-day sales, then blend them or use a freshness multiplier.
One simple approach is to export a bounded sales_velocity feature that compares recent sales with the product’s longer-term baseline. Another is to apply a recency factor based on the timestamp of the latest event. Keep promotional boosts separate from organic performance signals so merchandising teams can audit why a product ranked highly.
For example, a promotion can be passed as a query feature or maintained as a document attribute:
first-phase {
expression: nativeRank
+ 0.30 * log(1 + attribute(sales_30d))
+ 0.40 * attribute(conversion_rate_30d)
+ 0.15 * attribute(sales_velocity)
+ 0.25 * attribute(campaign_boost)
}
Limit campaign values to a documented range, such as zero through one, and require an expiration timestamp. Otherwise, an old campaign value can permanently distort organic ranking.
Support cold-start products
New products have no sales history, so a ranking model based only on conversions will systematically bury them. Use catalog relevance, category popularity, brand affinity, price competitiveness, and a small exploration allowance for products with insufficient observations.
A common policy is to apply performance signals only after a minimum number of qualified views, then gradually increase their weight as evidence accumulates. Alternatively, use the smoothed conversion rate described above and add a controlled exploration term for products that meet quality and inventory requirements.
Measure ranking quality in WooCommerce
Track ranking outcomes by query, category, device, and traffic source. Useful metrics include click-through rate, add-to-cart rate, checkout initiation, completed-order rate, revenue per search, and zero-result rate. Measure both the immediate interaction and the eventual order because a high click-through rate can coexist with poor commercial performance.
Keep a test set of representative WooCommerce queries with expected product judgments. Compare a text-only profile against the sales-and-conversion profile using offline evaluation before enabling the new profile for all traffic. Then use an A/B test with guardrails for revenue, conversion, latency, and stock-related complaints.
Inspect ranking explanations and representative result sets when a product unexpectedly moves. Common causes include a stale aggregation job, a denominator change in view tracking, a refunded-order policy change, or an unbounded promotional feature. Store the feature timestamp and aggregation window with the product data so these issues can be diagnosed without reconstructing the entire event history.