Custom Data

window.FrenzyProductGridChangeCallBack is a global hook that lets theme developers modify each product card generated by Frenzy. Common uses include:

Displaying custom, sale, preorder, new, or sold-out badges
Rendering color or material swatches
Updating price presentation
Adding low-stock or delivery messages
Adding wishlist or compare buttons
Adding analytics attributes
Loading additional Shopify product information

1. Callback signature

window.FrenzyProductGridChangeCallBack = function (html, data) {
  // Modify the product card here.
};

Parameters

Parameter	Description
`html`	A detached `HTMLElement` containing the generated product-card markup.
`data`	The Frenzy product record used to generate that card.

2. When the callback runs

The callback runs every time Frenzy formats a product card. Depending on the store configuration, that can include:

Collection grids
Search-result grids
Recommendation carousels
Cart-popup recommendations
Infinite-scroll results
Predictive-search suggestions

The same product can therefore pass through the callback more than once, or appear in multiple locations simultaneously. The callback must be:

Safe to run repeatedly
Scoped to the supplied cardRoot
Fast
Protected against missing data and missing elements
Careful about context-specific behavior

3. Understanding the product payload

The keys in the ‘data’ object is controlled from the Dashboard. (Search & Collections -> Filter Settings -> Extra Properties -> Response Fields. Below is an example image. This is done to limit the data in the API response and maintain the platform speed.

The list of keys/internal names can be selected from Search & Collections -> Filter Settings -> Filter Options -> Internal Name.

The exact fields depend on the store’s Frenzy feed and configuration. Frequently observed fields include:

Field	Typical purpose
`product_id`	Shopify product ID
`variant_id`	Current variant ID
`product_id_variant`	Compound product/variant identifier
`sku`	Card identifier or compound product/variant key
`org_prod_url`	Product handle or URL
`org_price`	Current product price
`org_msrp_price`	Compare-at price
`org_variant_min_price`	Lowest variant price
`org_variant_max_price`	Highest variant price
`org_stock_available`	Product availability
`org_stock_amount`	Inventory quantity, when available
`org_product_tags`	Shopify product tags
`prod_data_creation_date`	Product creation date
`org_template_suffix`	Shopify product template suffix
`options`	Grouped product options
`all_options`	Variant or option data
`all_options_details`	Detailed variant data
`org_request_type`	Frenzy rendering context
`smf_*`	Store-specific metafields
`sv_*`	Store-specific variant fields

*Do not assume every field will exist. During development, inspect the real payload:

window.FrenzyProductGridChangeCallBack = function (cardRoot, product) {
  console.debug("Frenzy product-card payload:", {
    product,
    cardRoot
  });
};

Remove or disable verbose logging before publishing the theme.

4. Recommended callback structure

Only one global callback can exist. Assigning the function again replaces the previous implementation. Use one coordinator that calls separate extension functions:

window.FrenzyProductGridChangeCallBack = function (cardRoot, product) {
  try {
    const card = cardRoot.querySelector(".frenzy_product_item");

    if (!card || !product) return;

    addProductBadges(cardRoot, product);
    addProductSwatches(cardRoot, product);
    applyProductCardRules(cardRoot, product);
    addAnalyticsData(cardRoot, product);
  } catch (error) {
    console.error("Frenzy product-card extension failed:", {
      error,
      product
    });
  }
};

The outer try/catch is important. An uncaught exception can interrupt the product-grid rendering loop and affect subsequent cards. If the theme already defines this callback, either add new helpers to the existing implementation or wrap it:

const existingFrenzyCallback =
  window.FrenzyProductGridChangeCallBack;

window.FrenzyProductGridChangeCallBack = function (cardRoot, product) {
  try {
    existingFrenzyCallback?.(cardRoot, product);
    applyMyAdditionalFeatures(cardRoot, product);
  } catch (error) {
    console.error("Frenzy card callback failed:", error);
  }
};

The wrapper must load after the existing callback.

5. Use case: product badges

The following example supports:

Automatic sold-out badges
Percentage-off sale badges
Preorder tags
Custom _badge_ product tags

function normalizeTags(value) {
  if (Array.isArray(value)) return value;
  if (typeof value === "string" && value) return [value];
  return [];
}

function isExplicitlyUnavailable(value) {
  return (
    value === false ||
    value === 0 ||
    String(value).toLowerCase() === "false"
  );
}

function createBadge(label, type) {
  const badge = document.createElement("span");

  badge.className = `frenzy-extension-badge frenzy-extension-badge--${type}`;
  badge.dataset.frenzyExtensionBadge = type;
  badge.textContent = label;

  return badge;
}

function addProductBadges(cardRoot, product) {
  const container = cardRoot.querySelector(".frenzy_product_tags");

  if (!container) return;

  // Remove only badges owned by this extension.
  container
    .querySelectorAll("[data-frenzy-extension-badge]")
    .forEach((badge) => badge.remove());

  const tags = normalizeTags(product.org_product_tags);
  const price = Number(product.org_price);
  const comparePrice = Number(product.org_msrp_price);

  if (isExplicitlyUnavailable(product.org_stock_available)) {
    container.appendChild(createBadge("Sold Out", "sold-out"));
    return;
  }

  if (tags.includes("_preorder")) {
    container.appendChild(createBadge("Preorder", "preorder"));
  }

  if (
    Number.isFinite(price) &&
    Number.isFinite(comparePrice) &&
    comparePrice > price
  ) {
    const discount = Math.round(
      ((comparePrice - price) / comparePrice) * 100
    );

    container.appendChild(
      createBadge(`${discount}% OFF`, "sale")
    );
  }

  tags
    .filter((tag) => tag.includes("_badge_"))
    .map((tag) => tag.split("_badge_")[1])
    .filter(Boolean)
    .forEach((badgeName) => {
      const label = badgeName.replaceAll("_", " ").trim();

      if (label) {
        container.appendChild(createBadge(label, "custom"));
      }
    });
}

Example styling:

.frenzy-extension-badge {
  display: inline-flex;
  padding: 4px 8px;
  font-size: 12px;
  line-height: 1;
  text-transform: uppercase;
}

.frenzy-extension-badge--sale {
  color: #fff;
  background: #c9232d;
}

.frenzy-extension-badge--sold-out {
  color: #fff;
  background: #222;
}

.frenzy-extension-badge--preorder {
  color: #222;
  background: #f1d88b;
}

Use textContent when displaying product data. Avoid inserting untrusted field values directly through innerHTML.

6. Use case: color or material swatches

This example reads Color or Metal from all_options_details.

Render swatches synchronously

function addProductSwatches(cardRoot, product) {
  const target = cardRoot.querySelector(
    ".frenzy_collection_swatches, " +
    ".custom-collection-swatches, " +
    ".frenzy_swatch"
  );

  if (!target) return;

  const variants = Array.isArray(product.all_options_details)
    ? product.all_options_details
    : [];

  const swatches = variants
    .map((variant) => {
      const option = variant.options?.find((item) => {
        const name = String(item.name || "").toLowerCase();
        return name === "color" || name === "metal";
      });

      return {
        id: variant.variant_id,
        label: option?.value,
        image: String(variant.org_image_url || "")
          .trim()
          .split(/\s+/)[0]
      };
    })
    .filter((swatch) => swatch.id && swatch.label);

  if (!swatches.length) return;

  let group = target.querySelector(
    "[data-frenzy-extension-swatches]"
  );

  if (!group) {
    group = document.createElement("div");
    group.className = "frenzy-extension-swatches";
    group.dataset.frenzyExtensionSwatches = "";
    group.setAttribute("role", "group");
    group.setAttribute("aria-label", "Available options");
    target.appendChild(group);
  }

  group.replaceChildren();

  const seenOptions = new Set();

  swatches.forEach((swatch) => {
    if (seenOptions.has(swatch.label)) return;
    seenOptions.add(swatch.label);

    const button = document.createElement("button");

    button.type = "button";
    button.className = "frenzy-extension-swatch";
    button.dataset.frenzySwatchId = swatch.id;
    button.dataset.frenzySwatchImage = swatch.image;
    button.dataset.frenzySwatchLabel = swatch.label;
    button.setAttribute("aria-label", `Select ${swatch.label}`);
    button.setAttribute("aria-pressed", "false");
    button.title = swatch.label;

    group.appendChild(button);
  });
}

Handle clicks through event delegation

Install this listener once, outside the callback:

document.addEventListener("click", function (event) {
  const swatch = event.target.closest(
    "[data-frenzy-swatch-id]"
  );

  if (!swatch) return;

  const card = swatch.closest(".frenzy_product_item");

  if (!card) return;

  card
    .querySelectorAll("[data-frenzy-swatch-id]")
    .forEach((item) => {
      item.classList.remove("is-selected");
      item.setAttribute("aria-pressed", "false");
    });

  swatch.classList.add("is-selected");
  swatch.setAttribute("aria-pressed", "true");

  const image = card.querySelector(".frenzy_img_first");
  const imageUrl = swatch.dataset.frenzySwatchImage;

  if (image && imageUrl) {
    image.src = imageUrl;
  }

  const colorLabel = card.querySelector(
    ".product_card_color_title, .current-metal"
  );

  if (colorLabel) {
    colorLabel.textContent =
      swatch.dataset.frenzySwatchLabel || "";
  }

  card.dataset.selectedVariantId =
    swatch.dataset.frenzySwatchId;
});

For a production swatch implementation, also update:

Product links with ?variant=...
Quick-add variant IDs
Price and compare-at price
Secondary product image
Size availability
The selected swatch state

7. Use case: custom merchandising rules

The callback can apply rules using product tags, inventory, template suffixes, collections, metafields, or request context.

function applyProductCardRules(cardRoot, product) {
  const card = cardRoot.querySelector(".frenzy_product_item");
  const quickAdd = cardRoot.querySelector(
    ".frenzy_add_to_cart_btn"
  );

  if (!card) return;

  const tags = normalizeTags(product.org_product_tags);
  const inventory = Number(product.org_stock_amount);

  if (tags.includes("online-exclusive")) {
    card.classList.add("is-online-exclusive");
  }

  if (
    Number.isFinite(inventory) &&
    inventory > 0 &&
    inventory <= 5
  ) {
    const details = card.querySelector(
      ".frenzy_product_item_detail"
    );

    if (
      details &&
      !details.querySelector("[data-frenzy-low-stock]")
    ) {
      const message = document.createElement("p");

      message.dataset.frenzyLowStock = "";
      message.className = "frenzy-low-stock";
      message.textContent = `Only ${inventory} left`;

      details.appendChild(message);
    }
  }

  if (tags.includes("coming-soon") && quickAdd) {
    quickAdd.disabled = true;
    quickAdd.textContent = "Coming Soon";
  }

  if (product.org_template_suffix === "product-clearance") {
    card.classList.add("is-clearance-product");
  }
}

8. Use case: context-specific behavior

Because the callback may run for collections, recommendations, predictive search, and cart popups, not every extension should run everywhere. Use org_request_type where available:

function isCartPopup(product) {
  return (
    product.org_request_type ===
    "widget_cart_popup_carousel_config"
  );
}

function applyProductCardRules(cardRoot, product) {
  if (isCartPopup(product)) {
    // Cart-popup-specific behavior.
    return;
  }

  // Collection/search behavior.
}

Request-type values depend on Frenzy configuration. Log product.org_request_type in the development theme before building an allowlist.

9. Use case: asynchronous product enrichment

Sometimes the Frenzy feed does not include everything required by the theme. Additional information may need to come from:

Shopify’s product JSON endpoint
A custom Shopify alternate view
A metafield endpoint
A third-party loyalty or review service

First, assign a stable identifier synchronously:

function prepareAsyncEnrichment(cardRoot, product) {
  const card = cardRoot.querySelector(".frenzy_product_item");

  if (!card) return;

  const key = String(product.sku || product.product_id || "");

  card.dataset.frenzyExtensionKey = key;

  enrichLiveCards(key, product);
}

Then cache the request and update the live cards:

const frenzyProductRequestCache = new Map();

function getProductHandle(product) {
  return String(product.org_prod_url || "")
    .split("?")[0]
    .split("/")
    .filter(Boolean)
    .pop();
}

function fetchShopifyProduct(product) {
  const handle = getProductHandle(product);

  if (!handle) {
    return Promise.reject(new Error("Missing product handle"));
  }

  if (!frenzyProductRequestCache.has(handle)) {
    const request = fetch(
      `${window.Shopify?.routes?.root || "/"}products/` +
      `${encodeURIComponent(handle)}.js`
    )
      .then((response) => {
        if (!response.ok) {
          throw new Error(`Product request failed: ${response.status}`);
        }

        return response.json();
      })
      .catch((error) => {
        frenzyProductRequestCache.delete(handle);
        throw error;
      });

    frenzyProductRequestCache.set(handle, request);
  }

  return frenzyProductRequestCache.get(handle);
}

async function enrichLiveCards(key, product) {
  try {
    const shopifyProduct = await fetchShopifyProduct(product);

    // Wait until the serialized Frenzy card has been mounted.
    requestAnimationFrame(() => {
      document
        .querySelectorAll("[data-frenzy-extension-key]")
        .forEach((card) => {
          if (card.dataset.frenzyExtensionKey !== key) return;

          const target = card.querySelector(
            "[data-frenzy-extra-information]"
          );

          if (target) {
            target.textContent =
              shopifyProduct.vendor || "";
          }
        });
    });
  } catch (error) {
    console.error("Unable to enrich Frenzy product card:", {
      error,
      key
    });
  }
}

Caching prevents the same product from being requested repeatedly when it appears in multiple grids.

10. Other useful extensions

Price presentation

Developers can add:

“From” labels for products with a price range
Percentage-saved messages
Member pricing
Clearance styling
Regional price messages

Avoid replacing Frenzy’s price unless the custom price source is authoritative and uses the correct active currency.

Wishlist or compare integrations

The callback can synchronously insert the required placeholder, product ID, variant ID, and classes. Initialize the third-party library only after the card is present in the live document.

Analytics

The callback is useful for adding attributes:

function addAnalyticsData(cardRoot, product) {
  const card = cardRoot.querySelector(".frenzy_product_item");

  if (!card) return;

  card.dataset.analyticsProductId = product.product_id || "";
  card.dataset.analyticsVariantId = product.variant_id || "";
  card.dataset.analyticsContext = product.org_request_type || "";
}

Do not fire an impression event directly from the callback. Formatting a card does not guarantee that the user saw it. Use an IntersectionObserver on the live cards.

Accessibility

Custom extensions should include:

Buttons for interactive swatches
Descriptive aria-label values
aria-pressed for selected swatches
Proper disabled states
Visible keyboard focus
Text equivalents for color-only indicators

12. Production checklist

Before publishing an extension:

Use a single global callback.
Define it before Frenzy performs its first grid render.
Wrap the callback in try/catch.
Guard every optional selector and data field.
Make every modification idempotent.
Scope synchronous queries to cardRoot.
Do not attach event listeners to the detached card.
Use event delegation for interactive features.
Do not rely on an asynchronous callback return value.
Re-query the live document after asynchronous work.
Cache per-product network requests.
Use textContent for product-derived text.
Sanitize any non-theme HTML before inserting it.
Test collection, search, recommendations, predictive search, cart popup, filtering, sorting, and infinite scroll.
Test products with missing images, no variants, sold-out variants, price ranges, and incomplete metafields.

Shopify App

API Functions

1. Callback signature

Parameters

2. When the callback runs

3. Understanding the product payload

4. Recommended callback structure

5. Use case: product badges

6. Use case: color or material swatches

Render swatches synchronously

Handle clicks through event delegation

7. Use case: custom merchandising rules

8. Use case: context-specific behavior

9. Use case: asynchronous product enrichment

10. Other useful extensions

Price presentation

Wishlist or compare integrations

Analytics

Accessibility

12. Production checklist

​1. Callback signature

​Parameters

​2. When the callback runs

​3. Understanding the product payload

​4. Recommended callback structure

​5. Use case: product badges

​6. Use case: color or material swatches

​Render swatches synchronously

​Handle clicks through event delegation

​7. Use case: custom merchandising rules

​8. Use case: context-specific behavior

​9. Use case: asynchronous product enrichment

​10. Other useful extensions

​Price presentation

​Wishlist or compare integrations

​Analytics

​Accessibility

​12. Production checklist

1. Callback signature

Parameters

2. When the callback runs

3. Understanding the product payload

4. Recommended callback structure

5. Use case: product badges

6. Use case: color or material swatches

Render swatches synchronously

Handle clicks through event delegation

7. Use case: custom merchandising rules

8. Use case: context-specific behavior

9. Use case: asynchronous product enrichment

10. Other useful extensions

Price presentation

Wishlist or compare integrations

Analytics

Accessibility

12. Production checklist