Blender Allocation

How Promoted's allocation system achieves optimal placement of listings, customized to your marketplace

In search and native ads delivery, Allocation is the process of deciding whether and where to insert each potential listing into the search, feed, or discovery results. Promoted's comprehensive allocation system is called Blender. This document details the components of Blender and shows an example Blender code configuration.

Promoted's Blender allocation system takes a set of search and ads candidates and outputs an optimized ordering.

Promoted's Blender allocation system takes a set of search and ads candidates and outputs an optimized ordering, unique to the user, context, and query.

Unified configuration system. Blender unifies search, feed, and native ads allocation to achieve optimal placement of listings. Blender allows Promoted to blend content, control diversity, and achieve custom business goals (e.g., new seller traction). All allocation rules and decisions are combined into this unified configuration system.

Marketplace-specific controls. Promoted works collaboratively with each marketplace to configure Blender, no matter whether the marketplace needs search, ads, or unified search and ads.

Components of Blender

Each component of Blender factors into the ordering of the listings in allocation. This list is not exhaustive; Promoted implements custom features on a per-client basis.

ComponentData typeDescription
Quality scoreFloatA combination of click and conversion probabilities unique to this user, context, and query.
DistanceFloatThe distance to the user or a specified location, if applicable.
Keyword matchingBooleanWhether the title of the listing matches a specified number of words in the query (or any number of words for a query in quotation marks).
Semantic relevanceFloatThe semantic relevance of the listing (in terms of the topic or meaning) to the search query, regardless of matching keywords.
PenaltyFloatA negative score that forces content lower in the results, potentially due to poor quality, bad seller reviews, high return rates, shipping delays, and other marketplace-specific penalties.
Custom goalsBooleanCustomizations relating to specific business goals, such as new seller traction, revenue maximization, and pinned items.
Insertion bid (native ads only)FloatA comprehensive monetary measure of both the advertiser's and platform's vested interests in whether to "boost" a specified listing.


Quality score

The quality score, calculated from Promoted's model-generated probabilities, contributes to the ranking of listings. These probabilities are generated for every query, for every potential listing, specific to this user and context.

User actions

Some of these probabilities represent the likelihood of the user performing specific actions, like click or purchase.

Model-generated action probabilityDefinition
p(click)Probability of a click occurring on a given listing (unique to this user, context, and query)
p(purchase | click)Probability of a purchase on the listing given that the user clicked on it, (unique to this user, context, and query)
p(purchase | impression)Probability of a purchase on the listing given that the user saw it, (unique to this user, context, and query)
p(purchase confirmed | click)Probability that the purchase is successfully completed (e.g., not canceled, returned) given that the user clicked on it, (unique to this user, context, and query)

Long-term revenue optimization

Promoted also generates probabilities and expected values to represent long-term revenue optimization.

Model-generated business value or probabilityDefinitionNotes
E(GSV|purchase) or E(revenue|purchase)Expected GSV or revenue of a purchaseThis value is defined differently depending on the client's marketplace and internal definition of GSV.
p(bad|purchase)Probability of “bad” purchaseA bad outcome of a purchase is client-specific and may include cancellations, returns, or fraud.
p(repeat|purchase)Probability of repeat purchaseA repeat purchase is more than one purchase on the same item by the same user.

Combined formula

These probabilities are combined into a formula to generate the score. The formula is refined over time, and could be as simple as p(click) * p(purchase | click), or may contain additional variables, weights, and filters.

📘

The quality score is just one part of a comprehensive allocation system.

Blender does not use a single, preset "goodness" score to rank listings. The quality score is dynamic and unique to each user, context, and query, and is used in combination with marketplace-specific ranking techniques. This may include keyword matching, distance, semantic relevancy, and business goals.

Custom slots in search results

Promoted offers the ability to customize specific positions in the ranking order. Each position in the results may use a different allocation "rule" that determines which listing will be chosen for that particular slot. The positioning may be determined deterministically or probabilistically.

CustomizationPurposeCategory
Boosted listingsPromoted's implementation of sponsored search results.Native ads
Pinned listings"Pin" the best eligible item to the top of the search results. This can be useful for bumping up the most relevant item that the customer "liked" or "favorited" earlier.Organic search
Challenger slotsA customizable position in the ranking that enforces a particular rule, guided by a business objective. For example, marketplaces can use this to promote new items so they'll gain initial tractionOrganic search
Maximizer slotsA customizable position in the search results that maximizes a quantitative objective, such as revenue. Functionally similar to the challenger.Organic search

