XRecommend Service

The XRecommend service lets you fetch AI-driven product recommendations either for multiple slots at once or for a single slot, using context and merchandising rules to tailor results for each shopper.

Methods

// Returns a recommendation response mapped by element IDs.
xg.recommend.getResults({ elementIds: ['<element_id_1>', '<element_id_2>'], options: { pathname: '/en-us/' } });

// Returns a recommendation response for the given element ID.
xg.recommend.getResultsById({ elementId: '<element_id>', options: { pathname: '/en-us/' } });

// Returns a container response for the given container IDs.
xg.recommend.getResults({ containerIds: ['<container_id_1>', '<container_id_2>'], options: { pathname: '/en-us/' } });

// Returns a container response for the given element ID.
xg.recommend.getResultsById({ containerId: '<container_id>', options: { pathname: '/en-us/' } });

getResults

getResults

Description: Fetches recommendation results for multiple elements at once.

Think of an “element” as a recommendation slot, like “You May Also Like” on a product page or “Trending Now” on your homepage.Gets recommendation results by a list of elementIds or containerIds.

Parameters

Name	Type	Required	Description
`elementIds`	`string[]`	✅ (for v2)	The IDs of the elements that you want to fetch results for
`containerIds`	`string[]`	✅ (for v3)	The IDs of the containers that you want to fetch results for
↳ `options.version`	`string`	❌	The version of the API to use. v2 corresponds with the experience api, while v3 corresponds with the containers api. (This is no longer used as of version 1.6.8)
↳ `options.pathname`	`string`	❌	The pathname that includes the locale (default to 'default' locale)
↳ `options.queryString`	`string`	❌	The query string of the url
↳ `options.locale`	`string`	❌	The locale to get items from
↳ `options.exclude`	`string[] \| number[]`	❌	Product codes to exclude from the recommendations (example: `["code_1", "code_2"]`)
↳ `options.recentlyViewed`	`string[] \| number[]`	❌	Product codes of recently viewed items (example: `["code_1", "code_2"]`)
↳ `options.productCode`	`string`	❌	Product code of the currently viewed product on a PDP page. Used to enhance recommendations.
↳ `options.targetProductCode`	`string`	❌	Product code of the target product (used for passing a product code for anything other than a PDP page)
↳ `options.context`	`object`	❌	Context object used for dynamic filtering
`queryId`	`string`	❌	An optional queryId passed to cancel a request

Returns

A Promise resolving to a Recommendations object:

{
        // v2
        [key: string]: {
            items: RecommendProduct[];
            title: string;
            ruleEngine: string;
            ruleset: string;
        };

        // v3
        [key: string]: {
            items: RecommendProduct[];
            title: string;
        };
}

getResultsById

getResultsById

Description: Fetches recommendation results for a single elementId or containerId.

Parameters

Name	Type	Required	Description
`elementId`	`string`	✅ (for v2)	The ID of the element that you want to fetch results for
`containerId`	`string`	✅ (for v3)	The ID of the container that you want to fetch results for
↳ `options.version`	`string`	❌	The version of the API to use. v2 corresponds with the experience api, while v3 corresponds with the containers api. (This is no longer used as of version 1.6.8)
↳ `options.pathname`	`string`	❌	The pathname that includes the locale (default to 'default' locale)
↳ `options.queryString`	`string`	❌	The query string of the page
↳ `options.locale`	`string`	❌	The locale to get items from
↳ `options.exclude`	`string`	❌	Product codes to exclude from the recommendations separated by `\|` (example: `code_1\|code_2`)
↳ `options.recentlyViewed`	`string`	❌	Product codes of recently viewed items separated by `\|` (example: `code_1\|code_2`)
↳ `options.productCode`	`string`	❌	Product code of the currently viewed product on a PDP page. Used to enhance recommendations.
↳ `options.targetProductCode`	`string`	❌	Product code of the target product (used for passing a product code for anything other than a PDP page)
↳ `options.context`	`object`	❌	Context object used for dynamic filtering
`queryId`	`string`	❌	An optional queryId passed to cancel a request

Returns

A Promise resolving to a Recommendations object:

{
        // v2
        items: RecommendProduct[];
        title: string;
        ruleset: string;
        ruleEngine: string;

        // v3
        items: RecommendProduct[];
        title: string;
}