Generic (Other Platforms): Installing Yotpo Reviews (v3)

Goals and Outcomes

If you're using a custom-built store or a platform not officially supported by Yotpo, this guide will walk you through the full installation of Yotpo Reviews using our Core API v3. Designed for developers, this process covers everything from syncing your backend data to placing review widgets on your storefront, giving you full control over how Yotpo Reviews is integrated into your store’s experience.

Who should use this guide?

• Merchants using an eCommerce platform that is not listed as a Yotpo supported platform. Otherwise, we recommend you use the relevant platform-specific guide. See supported platforms.

• This guide is intended for new Yotpo customers, as it uses our Core API v3, released in April 2021. If you already installed Yotpo before this date, you may want to use our previous installation guide.

Process Overview

To provide its full range of capabilities, Yotpo integrates with both your store’s backend and front end. Because the two are decoupled, you have the flexibility to implement each integration separately based on your store’s specific setup. Yotpo’s APIs are designed to be highly customizable, allowing you to tailor the integration to your exact needs.

Note

This implementation will require extensive dev resources.

Getting Started

Before you begin working with Yotpo’s APIs, make sure you have your Yotpo App Key and API Secret available. If you manage multiple stores under your Yotpo account, each store will have its own unique API credentials.

Not sure how to find them? See Finding your Yotpo App Key and API Secret.

Syncing Your Store Backend

Our one-time API integration allows you to sync your store activity and related information to Yotpo, including orders, product catalog information, customers, and other store information required to configure Yotpo products. 

For example, the Core API allows you to integrate your backend with Yotpo for Reviews and then quickly add SMS with no integration downtime.

Tip

If this is your first time working with Yotpo’s APIs, we strongly recommend reviewing the Getting Started section in our API documentation to understand how to use our RESTful API.

Already integrated with another Yotpo product (like SMS)? You might not need to recreate existing services, such as products.

Step 1: Generate a UToken

Start by using your store's API credentials to generate a UToken. This token is required for authentication in all API requests. Note that the UToken may expire over time. If you receive an authentication error, you’ll need to regenerate it.

Step 2: Send Products to Yotpo

Sending product information to Yotpo is essential for:

• Triggering review request emails to your customers

• Displaying reviews on product pages and across marketing channels

• Tagging images with specific products

We recommend that you send a standalone product feed with products as they are created and updated in your system to keep your catalog in sync with Yotpo at all times. 

A few things to note about products:

• Variants: If you are listing products on Google Shopping or using Yotpo’s retail syndication with Walmart or other partners, you will need to include a feed of product variants associated with each parent product and include each variant’s unique product identifiers.

• Product hierarchy: We recommend sending Yotpo your parent-level products.

• Grouping products: You may group products together to share reviews or images both ways, by adding the same Group Name to two products. 

• Product Identifiers: We highly recommend including all available product identifiers, including SKU, MPN, Brand & GTIN with every product, so Google and other marketplaces can match your reviews and display them.

• Add a product to your blocklist: When you add a product to your blocklist, Yotpo will not trigger any automatic review requests for it.

• Review form tags: You can include a product tag to be used to create different review forms for different categories of products.

If you do not have the resources to create a separate product feed, you may send aggregated order info, coupled with the product information that will be used in Yotpo. By using this approach, you'll be able to sync your store information to Yotpo with a single API call. However, you may be limited from using certain Yotpo features such as tagging new products to images, product sampling integrations, Google seller rating, Google Shopping, or syndication, until the first order for that product is received.

Step 3: Send Orders to Yotpo

To enable automatic review requests, you must send your orders to Yotpo. We recommend sending us your orders as soon as they are created. We'll send out review requests only for fulfilled orders. You can set your order status by using the same order creation endpoint, or as a separate API call. Make sure you include the following fields: 

• fulfillment_date

• fulfillment_status=success

Yotpo will send the review request email a few days after the "fulfillment date," as defined in Yotpo Reviews.

Note

If you pass a cancellation object in the Create order API call, all scheduled review requests for this order will also be canceled. This action is not reversible.

Once your backend integration is complete, Yotpo will begin collecting reviews and allowing you to tag products.

To learn more, see How to use the Core API or reach out to your Yotpo representative or Yotpo Support.