👍

For each customizable slot, Promoted selects the best listings out of a group of eligible listings.

If multiple items are eligible to be placed in boosted, pined, challenger, or maximizer slots, Promoted will default to the standard search ranking to choose the best within that group (based on click/conversion predictions, keyword match, distance, and other marketplace-specific features).

If no eligible items exist (e.g., they were filtered out by retrieval or by Promoted's system), then the slot will be bypassed and Promoted will default to standard search ranking.



Example configuration

An example Blender configuration is shown below, with some constants and variables obfuscated for confidentiality. The actual ranking is decided by the SORT() allocation rules. Each rule is followed in order until the LIMIT() is reached, if applicable. This means the first few listings ranked may follow a different rule from the following ones.

// Values are calculated to be used in allocation rules
// Based on the features in each listing
"clean_long_quote_match = IF(FEATURE(CLEAN_QUERY_TITLE_MATCH) > 3, IF(FEATURE(CLEAN_QUERY_NUM_WORDS) > 3, 1, IF(FEATURE(QUERY_HAS_QUOTES) > 0, 1, 0)), 0);",  
"title_query_substring = IF(FEATURE(\"titleQueryWordsSubstring\") > 2, 1, 0);", 

// Model predictions
"p_click = FEATURE(PREDICTION_NAVIGATE);",
"p_purchase = FEATURE(PREDICTION_POST_CLICK_PURCHASE);",

"score = p_purchase * p_click",

// Allocation rules combine the above values to sort the listings
// In the ranking, prioritize substring match then score (in case of ties)
"SORT(clean_long_quote_match, title_query_substring, score);"  

Boosted (sponsored) listings

Using Promoted for both organic search and native ads unifies and simplifies your system, ensuring results are relevant and optimal. When native ads are implemented with organic search and feed, Promoted calls them boosted listings. In the rules, Promoted first filters out listings that are not eligible to be a native ad (some listings may only be eligible for organic search). Eligibility is determined by the seller and sent to Promoted via the Delivery request, just like other associated metrics.

// New boosted value and score
"boosted = IF(FEATURE(\"adsEnabled=true\") == 1, IF(FEATURE(\"boosted_profile_config.is_boosted\") == 1, 1, 0), 0), 0), 0);",
"boosted_score = IF(boosted == 1, p_click * FEATURE(\"boosted_profile_config.bid_value\"), 0);",

"SELECT<BOOSTED> WHERE(boosted > 0) SORT(clean_long_quote_match, title_query_substring, boosted_score, score) ABSOLUTE_POSITION(1);",

After filtering, the SELECT<BOOSTED> rule uses a boosted_score that combines model-generated probabilities with ad-specific features like the bid value. In the example, the SELECT<BOOSTED> rule places an ad into the second slot of the results (as long as an eligible listing exists). Otherwise, the listings are sorted as described previously.

Pinned listings (optional)

Marketplaces may want to "pin" a particular item (not an ad) at the top of results — or select from a group of eligible (or "pinnable") items. This can be useful for bumping up an item the customer "liked" or "favorited" earlier. This can be performed by setting an eligibility value as a feature in the content item (e.g., pin_to_front). Promoted will then filter the retrieval items that have this value set to true, and select the best one.

// If listing is eligible to be pinned, set pinned to true
"pinned = IF(FEATURE(\"pin_to_front\") > 0, 1, 0);"

// The third search result is the challenger, if one exists
"SELECT<PINNED> WHERE(pinned == 1) SORT(clean_long_quote_match, title_query_substring, score) ABSOLUTE_POSITION(0)"

// All results except for the challenger slot follow the standard rule
// In the ranking, prioritize substring match then score (in case of ties)
"SORT(clean_long_quote_match, title_query_substring, score);" 

Challenger slots (optional)

The challenger slot is a position in the ranking that enforces a particular rule. Whereas boosted slots are paid native ads, challenger slots achieve particular business objectives. Marketplaces can use this to promote, for example, new sellers or new items on the platform to gain initial traction. The example below shows the challenger slot prioritized for items with fewer purchases to help gain traction and avoid being buried in the results due to a lack of data, reviews, etc.

Here's a Blender rule for emphasizing items with few purchases (< 10):

// If listing was purchased fewer than 10 times, set challenger to true
"challenger = IF(FEATURE(\"total_purchases\") \< 10, 1, 0);", 

// The third search result is the challenger, if one exists
"SELECT<CHALLENGER> WHERE(challenger == 1) SORT(clean_long_quote_match, title_query_substring, score) RELATIVE_POSITION(3);"

// All results except for the challenger slot follow the standard rule
// In the ranking, prioritize substring match then score (in case of ties)
"SORT(clean_long_quote_match, title_query_substring, score);" 

Maximizer slots (optional)

The maximizer slot is similar to the challenger, except it maximizes a quantitative objective, such as revenue. See below for an example of a revenue maximizer that forces the listing in slot 4 to be above a price threshold, such as $150.

// If country is US, set threshold to 150. If not, set to 100
"price_threshold = IF(FEATURE(\"search.filter_country_code=US\") == 1, 150, 100)));"

// Set maximizer to true if price is above threshold
"maximizer = IF(FEATURE(\"average_price\") > price_threshold, 1, 0), 0);"

// The third search result prioritizes the maximizer value first, then others if tied
"SELECT<MAXIMIZER> WHERE(maximizer == 1) SORT(clean_long_quote_match, title_query_substring, score) RELATIVE_POSITION(5);"
// All results except for the maximizer follow the standard rule
"SORT(clean_long_quote_match, title_query_substring, score);" 

Putting it all together

Let's put the Blender rules for both search and ads together in a single code block:

/***** Same rules and predictions as before *****/
"clean_long_quote_match = IF(FEATURE(CLEAN_QUERY_TITLE_MATCH) > 3, IF(FEATURE(CLEAN_QUERY_NUM_WORDS) > 3, 1, IF(FEATURE(QUERY_HAS_QUOTES) > 0, 1, 0)), 0);",  
"title_query_substring = IF(FEATURE(\"titleQueryWordsSubstring\") > 2, 1, 0);", 

"p_click = FEATURE(PREDICTION_NAVIGATE);",
"p_purchase = FEATURE(PREDICTION_POST_CLICK_PURCHASE);",

// The boosted score already handles native ads, so this is the regular search score
"score = p_purchase * p_click;"

// "challenger" rule
"challenger = IF(FEATURE(\"total_purchases\") \< 10, 1, 0);", 

// "maximizer" rule
"maximizer = IF(FEATURE(\"average_price\") > price_threshold, 1, 0), 0);"

// "boosted" value and score to account for native ads within organic results
"boosted = IF(FEATURE(\"adsEnabled=true\") == 1, IF(FEATURE(\"boosted_profile_config.is_boosted\") == 1, IF(FEATURE(1327178) == 0, 1, 0), 0), 0), 0);",
"boosted_score = IF(boosted == 1, p_click * FEATURE(\"boosted_profile_config.bid_value\"), 0);",

// Allocation rules combine the above values to sort the listings
// Assign native ads to absolute positions (e.g., the first and third search results)
// Use multiple rules to customize ordering of remaining results
"SELECT<BOOSTED> WHERE(boosted > 0) SORT(clean_long_quote_match, title_query_substring, boosted_score, score) ABSOLUTE_POSITION(0);",
"SELECT<CHALLENGER> WHERE(challenger == 1) SORT(clean_long_quote_match, title_query_substring, score) RELATIVE_POSITION(3);"
"SELECT<MAXIMIZER> WHERE(maximizer == 1) SORT(clean_long_quote_match, title_query_substring, score) RELATIVE_POSITION(5);"

"SORT(clean_long_quote_match, title_query_substring, score);"  

Each item is either inserted at a particular position in the ranking order or not ranked at all; only a small percentage of all items in retrieval will be ranked and shown to the user initially. Promoted supplies high-quality results and dynamic ranking of items when the user refreshes the page or loads additional items. This also applies to geolocation-based marketplaces with a map view — as long as geolocation data is being sent to Promoted in real-time, the list will update immediately when the user adjusts the map or filters.