Boosting

Product Boost Level

Product Boost Level is a simple priority field you add to your Item Feed. It gives you direct control over which products get more visibility across search results, recommendations, and category pages — without needing to configure complex merchandising rules.

Set a number from 1 to 5 on any product: 1 means the product ranks naturally, 5 means it gets maximum promotion. The boost works alongside Perselio's relevance and personalization algorithms, not against them — a boosted winter coat won't appear in summer swimsuit searches.

If you don't set a value, every product defaults to level 1. This lets you influence product visibility in minutes by updating a single field in your existing catalog export, with no dashboard configuration or technical setup required.

Boost Levels

Level	Name	Description
1	Default	No boost applied. Product ranks naturally based on relevance, personalization, and behavioral signals. This is the default value — if the field is omitted from the catalog feed, level 1 is assumed.
2	Low	Gentle boost. Product receives a slight ranking advantage over non-boosted items. Use for products you'd like to subtly favor without disrupting natural relevance order.
3	Medium	Moderate boost. Product is noticeably promoted in search results and recommendations. Suitable for seasonal highlights, new arrivals, or products with a current marketing campaign.
4	High	Strong boost. Product is pushed significantly higher in rankings. Use for strategic priorities — high-margin products, exclusive items, or key promotional targets.
5	Maximum	Strongest possible boost. Product is aggressively promoted toward top positions in all surfaces (search, recommendations, category listings). Reserve for your most important business priorities — flagship launches, limited-time offers, or contractual obligations.

Pinning

Force specific products to appear at exact positions in any recommendation carousel or widget — regardless of what the AI model would otherwise rank first.

What is Pinning?

By default, Perselio's recommendation engine ranks products automatically based on user behavior, relevance, and business rules. Pinning lets you override this ranking for specific products, guaranteeing they appear at a position of your choosing.

This is useful when you want to promote a campaign product, highlight a new arrival, or surface hand-curated selections — while still letting the AI fill the remaining slots dynamically.

Pins are applied after all AI ranking and reranking is complete. The rest of the list continues to be personalized and dynamic.

Common Use Cases

Promotional highlights

Pin campaign products or bundles to position 1–2 in a "Quick Picks" or "Featured" carousel to guarantee visibility during a sale or product launch.

Curated alternatives

On a product detail page, pin hand-selected alternatives at the top of the "Similar products" widget — ideal for catalog curation where editorial control matters.

Catalog-driven alternatives

Automatically pin items from a product's "alternative products" field in your catalog feed. These are placed first without any manual configuration per product.

Context-specific overrides

Define different pinned items for specific context products. For example, when a customer views product A, always show products X and Y first.

How It Works

Pinned items are configured per recommendation scenario (the model powering a widget). You specify a product ID and the exact position it should appear at — positions are numbered from 1 (first slot).

Position Behavior

Concept	Behavior
Position numbering	Starts at 1 (first visible slot in the widget)
Order	Positions must be unique and listed in ascending order
Non-pinned slots	Filled dynamically by the AI model
Duplicates	If a pinned item already appears in AI results, it is moved to the pinned position — not shown twice
Fallback	If the model returns fewer items than the total widget size, trailing pin slots may be skipped

Context-Awareness

Pins can be configured either globally (apply to all users and contexts) or for a specific context product (apply only when a user is viewing a particular item):

Mode	When it applies
Default pins	Applied whenever no context-specific pins are defined for the viewed product
Per-product pins	Applied only when the user is viewing the specified product

Configuration Options

There are two ways to set up pinning — choose the one that fits your workflow:

Option 1 — Manual pin list

Provide an explicit list of product IDs and their target positions. This gives you full control and works for any scenario.

Best for: promotional campaigns, quick picks, a small number of hand-curated overrides.

Option 2 — Catalog-driven pins (alternatives field)

Enable automatic pinning from your product catalog. Each product's alternative products field (set in your feed) is used to pin alternatives at the top of the widget for that product, in the order they appear in the field.

Best for: large catalogs where alternative products are already managed in the feed, Shoptet stores using alternativeProducts.

Manual pin lists and catalog-driven pins are mutually exclusive — you can use one or the other per scenario, not both at the same time.

Important Notes

Topic	Detail
Scope	Pinning is configured per recommendation scenario (model), not per page or widget placement. The same pinned items appear wherever that scenario is used.
AI ranking still applies	Unpinned slots continue to be ranked and personalized by the AI model normally.
Unavailable products	If a pinned product is not in the catalog, a warning is logged and the product may still be recommended if recoverable.
Pin limit	There is no hard limit on the number of pins, but pins beyond the widget's visible slot count have no effect.
Updates	Changes to pin configuration require a model retrain/republish to take effect.

Setting Up Pinning

Pinning is configured by the Perselio team as part of your scenario setup. To request pinning for a widget:

Identify the widget / recommendation scenario where you want pins.
Provide the product IDs to pin and their desired positions (1-based).
Specify whether pins should apply globally or per context product.
Alternatively, ensure your product feed includes the alternative products field if using catalog-driven pins.