Get Product Badges

Usage

Fetch badge configuration and match badges for a set of products by their IDs.

Use this method when you need badges for specific products outside of a search or collection flow — for example on a product detail page, a featured products section, or a custom product carousel.

For search, collection, and recommendation flows, use the withBadges: true flag on the respective method instead — it requires no extra API call.

Example

window.FastSimonSDK.getProductBadges({
    productIds: ["123", "456", "789"],
    callback: (badges, products) => {
        // badges: { [productId]: Badge[] }
        // products: { [productId]: Product } — use for price-based badge text
        const badgesFor123 = badges["123"];
        const productFor123 = products["123"];
        // render badges using productFor123.p (price) and productFor123.p_c (compare price)
    }
});

Options

Option	Type	Description
productIds	string[] (required)	Product IDs to fetch and match badges for
callback	(badges: Record\<string, Badge[]>, products: Record\<string, Product>) => void (required)	Callback with matched badges and product data per product ID

Response

The callback receives two dictionaries:

• badges — maps each product ID to its matched badges, sorted by priority and limited to the site's configured badge limit
• products — maps each product ID to its full product data from the Fast Simon index, including market-aware prices (p for current price, p_c for compare price)

Use the product's p and p_c fields when computing text for discount auto-badges — these prices are returned in the active market's currency, matching exactly what the serving layer uses on search and collection pages.

If a product has sibling (ALT) products — for example, color variants that are separate Shopify product IDs — their badges and product data are included in the result automatically. You do not need to pass sibling IDs in productIds.

This means a single call with the main product ID is enough to pre-fetch badges for all siblings and handle swatch/color switches with no additional requests.

TypeScript Typing

type BadgesResponse = Record<string, Badge[]>
type ProductsResponse = Record<string, Product>

interface Badge {
    tag: string               // internal badge identifier
    displayType: "text" | "image"
    autoBadgeType: string     // "discount" | "inventory" | "release_date" | "sales" | ""
    badgeText: string         // display text (text badges)
    badgeStyle: {
        backgroundColor?: string
        textColor?: string
        borderColor?: string
        borderRadius?: number
        size?: number
        vertical?: "top" | "bottom"
        horizontal?: "left" | "right"
    }
    autoConfig: object        // discount calculation config, inventory thresholds, etc.
    imageUrl: string          // image URL (image badges)
    priority: number
    displayName?: string
}

interface Product {
    id: string | number
    p: string     // current price in active market currency
    p_c: string   // compare-at price in active market currency
    // ... additional product fields
}

Rendering Badges

window.FastSimonSDK.getProductBadges({
    productIds: ["123"],
    callback: (badges, products) => {
        const productBadges = badges["123"] || [];
        const product = products["123"];
        productBadges.forEach(badge => {
            if (badge.displayType === "image") {
                // render <img src={badge.imageUrl}>
            } else {
                // for discount badges (autoBadgeType === "discount"):
                // use product.p and product.p_c for accurate price-based text
                // render badge.badgeText with badge.badgeStyle
            }
        });
    }
});

Badge limits

The badges returned already respect the site's configured limits:

• badgesLimit — maximum badges per product across all corners
• badgesLimitPerCorner — maximum badges per corner position (e.g. at most 2 at top-left)

Both values come from the dashboard Badges per Product and Per Corner settings and are applied automatically. No extra configuration needed in the callback.

tip

For search and collection pages, use withBadges: true on fullTextSearch or smartCollections — badges are computed in-memory with no extra request.

getProductBadges is best suited for pages where you already know the product IDs but don't have product data yet (e.g. a PDP).