Separate eligibility from ranking
Product availability should influence search results, but it should not be treated as a substitute for an eligibility rule. In a WooCommerce storefront, an unavailable product may need to be excluded entirely from search, while a product with limited stock, a delayed fulfillment date, or an active backorder policy can remain eligible and receive a lower ranking score.
A practical search pipeline uses two decisions:
- Eligibility: Can this product be shown or purchased in the current channel, region, and customer context?
- Ranking: Among eligible products, how strongly should availability influence the order?
Keeping these decisions separate prevents a highly relevant but unavailable product from outranking products that customers can actually buy.
Define a normalized availability model
WooCommerce exposes several inventory-related concepts, including stock_status, stock_quantity, manage_stock, backorders_allowed, and catalog visibility. Agencies should normalize these values before sending them to Vespa rather than making the rank profile understand every WooCommerce state.
For example, a feed can derive the following fields for each searchable product or purchasable variation:
availability_state: a string such asin_stock,low_stock,backorder, orout_of_stock.availability_score: a numeric value used by ranking, such as 1.0 for in-stock, 0.6 for low-stock, 0.35 for backorder, and 0.0 for unavailable.availability_eligible: a boolean or integer used for filtering.stock_quantity: an optional numeric attribute for inventory-aware business rules.available_from: an optional timestamp for products that are not immediately available.
The exact score values are business policy, not universal constants. A backorder product might deserve a score close to an in-stock product if the store has reliable fulfillment estimates. Conversely, a product with one remaining unit may need a lower score if inventory accuracy is poor.
Store ranking features in the Vespa schema
Availability values that are used for filtering or ranking should be indexed as attributes. Attributes are available to ranking expressions without requiring the full document text to be retrieved.
field availability_state type string {
indexing: attribute | summary
}
field availability_score type double {
indexing: attribute | summary
}
field availability_eligible type int {
indexing: attribute | summary
attribute: fast-search
}
field stock_quantity type int {
indexing: attribute | summary
}
field available_from type long {
indexing: attribute | summary
}
Use fast-search on an attribute when the field will commonly be used as a filter. The state and score can also be included in summaries if the application needs to display availability information without looking it up in WooCommerce.
For products with variations, decide where availability belongs before creating the schema. If customers search and purchase variations independently, index each variation as its own Vespa document. If the storefront displays a parent product, calculate parent availability from its purchasable children and retain the best or most relevant variation information for presentation.
Use availability in a rank profile
A rank profile can combine the normal text or semantic relevance score with the normalized availability score. The availability weight should be configurable through a query feature so that different storefronts, channels, or experiments can use different policies.
rank-profile availability_boost inherits default {
inputs {
query(availability_weight): double
}
first-phase {
expression: nativeRank + query(availability_weight) * attribute(availability_score)
}
}
This example assumes that the inherited profile already produces a meaningful nativeRank. For a hybrid search setup, the base expression could instead combine text relevance, vector closeness, business signals, and availability:
rank-profile hybrid_availability inherits default {
inputs {
query(availability_weight): double
}
first-phase {
expression: 0.65 * bm25(title) + 0.35 * closeness(field, embedding) + query(availability_weight) * attribute(availability_score)
}
}
Do not select weights only by inspecting a few result pages. Use historical search and conversion data, then compare metrics such as click-through rate, add-to-cart rate, conversion rate, zero-result rate, and the percentage of shown products that cannot be purchased.
Filter products that cannot be shown
If an unavailable product must never appear, apply the rule in the query rather than relying on a ranking penalty. A numeric eligibility attribute makes the rule explicit:
select * from product where availability_eligible = 1 and userQuery()
The application can then request the relevant profile and weight:
ranking=availability_boost&ranking.features.query(availability_weight)=0.25
Use ranking-only treatment for states that are still commercially valid, such as low stock or backorder. For example, an agency might set availability_eligible to 1 for both in-stock and backorder products, while assigning the backorder state a lower score. Regional inventory can be handled by maintaining one availability attribute per fulfillment region or by writing the region-specific value into the query document used for that request.
Keep availability synchronized with WooCommerce
Availability is volatile. A nightly product export is not sufficient when the ranking signal depends on stock changes. A robust integration normally combines:
- Initial indexing: Export products, variations, visibility settings, stock status, and derived availability fields.
- Event-driven updates: Send a targeted Vespa document update when stock, backorder policy, publication status, or variation availability changes.
- Periodic reconciliation: Re-export the catalog at an interval appropriate for the business to correct missed webhooks, failed jobs, or manual database changes.
- Operational monitoring: Track update latency, failed document operations, stale timestamps, and the number of Vespa documents whose availability differs from WooCommerce.
WooCommerce agencies should also account for changes made outside the normal product editor, including imports, ERP synchronizations, warehouse reservations, refunds, and order cancellations. The source of truth may be WooCommerce or an inventory system connected to it; the Vespa feed should consume the authoritative result rather than infer stock from order events alone.
Handle inventory race conditions
Search results are not a reservation mechanism. A product can be in stock when Vespa ranks it and become unavailable before checkout. The checkout service must validate current inventory independently and return a clear customer-facing response when the item can no longer be purchased.
For high-volume stores, include an availability update timestamp in the document and monitor the age of that value. A stale availability signal can be more harmful than a conservative ranking penalty. If the feed is delayed beyond an agreed threshold, the application can reduce the availability weight, exclude stale products, or fall back to a real-time inventory check for the first page of results.
Test the ranking behavior
Create test queries where textual relevance is held constant and only availability changes. The expected behavior should be documented for each state:
- An exact-match product that is out of stock is excluded when the business rule requires purchasable results only.
- An in-stock product and a backorder product with similar relevance are ordered according to the configured availability weight.
- A low-stock product is not automatically removed unless the catalog policy says that low stock is unavailable.
- A parent product is not shown as available when every purchasable variation is unavailable.
- A product with an outdated inventory timestamp follows the stale-data fallback policy.
Use Vespa ranking tests or representative query snapshots to verify score ordering after schema and rank-profile changes. Also test the WooCommerce-to-Vespa update path by changing stock status, enabling backorders, publishing a variation, and cancelling an order. Ranking changes should be observable in the search response and in the feed monitoring logs.