Method Signature
getBrowseResultsForItemIds(
itemIds: string[],
parameters?: Omit<IBrowseParameters, 'qsParam'>,
networkParameters?: NetworkParameters
): Promise<GetBrowseResultsForItemIdsResponse>
Parameters
Array of item IDs to fetch. Example: ['shirt-123', 'shirt-456', 'shirt-789']
Additional parameters to refine the result setShow parameters properties
The page number of the results. Cannot be used together with offset.
The number of results to skip from the beginning. Cannot be used together with page.
The number of results per page to return
Key-value mapping of filters used to refine results. Example: { size: "medium", color: "blue" }
An object specifying whether results must match all, any, or none of a given filter. Example: { brand: "any", size: "all" }
The section name for results
Hidden metadata fields to return in results
Hidden facets to return in results
Parameters relevant to the network requestShow networkParameters properties
Request timeout in milliseconds
Returns
Returns a Promise that resolves to a browse results response object.
Information about the request that was made, including the item IDs and applied parameters
The browse results data
Array of product result objects matching the provided item IDs. Each result includes:
data: Product data including id and other metadatavalue: Product name or titlematched_terms: Terms that matched the browse querylabels: Product labels and badgesvariations: Product variations (if applicable)result_id: Unique identifier for tracking (automatically appended)
Available facets for filtering
Product groups or categories
Available sorting options for the result set
Total number of results returned
Information about result sources
Refined content and merchandising rules
Active features for this browse request
Unique identifier for this result set, used for analytics tracking
Examples
Basic Item ID Browse
const results = await constructorio.browse.getBrowseResultsForItemIds([
'shirt-123',
'shirt-456',
'shirt-789'
]);
console.log(results.response.results); // Array of matching products
Browse with Filters
const results = await constructorio.browse.getBrowseResultsForItemIds(
['prod-001', 'prod-002', 'prod-003', 'prod-004'],
{
filters: {
size: 'medium'
},
filterMatchTypes: {
size: 'all'
}
}
);
Browse with Section
const results = await constructorio.browse.getBrowseResultsForItemIds(
['item-100', 'item-200', 'item-300'],
{
section: 'Products',
resultsPerPage: 10
}
);
Browse with Hidden Fields
const results = await constructorio.browse.getBrowseResultsForItemIds(
['sku-a1b2c3', 'sku-d4e5f6'],
{
hiddenFields: ['internal_notes', 'supplier_cost'],
hiddenFacets: ['internal_category']
}
);
Browse with Variations Map
const results = await constructorio.browse.getBrowseResultsForItemIds(
['shoe-red-10', 'shoe-blue-10', 'shoe-green-10'],
{
variationsMap: {
group_by: [
{
name: 'color',
field: 'data.color'
}
],
dtype: 'array',
values: {
size: {
aggregation: 'all',
field: 'data.size'
}
}
}
}
);
Browse with Pre-Filter Expression
const results = await constructorio.browse.getBrowseResultsForItemIds(
['product-1', 'product-2', 'product-3'],
{
preFilterExpression: {
or: [
{
name: 'brand',
value: 'Nike'
},
{
name: 'brand',
value: 'Adidas'
}
]
}
}
);
Browse with Timeout
const results = await constructorio.browse.getBrowseResultsForItemIds(
['item-a', 'item-b', 'item-c'],
{
section: 'Products'
},
{
timeout: 3000 // 3 second timeout
}
);
Use Cases
Personalized Product Collections
Create custom product collections based on user preferences or recommendations:
// Fetch user's favorited item IDs
const favoriteIds = getUserFavorites(); // ['item-1', 'item-2', 'item-3']
const results = await constructorio.browse.getBrowseResultsForItemIds(
favoriteIds,
{
section: 'Products',
filters: {
in_stock: true
}
}
);
Cross-Sell and Upsell
Display related or complementary products:
const relatedItemIds = ['accessory-1', 'accessory-2', 'upgrade-1'];
const results = await constructorio.browse.getBrowseResultsForItemIds(
relatedItemIds,
{
resultsPerPage: 6
}
);
Recently Viewed Items
Retrieve full details for recently viewed products:
const recentlyViewedIds = getRecentlyViewedFromStorage();
const results = await constructorio.browse.getBrowseResultsForItemIds(
recentlyViewedIds,
{
hiddenFields: ['user_specific_price'],
section: 'Products'
}
);
Error Handling
try {
const results = await constructorio.browse.getBrowseResultsForItemIds(
['item-1', 'item-2'],
{ section: 'Products' }
);
// Process results
console.log(results.response.results);
} catch (error) {
if (error.message.includes('ids is a required parameter')) {
console.error('Item IDs array is required');
} else {
console.error('Browse request failed:', error);
}
}
Additional Resources
