Storefront Query Helper

Description

Storefront Helpers allow custom blocks to pull real-time e-commerce catalog data—such as structural product listings, filtered descriptions, variants, inventory flags, and curated lists—without having to construct raw, external GraphQL or REST requests from scratch.

Function Signature

const response = await Superfans.helpers.getStorefrontData({
      query: QUERY,  //Query is any storefront query you need to fetch from Shopify
      variables: { 
        id: variantGid 
      }
});


// Sample qury to get Product info

const QUERY = `
    query ProductVariantById($id: ID!) {
      node(id: $id) {
        __typename
        ... on ProductVariant {
          id
          title
          availableForSale
          quantityAvailable
          currentlyNotInStock
          sku
          product {
            title
          }
        }
      }
    }
  `;

Structure of Response

Status	Response
Success	`{ "status": "success", "data": { "products": [ ... ] } }`
Error	`{ "status": "error", "errorId": 500, "errorHandle": "unknown-error", "message": "Storefront API request timed out" }`

Example Usage

async function fetchVariantWithHelper(numericId) {
  // 1. Replicate your working GID logic
  const variantGid = `gid://shopify/ProductVariant/${numericId}`;
  // 2. Use your exact working query
  const QUERY = `
    query ProductVariantById($id: ID!) {
      node(id: $id) {
        __typename
        ... on ProductVariant {
          id
          title
          availableForSale
          quantityAvailable
          currentlyNotInStock
          sku
          product {
            title
          }
        }
      }
    }
  `;
  try {
    // 3. Call the helper
    const response = await Superfans.helpers.getStorefrontData({
      query: QUERY,
      variables: { 
        id: variantGid 
      }
    });
    // Log for verification
    console.log("Helper Response:", response);
    // 4. Access data (Helper usually returns the 'data' object directly)
    const variant = response?.data?.node || response?.node;
    if (variant) {
      // Logic for UI updates
      const status = variant.availableForSale ? "In Stock" : "Out of Stock";
      console.log(`Success! ${variant.title} is ${status}`);
      // Example of displaying it in your test element
      const displayElem = document.getElementById("test");
      if(displayElem) {
        displayElem.innerHTML += `<br>Helper Result: ${variant.title} - ${variant.quantityAvailable} available`;
      }
      return variant;
    } else {
      console.warn("Helper returned empty node. Check SDK initialization tokens.");
      return null;
    }
  } catch (error) {
    console.error("Superfans Helper Error:", error);
    return null;
  }
}
// Explicit Call
fetchVariantWithHelper("45253067309241");

<div id="test"></div>

The above example retrieves the quantity variant available and displayed in a div.

Best Practices

Caching Mechanisms: Store frequent, heavy payload items returned into your block's Local Storage helper methods to speed up subsequent custom block loads.
Loading Skeletons: Ensure you wrap async data retrievals with clean loading indicators (Show Toast, loaders) to prevent jarring visual layouts while data pulls from the Shopify servers.

Caveats

Sync Frequency: Newly added storefront configurations, localized pricing rules, or inventory adjustments made directly in the Shopify Admin dashboard might take up to a few minutes to accurately propagate through the Storefront Helper API responses.