Get Products

Usage

Fetch product data by product IDs.

getProducts has two modes:

• direct: true (recommended) - fetches products directly from the Fast Simon index by ID. Input order is preserved; unknown IDs are silently omitted from the response. Supports withAttributes and withProductVariants.
• Default (no direct) - legacy mode that treats productIds as the user's recently-viewed history and returns recommendations based on those products, not the products themselves. The recently-viewed widget must be configured in your Fast Simon dashboard. Order is not guaranteed. Does not support withAttributes.

Example (Direct Fetch - Recommended)

window.FastSimonSDK.getProducts({
    productIds: ["123", "456", "234235"],
    direct: true,
    callback: (products) => {
        // products are returned in the same order as productIds
        // IDs not found in the index are omitted
    }
});

Example (Promise)

const products = await window.FastSimonSDK.getProducts({
    productIds: ["123", "456", "234235"],
    direct: true
});

Example (Default - via Recently-Viewed Widget)

// Legacy behavior: treats productIds as recently-viewed history and returns
// recommendations based on those products, not the products themselves.
// Requires the recently-viewed widget to be configured in the dashboard.
// Does not support withAttributes. Order is not guaranteed.
window.FastSimonSDK.getProducts({
    productIds: ["123", "456", "234235"],
    callback: (products) => {
        // handle here
    }
});

Options

Option	Type	Applies to	Description
productIds	string[] (required)	both modes	Product IDs to fetch. Input order is preserved when using direct: true. Unknown IDs are silently omitted.
callback	(products: Product[]) => void	both modes	Called with the result array. Required when not using the Promise API.
direct	boolean	-	When true, fetches directly from the Fast Simon index by ID. Recommended for most use cases. Default: false (routes through the recently-viewed widget).
withAttributes	boolean	direct: true only	When true, includes product custom attributes in the response.
withProductVariants	boolean	direct: true only	When true, includes product variant data in the response. Defaults to the value set at SDK initialization.
withSiblings	boolean	direct: true only	When true, includes alternative products (alt) in the response. Alternative products are separate Shopify products grouped together by the Fast Simon team (e.g. the same shoe in different colors, each stored as its own Shopify product). This is distinct from regular Shopify variants. Up to 25 alternative products per product are returned.
withBadges	boolean	both modes	When true, appends a badges array to each product with matched site badges. Automatically enables withAttributes.

Response

TypeScript Typing

type Response = Product[]

Behavior Details

Behavior	direct: true	Default (recently-viewed widget)
Unknown product IDs	Silently omitted	Silently omitted
withAttributes support	Yes	No
withProductVariants support	Yes	No
Alternative products (alt)	Up to 25 per product (requires withSiblings: true)	Not returned

Getting All Product Images via Custom Attributes

By default, each product includes:

• product.t - main/thumbnail image URL
• product.t2 - fallback image URL

To retrieve all product images, the Fast Simon team must first enable the "Product images" custom attribute for your store. This is a server-side configuration - it is not self-service.

To request this: Contact support@fastsimon.com and ask to enable product images as a custom attribute.

Once enabled, use withAttributes: true with direct: true to receive the full image list:

window.FastSimonSDK.getProducts({
    productIds: ["123", "456"],
    direct: true,
    withAttributes: true,
    callback: (products) => {
        products.forEach((product) => {
            const imagesAttr = product.attributes?.find(([key]) => key === "Product images");
            const allImages = imagesAttr ? imagesAttr[1] : [];
            console.log("All images for", product.l, ":", allImages);
        });
    }
});

The attributes field is an array of [attributeName, values] tuples. The "Product images" entry contains an array of all image URLs for the product.