Upsell & Cross-Sell

Usage

Use the following code to retrieve product recommendations data

Example

window.FastSimonSDK.productRecommendationByWidget({
    productID: "1233231",
    withAttributes: true,
    recent:["12345","67890"],
    widgetsIDS: ["123457878"],

    callback: (response) => {
        // draw widget
    }
});

Options

Option	Type	Description
productID	string (required)	response will be based on this product
callback	(Response) => void (required)	callback to handle the results
widgetsIDS	string[] (required)	An array of widget IDs from the Fast Simon dashboard to specify which widgets should return recommendations.
recent	string[]	add tracked recent product ids, example: ["2323","123"]
withAttributes	boolean	include product attributes in the response
withBadges	boolean	when true, appends a badges array to each product in each widget's payload with the matched site badges. Automatically enables withAttributes.

Response

TypeScript Typing

interface Widget {
    productID: string
    widgetID: string
    categoriesIDs: string[]
    payload: Product[]
    sources: string
    title?: string
    similarByAttributesTiers?: Record<string, string[]>
}

interface Response {
    action: "recommendations",
    payload: Widget[]
}

Reporting Implementation (must for analytics)

Please follow the guideline to report shopper behaviour on the recommendation widget in order to get accurate Analytics in the Fast Simon dashboard as well as greater personalized accuracy

1. Products Viewed From Upsell/Cross-Sell - report whenever product is clicked from the widget
2. Report Products Shown - report when recommendation products are displayed to users

1. Report Recommendations Products Shown

Use this event to report when products from recommendations are shown to users for analytics and personalization tracking.

Example

window.FastSimonSDK.event({
    eventName: window.FastSimonEventName.RecommendationsProductsShown,
    data: {
        products: [
            {
                "l": "Women's Classic Nylon 89 Shoes",
                "c": "USD",
                "u": "/products/nylon-89-shoes-muted-clay-pink-clay-leisure-blue-132131",
                "p": "90.00",
                "t": "https://cdn.shopify.com/s/files/1/0862/7834/0912/files/JPG-100230796_SLC_eCom_large.jpg?v=1751303079",
                "id": "9891167699248",
                "sku": "100230796-8.5",
                // ... other product properties
            },
            {
                "l": "Another Product Name",
                "c": "USD", 
                "p": "45.00",
                "id": "9891167699249",
                // ... other product properties
            }
        ], // or a widget's own products from the callback: response.payload[i].payload
           // (NOT response.payload itself — that is the array of widgets, and passing it breaks reporting)
        widget_id: "17496353898304754", // Required, the widget id from the same widget entry: response.payload[i].widgetID
        id: "9891167650432" // optional - the numeric source product id. Note: `id`, not `sourceProductID`.
    }
});

Data Properties

Property	Type	Description
products	(Product \| string \| number)[] (required)	The products this ONE widget showed. A bare numeric id may be passed in place of a Product object.
widget_id	string (required)	Identifier for the recommendation widget
id	string (optional)	Numeric source product id; parsed as an int, so a non-numeric value records no source product. This event uses id; the click event below uses sourceProductID.

Product Object Properties

Only two fields are read from each element of products:

• id: required, the numeric product id (a numeric string is fine). An element without one is dropped from the report.
• rec_src: optional, the recommendation source from the widget response; carried through to analytics.

Everything else the recommendation API returns (l, c, p, u, t, sku, …) is ignored by this event, so passing the objects the API gave you is the simplest correct thing to do. A bare numeric id also works and loses only rec_src: products: [9891167699248, 9891167699249].

When to Use

Use this event to report when recommendation products are displayed to users:

• Product Page Recommendations: When related/similar products are shown
• Upsell/Cross-sell Widgets: When recommendation widgets render products
• Cart Recommendations: When products are recommended in cart/checkout
• Category Page Recommendations: When recommended products appear on collection pages

Best Practices

1. Call after products are actually visible: Only report when products are rendered and visible to users
2. Include widget_id: Helps distinguish different recommendation contexts. Omitting it records a NULL widget_id, which the widget-performance reports filter out
3. Send one event per widget: each carrying that widget's own products, not one event per product

2. Report Recommendations Products clicks

Use this event to report when products from recommendations are clicked by the users for analytics and personalization tracking.

Example

window.FastSimonSDK.event({
    eventName: window.FastSimonEventName.RecommendationProductClicked,
    data: {
        productID: "5551555", // The id of the clicked product (Required)
        widget_id: "17496353898304754", // the widget id from the same widget entry: response.payload[i].widgetID  (Required)
        position: 7, // The position of the product in the widget / popup (counted from 1)
        sourceProductID: "441" // Source product ID (example product page product ID)
    }
});

Data Properties

Property	Type	Description
productID	string (required)	The id of the clicked product
widget_id	string (required)	Identifier for the recommendation widget
position	number (required)	The position of the product in the widget / popup (counted from 1)
sourceProductID	string (optional)	The source product ID (usually current product page)

When to Use

Use this event to report when recommendation products are clicked by the users:

Best Practices

1. Trigger before redirection: When a recommended product is clicked, trigger the event before redirecting to the relevant product page. Wait for the event to complete, then proceed with the redirection.
2. Use local storage as a fallback: Alternatively, you can store the clicked product in local storage before redirecting. After the new page loads, check local storage for the stored product, trigger the event, and then clear the storage.