Skip to main content

Yotpo Reviews

Overview​

This module provides a system for fetching, enriching, and preparing product reviews from Yotpo for display in our UI. It handles both single products and bundles, supporting filters such as star ratings, media presence, size, height, and a few sort categories.

Key features:

  • Fetches raw review data from Yotpo based on Shopify product handles.
  • Enriches reviews with metadata including product-specific details.
  • Supports pagination and filtering options.
  • Aggregates and merges reviews for bundled products.
  • Fetches and attaches popular review topics.
  • Resolves selected product options (SKU mappings) for each review.
  • Caches requests efficiently to reduce network overhead.

Main Function: getProductReviews​

Purpose​

Orchestrates the entire process of retrieving and enriching product reviews.

Inputs​

  • storefront: Shopify storefront API instance.
  • request: Incoming HTTP request.
  • withCache: Cache-enabled fetch utility.
  • Query parameters (optional):
    • handle: Product handle (string).
    • starRating: Filter by star rating (number).
    • page: Pagination page number (default 1).
    • perPage: Number of reviews per page (default 4).
    • Other filters like excludedIds, sorting, hasMedia, height, heightQuestionId, size, sizeQuestionId, topics

Flow​

  1. Fetch Shopify product info using the handle.
  2. Fetch raw Yotpo reviews for the product(s).
  3. Obtain a Yotpo OAuth access token. (If possible, as the Yotpo Secret Key is only available in production environments)
  4. Enrich reviews by fetching and attaching metadata. (This uses the OAuth access token. If it isn't available, we will resort to metadata being null)
  5. Fetch popular review topics.
  6. Attach selected product options (through SKU mappings) to each review.
  7. Return the fully prepared review response.

Supporting Functions​

fetchYotpoReviews​

Fetches reviews for one or multiple product IDs, applying filters and pagination. For bundles, it fetches reviews per product and aggregates the results.

getYotpoAccessToken​

Retrieves and caches the OAuth token necessary for accessing review metadata endpoints.

getReviewById​

Makes direct calls to Yotpo's API for reviews by product ID, supporting both simple and filtered queries.

aggregateMetadataIntoReviews​

Fetches metadata for each review (e.g., product specs) and merges it into the review objects. Handles bundles and single products differently.

fetchReviewMetadata​

Fetches metadata for a single review by review ID using the Yotpo API.

getSelectedOptionsForReviews​

Fetches selected product options (like SKUs) for each review and attaches them. We can use this data to find the color and size selection of the item. At the time of this writing (7/22/25), Yotpo doesn't correctly provide the correct SKU number the customer purchases and only sends back the first and smallest variant. Once this issue is resolved on their end, we will be able to use the size selection from their SKU.

prepareBundleProductResponse​

Aggregates reviews and statistics from multiple products in a bundle into a unified response.

extractFitScaleData​

Extracts custom fit scale data from review metadata for display purposes. This data is extracted to a higher level in the response so that the rollup can consume this data and show the averages of the product.

getPopularTopics​

Fetches popular review topics to enable topic-based filtering.

getReviewsWithImages​

Retrieves reviews containing images to display in the rollup review carousel. This function is also called to fetch more of these media containing reviews when a user navigates to the end of the carousel. Reviews are fetched in groups of 20.

Error Handling & Caching​

  • All external API calls are wrapped with error capture and logging via Sentry.
  • Responses are cached with appropriate cache strategies to reduce network load.
  • Failures in metadata or topic fetching handle fallbacks, returning empty or partial data without breaking the main review display.

Usage Notes​

  • This function is called in two places: product.$handle.tsx and api.yotpoReviews.tsx.
  • PDP page initially calls this function with no optional params other than handle, page, and perPage.
  • api.yotpoReviews.tsx calls this function from the Reviews Container component where the optional parameters are passed depending on customer interaction.
  • The module depends on environment variables for Yotpo API parameters, but some are limited and only exposed during the product environment.
  • Bundled product reviews require special attention due to their aggregated nature.
  • Review metadata can sometimes be null — client code will defensively check this.

Example Usage​

const yotpoResponse = await getProductReviews(
  { storefront, request, withCache },
  { handle: 'bg-product-handle', starRating: 5, page: 1, perPage: 4 }
);
console.log(yotpoResponse.reviews);