Dynamic Grouping

Some products are available in variants that only differ on a small set of attributes, such as size or color. Marketplace sellers may also carry the same products. If each of these similar products is displayed independently in search results, then the recall may extend to many pages and therefore reduce the discoverability of other products.

Dynamic Grouping allows you to group similar products together to reduce the size of the recall and improve product discoverability, thus leading to an increase in conversion. For a given search query, you can specify a group, which defines an attribute for products to be grouped by. For example, you could group by color to group variants of the same color together.


Say your catalog contains red paint in three sizes: 1L, 2L, and 3L. With Dynamic Grouping, you can group all the red paint size variants into a single red paint group. Note that searches can only group on a single attribute at a time.


Products can be grouped by a specified grouping attribute at run-time on the API. The grouping attribute can vary across different pages, search or category. For example, you could group by sub-category on a category page, or group by color on a search page, etc. You can also choose to not group products on some pages and make a regular search request. For more details, read the Dynamic Grouping API page

Ranking Groups

When a grouping request is made, products are retrieved and ranked as with a non-grouped search request. The returned products are further grouped and ranked within the group based on their product score. The groups are then ranked based on the top product score within each group.

The table below shows an example of how ranking changes after grouping:

Ungrouped RankingGrouped Ranking
PID 1 = 50 (Group B)Group B
PID 2 = 30 (Group A)
PID 3 = 10 (Group A)Group A
PID 4 = 5 (Group B)
PID 5 = 1 (Group C)
PID 6 = 1 (Group C)Group C

Sorting Groups

Sorting on grouped pages works similarly to how groups are ranked. Products are sorted within groups, then groups are sorted based on the top product within each group.

Facets and Groups

Facets work with grouping requests the same as they do with non-grouped requests. Facet count corresponds to the products and not the groups. For example, if there are 4 products returned and 2 groups are made, the facet count is still based on the 4 products.

How to enable this feature?

To get access to this feature, reach out to your account manager. You will have to work with the tech services team to enable it on your production site.

How to integrate this feature?

Visit the Dynamic Grouping API page for integration details.


Code sample

Check the demo code sample that demonstrates how to implement Dynamic Grouping.


What happens if a product does not have the grouping attribute or value?

If this product is a part of the recall, then it will be returned in a Default/Null group. 

What APIs support dynamic grouping?

Grouping is supported on Search and Category APIs. We also allow the creation of group rules and apply them to grouped API requests. Visit this guide to learn more.

Can you perform grouping on a SKU level attribute?

No, this is not supported.

How does Dynamic Grouping interact with other Search features?

Dominant CategoryDominant categories for top queries and live dominant category are computed without grouping.
Dominant AttributeDominant attributes for top queries are computed without grouping.
Precision ModeUnaffected by grouping.
Spell CorrectResults from the spell-corrected query are grouped.
Query RelaxationResults from the relaxed query are grouped.
Dynamic Facet/Reorder FacetGrouping is disabled.
Merchandising rules (include/exclude/ boost/bury/soft boost/slots)Still apply on the product-level and not on groups. Slots are disabled for grouping requests.
SKUsSKU filtering and faceting, and Hero SKUs are supported for grouping requests.
LookupsGrouping applies to Lookup queries.
Attribute-based FilteringUnaffected by grouping.

How does Dynamic Grouping work with merchandising?

Merchandising works on grouped pages at a product level, and you cannot merchandise directly on groups. Some important interactions between Dynamic Grouping and other merchandising features are listed below.

Ranking Behavior

  • Boost to top a product - Product A is boosted to top and is a part of group:blue. Product A should be the 1st product in group:blue, and group:blue should be the 1st group in the recall.
  • Bury to bottom a product - Product B is hard buried and is a part of group:red. Product B should be buried at the bottom of group:red, but group:red should continue to be ranked based on the 1st product of the group. 
  • Blocklist a product - Product C is blocklisted and is a part of group:green. Product C should not be returned in the recall, and should not be seen in group:green.
  • Product Slots - Slots will NOT apply on grouped pages. 
  • Boost by Attribute - If color:red is boosted for a query, then products that are color:red should be ranked higher within each group. Group ranking should continue to be based on the top product of each group. 
  • Bury by Attribute - If color:green is buried for a query, then products that are color:green should be ranked lower within each group. 
  • Include only - The grouped response should only contain included products by attribute. If you include only color:red products for a query, then only color:red products should be seen within the groups.
  • Exclude only - The grouped response should not contain excluded products by attribute. If you exclude color:green products for a query, then color:green products should not be seen within the groups.

Ranking Diagnostics

Ranking Diagnostics does NOT support the grouped recall.

Facet Manager

No expected changes. Do note that on grouped pages, the facet count corresponds to the products and not the groups.

A/B Testing

No expected changes for product-level customizations. 


No expected changes.


No expected changes.


No expected changes.