Recommendation logic should be designed around the location where the recommendation appears, not only around the products being recommended. A product-page carousel, an empty-cart message, a mini-cart cross-sell, and a post-purchase email may all use the same catalog, but they serve different customer intents and have different space, timing, and conversion constraints.
For WooCommerce agencies, the most reliable way to manage this difference is to give every recommendation placement its own scenario. A scenario defines the purpose of the placement, the eligible products, the ranking rules, the exclusions, the fallback behavior, and the metrics used to evaluate it.
What a recommendation scenario controls
A placement is the visible location in the storefront. A scenario is the complete decision model behind that location. Treating the two as separate makes it possible to reuse recommendation components without accidentally reusing unsuitable business rules.
A scenario commonly includes:
- Context: the page, template, customer state, cart contents, or event that triggered the recommendation.
- Objective: increasing basket value, helping product discovery, reducing purchase uncertainty, or recovering an abandoned cart.
- Candidate source: related products, frequently bought together products, category products, recently viewed products, or a curated collection.
- Eligibility rules: stock status, catalog visibility, product type, price range, category, shipping constraints, and customer permissions.
- Ranking rules: relevance, purchase frequency, margin, inventory position, personalization signals, or a weighted combination.
- Exclusions: products already in the cart, products already purchased, incompatible variations, and products that duplicate the current item.
- Fallback: what should appear when the primary candidate set does not contain enough products.
- Measurement: the impression, click, add-to-cart, conversion, and revenue events attributed to the scenario.
Why one global scenario creates poor recommendations
A global rule such as “show products related to the current product” is easy to install but usually too broad for a mature store. The same recommendation may be relevant on a product page and inappropriate in the cart.
For example, a product-page placement can introduce compatible accessories because the shopper is still evaluating the main product. A cart placement should usually prioritize products that can be added quickly without changing the customer’s decision. Showing another primary product from the same category may distract from checkout rather than increase order value.
Context also changes the meaning of product signals. A product frequently purchased with a camera may be an excellent product-page recommendation, but it may be a poor recommendation after the customer has already added that accessory. The cart scenario should remove it and select the next suitable item.
Define scenarios by shopper intent
Start by documenting the intent of each placement before choosing an algorithm. A useful scenario name should describe both the location and the job it performs.
- Product page: Complete the setup. Recommend compatible accessories, consumables, or service plans for the viewed product.
- Product page: Explore alternatives. Recommend comparable products when the shopper is evaluating options rather than building a bundle.
- Cart: Increase basket value. Recommend low-friction additions that complement the current cart.
- Mini-cart: Add one more item. Use a compact, fast-loading recommendation with a clear relationship to the current cart.
- Category page: Continue browsing. Recommend popular or personalized products within the active category.
- Thank-you page: Prepare for the next purchase. Recommend replenishment products, warranties, memberships, or products related to the completed order.
- Email: Recover or extend the purchase journey. Use a stable product set that can be rendered reliably outside the active storefront session.
These names help the development and merchandising teams discuss behavior precisely. “The cart scenario is underperforming” is more actionable than “recommendations are not working.”
Build a scenario contract
Before implementation, create a contract for each scenario. The contract should be specific enough that an agency can build automated tests and a merchant can approve the intended behavior.
For a “Complete the setup” scenario on a product page, the contract might be:
- Use the viewed product as the primary context.
- Prefer products explicitly marked as compatible with the viewed product.
- Exclude the viewed product, unavailable products, hidden products, and products already in the cart.
- Do not recommend a product from an incompatible voltage, size, platform, or model family.
- Return up to four products on desktop and up to two visible products on mobile.
- Fall back to category-level accessories only when no compatible products exist.
- Track impressions, clicks, add-to-cart events, and orders containing a recommended product.
The contract should also state what happens when product data is incomplete. If compatibility is not known, silently treating every product as compatible can create customer support issues. A safer rule is to exclude uncertain products or use a clearly labeled curated fallback.
Separate candidate generation from ranking
Each scenario should have two distinct stages. Candidate generation determines which products are allowed into consideration. Ranking determines the order in which eligible products are displayed.
For example, a cart scenario for a coffee equipment store might generate candidates from products tagged as filters, cleaning supplies, and storage accessories. It could then rank those candidates using stock availability, cart compatibility, historical attach rate, gross margin, and the number of days since the customer last purchased the item.
This separation prevents a popular but irrelevant product from winning simply because it has strong overall sales. It also makes debugging easier: the team can determine whether a product was never eligible or was eligible but ranked too low.
scenario: cart_add_on
context: current_cart
candidates:
include_categories:
- coffee-filters
- cleaning-supplies
exclude:
- cart_items
- out_of_stock
- subscription_only
ranking:
- cart_compatibility
- attach_rate
- inventory_priority
fallback: store_curated_cart_add_ons
limit: 4
Use placement-specific exclusions
Exclusions are often more important than the recommendation algorithm. They prevent repetition, reduce distraction, and protect the customer from unsuitable offers.
A product-page scenario may exclude the current product and its exact variations but allow products already viewed during the session. A cart scenario should normally exclude everything already in the cart and may also exclude products that would create a duplicate subscription or violate a bundle rule.
A post-purchase scenario should use the completed order as context and exclude the products purchased in that order. It may also apply a replenishment interval so that consumables are recommended at a useful time rather than immediately after checkout.
In WooCommerce, implement these checks against current product and cart data rather than relying only on a cached recommendation response. A cached product list can become invalid when inventory, visibility, pricing, or cart contents change.
Account for WooCommerce product and cart states
WooCommerce stores frequently contain simple products, variable products, subscriptions, bundles, virtual products, and products with complex shipping rules. A scenario must define which product types it supports and how variations are handled.
- For variable products, decide whether to recommend the parent product or a specific purchasable variation.
- For products requiring configuration, link the recommendation to the product page instead of attempting an incomplete one-click add-to-cart action.
- For subscription products, avoid mixing one-time and recurring products unless the checkout and pricing behavior are clearly communicated.
- For bundled products, prevent recommendations that duplicate components already included in the bundle.
- For products with shipping restrictions, filter recommendations using the customer’s known destination when that information is available.
- For private, draft, password-protected, or catalog-hidden products, apply the same visibility rules used by the storefront.
Eligibility should be checked at request time or at the point of rendering. At minimum, verify that the product is purchasable, visible, assigned to the intended catalog context, and still available under the current pricing and stock rules.
Give each scenario its own metrics
Do not evaluate every placement with one blended click-through rate. A product-page scenario may be successful when it generates assisted add-to-cart events, while a cart scenario should usually be judged by incremental order value and the rate of additional items added after exposure.
Useful scenario-specific metrics include:
- Product page: recommendation click rate, add-to-cart rate, attach rate, and revenue per product-page session.
- Cart and mini-cart: incremental items per order, incremental revenue, margin contribution, and checkout completion rate.
- Category page: product detail views per session, category depth, and progression to cart.
- Thank-you page: immediate secondary purchase rate, coupon usage, and repeat-purchase revenue.
- Email: delivered-message click rate, landing-page conversion, unsubscribe rate, and revenue attributed within the defined window.
Record a stable scenario identifier with each impression and conversion event. For example, product_complete_setup_v2 and cart_add_on_v1 should remain distinguishable in analytics, even if both use the same recommendation service.
Prevent recommendation conflicts
A page can contain multiple placements, especially when a theme, a page builder, and a plugin each add their own blocks. Without coordination, the customer may see the same product several times or receive contradictory messages.
Use a request-level or session-level suppression list when appropriate. After a product is displayed in one high-priority placement, another placement may suppress it or lower its rank. However, do not apply universal suppression blindly. A product shown in a product-page accessory block may still be appropriate in a cart scenario if it was not purchased or added.
Define placement priority explicitly. For example:
- Show compatibility-critical recommendations on the product page.
- Show cart-specific add-ons in the cart and mini-cart.
- Use a broader fallback only when higher-priority scenarios return too few eligible products.
Test scenarios with real storefront states
Scenario testing should cover more than a logged-in customer viewing a product. Build test cases around the states that alter eligibility and ranking.
- A guest customer with an empty cart.
- A customer with one product in the cart.
- A customer whose cart contains a product already present in the recommendation candidate set.
- A customer viewing an out-of-stock or backorder product.
- A customer using a different currency, tax region, or shipping destination.
- A customer with a subscription product in the cart.
- A returning customer with prior orders that affect replenishment recommendations.
- A mobile visitor where the placement has a smaller display limit.
For each test, verify the candidate set, ordering, product visibility, price display, add-to-cart behavior, tracking payload, and fallback response. Also test cache boundaries. A page cache must not expose one customer’s cart-aware recommendations to another customer.
Make scenario ownership explicit
Assign ownership for the rules, data, implementation, and reporting. Merchants may own compatibility tags and curated fallback products. Developers may own eligibility filters, caching, and event tracking. Analysts may own attribution windows and experiment design.
Store the scenario identifier and version in configuration rather than embedding an anonymous rule in a template. This allows an agency to change ranking weights, compare versions, and identify which logic produced a recommendation after a conversion or support incident.
When every placement has a defined scenario, recommendation work becomes easier to implement and audit. The product page can optimize for relevance, the cart can optimize for useful additions, and post-purchase placements can optimize for the next appropriate interaction without forcing every storefront location into the same decision model.