Integrating Your Storefront

Integrating your storefront includes placing Yotpo’s core scripts and widgets in your storefront. These widgets will be automatically populated with the scoring and review content relevant to the product page.

Additionally, you can style your widgets via the cloud-based Yotpo admin to make sure they match your brand’s voice and tone.

Step 1: Add the JavaScript Library Code

To add the JavaScript to your store:

1. In your Yotpo Reviews main menu, go to On-Site Widgets and select Reviews Widget.

2. Click Publish at the top right corner. You will see a popup with 2 code snippets. The top snippet contains the Javascript code you need to add to your store.

3. Copy the code and paste it in the <head> tag.

This code enables Yotpo elements to appear in your store. The other elements will appear on your store once you add the rest of the code snippets.

Step 2: Add the Reviews Widget

The Reviews Widget allows you to showcase your reviews on product pages in a fully customizable format. Each review will appear with a title, review content, and its associated star rating.

To add the Reviews Widget to your website:

1. In your Yotpo Reviews main menu, go to On-Site Widgets, and select Reviews Widget.

2. Click Publish at the top right corner. You will see a popup with 2 code snippets. The bottom snippet contains the relevant code.

3.  Copy the code and paste it so it appears across your product pages.

Make sure you replace each data element with the appropriate values of your website and product attributes.

The data-product-id attribute supports only alphanumeric (a...z, A...Z, 0...9) and "_" and "-" symbols.

Step 3: Add the Star Rating

The Star Rating reflects the average aggregated rating of a product's published reviews and offers an easy way to link shoppers to read full reviews on your site. The star rating will appear only next to products that have reviews. When the star rating is installed, clicking on it will bring you to all the reviews of the product. For this reason, people usually insert the star rating code somewhere close to the product description near the top of the page.

To add the Srat Rating to your website:

1. In your Yotpo Reviews main menu, go to On-Site Widgets, and select Star Rating.

2. Click Publish at the top right corner. You will see a popup with 2 code snippets. The bottom snippet contains the relevant code.

3.  Copy the code and paste it so it appears across your product pages.

Make sure you replace each data element with the appropriate values of your website and product attributes.

The data-product-id attribute supports only alphanumeric (a...z, A...Z, 0...9) and "_" and "-" symbols.

Tip

To add the star rating widget on the collection page, place the same code in your category/collection page file.

Step 4: Add Additional Widgets (optional)

Yotpo offers a wide range of on-site widgets that you can add to your store in addition to our core features. View the list below and click the relevant link to learn more:

• Reviews Badge

• Reviews Widget Smart Filters

• Review Highlights

• Reviews Tab

• Promoted Products

• SEO Page

Step 5: Set Up Conversion Tracking

Yotpo helps you leverage your reviews to drive traffic to your store and increase your sales. The Conversion Tracking code enables you to measure those gains.

Following each successful checkout submission, Yotpo validates if the visit and sale were generated by Yotpo or self-served.

The Conversion Tracking code below should be loaded after each purchase is completed, on the order confirmation page:

<script type="text/javascript">(function e(){var e=document.createElement("script");e.type="text/javascript",e.async=true,e.src="//staticw2.yotpo.com/{{APP_KEY}}/widget.js";var t=document.getElementsByTagName("script")[0];t.parentNode.insertBefore(e,t)})();</script><script>yotpoTrackConversionData = {orderId: "######ORDER_ID######", orderAmount: "######ORDER_AMOUNT#####", orderCurrency: "######ORDER_CURRENCY#####"}</script><noscript><img src="//api.yotpo.com/conversion_tracking.gif?app_key={{APP_KEY}}&order_id=######ORDER_ID######&order_amount=######ORDER_AMOUNT#####&order_currency=######CURRENCY######" width="1" height="1"></noscript>

Important

Make sure to replace the two {{APP_KEY}} portions of the code with the App Key from your account. Please note that the brackets must be removed as well.

Additionally, replace the ######ORDER_ID#####, ######ORDER_AMOUNT##### - total amount paid for the order, and ######ORDER_CURRENCY##### portions of the code with the correct placeholders.

Can't find your App Key? Click here.

Additional Resources

• Core API reference

• API changelog