API referenceCore APIUGC APILoyalty APIHelp Center

Product Recommendations

This guide details how you can integrate Yotpo Reviews and Yotpo Visual UGC with your Product Recommendation platform or features to add social proof to your experience and increase user engagement for shared merchants.

Main use cases covered in this guide:

📘

Have you registered your app yet?

Before you start building your app on top of Yotpo’s App Developer API, you first need to register it with us. If you haven’t done so yet, refer to the steps in our Welcome guide.

Displaying the star rating for a product

There are 3 options for returning a product’s average rating and review count (for reviews published by the merchant):

  1. Using Yotpo’s out-of-the-box on-site widgets
  2. Returning the HTML & CSS Payload via API
  3. Returning the average score and review count data fields via API

Here are additional details on each of these options:

Using Yotpo’s ‘out of the box’ on-site widgets

  1. First, you will need to add the JavaScript library code to the on-site asset you want Yotpo to be displayed on (get the Yotpo app key value from the OAuth flow. If you are trying to load the Yotpo elements on a page that is hosted on the merchant’s eCommerce website, the JS library will most likely already be available in the header.
  2. Add the Star Rating element where you want it to appear next to the relevant product.
  3. Populate the ‘data-product-id’ value in the HTML snippets with the eCommerce platform’s parent product_id.
  4. Since Yotpo loads asynchronously, you may need to reload Yotpo’s widgets using AJAX after your own elements are loaded, do so following this guide.

Retrieve the HTML snippet via API using the ‘bottom line’ method and repeat steps 2 - 4 above

By retrieving the full HTML payload of the Yotpo Star Rating element, you will not need to implement the JS Library and can refresh the data as frequently as you’d like, while taking advantage of the existing look and feel the merchant has configured within Yotpo.

Pull the review count and average score using the product star rating endpoint

You will need to create the look and feel using this data and refresh it as frequently as needed (we recommended once every 1-3 hours).

Display top reviews or sentences for a product

Similar to the Star Rating element, there are 2 options for displaying a product’s top reviews or sentences next to products:

  1. Using Yotpo’s out-of-the-box on-site widgets
  2. Returning the data via API

Here are additional details on each of these options:

Using Yotpo’s out-of-the-box on-site widgets

  • First, you will need to add the JavaScript library code to the on-site asset you want Yotpo to be displayed on (get the Yotpo app key value from the OAuth flow. If you are trying to load the Yotpo elements on a page that is hosted on the merchant’s eCommerce website, the JS library will most likely already be available in the header.
  • If the website and reviews are in English, you may want to use the Review Highlights widget, which leverages Yotpo’s AI algorithm for determining the top reviews/sentences. Place the widget where you want it to appear next to the relevant product. Hide the “Read More Review” element of the widget using local CSS (the button will not work unless the ‘main reviews widget’ for that product is placed on the same page).
    If the website and reviews are in any other language, you can use the Reviews Carousel widget using the code below, and use CSS to hide any elements you do not need:
<div class="yotpo yotpo-reviews-carousel" 
 data-background-color="transparent" 
 data-mode="top_rated" 
 data-type="per_product" 
 data-count="3" 
 data-product-id="dataproduct-id">&nbsp;</div>
  • Populate the -‘dataproduct-id’ value in the HTML snippets with the eCommerce platform’s parent product_id.
  • Since Yotpo loads asynchronously, you may need to reload Yotpo’s widgets using AJAX after your own elements are loaded, do so following this guide.

Retrieve the top product reviews and sentences via API:

  • If the website and reviews are in English, you may use the best reviews or best sentences endpoints to retrieve your top product reviews. These endpoints will return only published reviews that were detected as high quality and positive by our AI algorithm.
  • Even if your website is in English, we recommend having a fallback option using the more simple Top reviews endpointin case no reviews were returned by the API. If the website/reviews are not in English, this can be used as your first option.
  • If the top reviews endpoint also comes back empty, this probably means that there are no positive published reviews, in which case you can return the top general reviews (about the site/service) by using the same APIs above using “yotpo_site_reviews” as the product ID - this will return the top reviews the merchant collected on their brand and marked in Yotpo as ‘site reviews’. Learn more here.

Display customer photos for a product

📘

Please note

The merchant must have the Yotpo Visual UGC product to leverage this capability.

You can display photos or videos that were handpicked and published by the brand within Yotpo Visual UGC and display them in your abandoned cart messages and promotional communications by using the Product images endpoint. The endpoint may be called in real-time when displaying the product or by storing the images for each product and updating them daily.

We recommend first trying to retrieve ‘Favorited’ images - these are images that the merchant marked as a favorite while publishing the content in Yotpo, in order for these images to be prioritized when they are displayed. If no images are returned as favorited, you may return any other images for the product - the endpoint will only return images that were published by the brand and as such are ok to use.

Some products may not have any tagged and published images, in which case the API will be returned empty. We recommend falling back to the stock image or some other branded image for these cases.

Inject product recommendations into Yotpo SMS & Email flows

By using the Create or Update Custom Customer Event endpoint, you can send custom events with product recommendations that will trigger flows in Yotpo SMS & Email, if set up by the merchant. These custom event properties can include the recommended product’s name and URL.

Some examples of communications that can be sent include order completed, product page view, etc.

You can also include any metadata associated with the event to create personalized segments and campaigns. Additionally, you can include any relevant elements in the “event_properties” such as custom URLs, promotion codes, etc, to be used as shortcodes within the SMS.

Once the custom event has been sent, you can follow the below steps to set up an SMS campaign:

  1. After you send the event, you can access it in the Yotpo SMS & Email admin in Flows & Automations > Custom Triggers.
  2. In order to use them in a flow, you’ll need to manually enable the toggle to Display as a trigger.
  3. You can view and edit any flows in the Flows section, located in the same Flows & Automations tab as the Custom Triggers.

🚧

Please note:

  • You must send all sample payloads in a Google doc to [email protected].
  • After the integration is tested and approved, we will reveal the triggers to all merchants in the flows section of the admin (as opposed to in the custom triggers section).
  • Please also provide us with a start install URL for the integration and a link to the integration help article so we can direct merchants who have not yet installed the integration to be able to do so.
  • For more detailed information on how to leverage Yotpo SMS & Email flows, check out this guide.

👍

On our roadmap for future development:

Coming soon, you'll be able to include any custom properties associated with the customer for creating personalized segments and campaigns. You will also be able to build conditional logic leveraging properties sent in event_properties.

👍

Got questions?

Contact us at [email protected].

Updated 12 months ago