Email Marketing & Communications

This guide details the most popular use cases for integrating reviews, visual user-generated content (UGC), and loyalty and referrals with your marketing communications platform.

Main use cases covered in this toolkit:

Yotpo Reviews

Display a product’s star rating and the average score
Display top product reviews and AI sentences
Segment customers based on recent reviews & aggregated data
Trigger follow-up messages and flows based on review

Yotpo Visual UGC

Display visual UGC on a product
Display visual UGC from any custom album

Yotpo Loyalty & Referrals

Sync historical customer data for segmentation and personalization
Trigger emails and update customer profiles based on loyalty events and milestones

📘
Please note:
Each of the listed use cases requires that the customer has the applicable Yotpo Product (Reviews, Visual UGC, and Loyalty) available to them and installed.

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

Yotpo Reviews

Sync product data, including review quantity, average score, and top reviews and images between Yotpo and your platform in order to increase click-through rates on products, abandoned cart messages, and more.

Display a product’s star rating and average score

Retrieve product data using the product or all products endpoints, either to display it in real-time or to store it in your system. We recommend refreshing the data every day or every few hours.

These endpoints allow you to retrieve published data on products in the Yotpo system, including their average review score (average_score) and the total number of reviews written about them (total_reviews).

Get top product reviews and AI sentences

Use the best reviews or best sentences endpoint to retrieve your top product reviews. These endpoints will return only published reviews with a positive overall sentiment score, using Yotpo’s powerful AI engine.

Make sure you provide the external_product_id parameter to pull relevant reviews about the actual product and not store or site reviews.

Since these endpoints utilize an AI (NLP) engine that works on English reviews only, you can use the top reviews endpoint as an alternative endpoint for non-English language stores and as a fall-back when a product does not have enough reviews with a positive sentiment score.

In the case that both endpoints do not retrieve any reviews (the product does not have positive enough reviews) we recommend pulling reviews for the product yotpo_site_reviews as a fallback (will return reviews collected about the brand/business).

Segment customers based on recent reviews & custom questions

To return the latest customer reviews, including answers to custom questions, and enhance your segmentation capabilities, simply retrieve all reviews and query by the customer’s email address or last sync date. This will return all reviews that have been updated in Yotpo, whether created or published/unpublished, since that date.

Segment customers based on aggregated data

Yotpo’s customer endpoints allow partners to pull a consumer’s record from Yotpo’s centralized CDP. This data can be pulled by customer email address or in bulk for all records updated since a set date using the Retrieve Customers endpoint.

📘
Please note:

Although some loyalty data is also available in this call, we recommend using the reviews information only (see below for Loyalty integration best practices).

Yotpo’s CDP will only return verified reviews . Anonymous reviews, submitted on-site and not yet verified by the reviewer will not be returned even if published. If you are testing your app using a test account, make sure to verify your email when creating reviews to successfully retrieve this data.

Trigger follow-up messages and flows based on review

Use the review_create webhook event to set up follow-up messages for new reviews that were just received from a customer. You can use the review score to create different follow-up flows for positive reviews vs. negative reviews.

📘
Please note:

You may use the include_nested parameter to include user data, for example, the user that wrote the review.

According to Google’s reviews policies, site reviews cannot be incentivized in any way, while product reviews can. If you offer incentives through your platform, make sure to allow merchants to differentiate between site and product reviews using the review_type_id field in the response. When =1, the review is a product review and can be incentivized. When =2, the review was collected as a site review and must not be rewarded in any way.

Some merchants may also want to differentiate between verified buyer reviews, which are submitted automatically post-purchase and are therefore more authentic and valuable from a brand perspective, and anonymous reviews.

Announce to a customer that a review was published on the website

Use the review_updated webhook event to notify a consumer that their review was published on the website and bring them back to your website.

📘
Please note:

The webhook only means the review was published if ‘deleted’ = ‘false’ for the first time. The webhook may trigger when later moderation changes are made to the review, which the brand might not want to trigger an event for.

Some merchants might also be interested in collecting reviews through your platform. To ensure the authenticity of the content collected, we do not currently offer this use case.

Yotpo Visual UGC

Display visual UGC on a product

Display photos or videos that were handpicked and published by the brand on abandoned carts and promotional communications by pulling them from the product images endpoint in real-time or storing them while updating at least daily.

Display visual UGC from an album

Display a gallery of photos or videos that the brand curated as a custom album. Just get the album ID from the photos or videos and then use the photos by album endpoint.

Yotpo Loyalty & Referrals

Sync historical customer data for segmentation and personalization

The historical customer sync is essential for segmentation and personalization of general marketing emails when a merchant already has loyalty members in Yotpo. In addition, there are times when a merchant might pause their Loyalty program or integration and need to re-sync all customers since a certain date. For both of these scenarios, you can use the ‘retrieve customers’ endpoint. This endpoint returns the most used loyalty properties only - if you’d like to retrieve all loyalty properties on a profile, you will need to run a subsequent call for each profile that has loyalty data, using the ‘fetch customer’ endpoint.

Another option (although far less optimal) is asking merchants to export customers from Yotpo manually (as CSV) and importing them into your system, the steps to do this in Yotpo can be found in this article.

📘
Please note:
If the loyalty program is running while you run your historical customer sync, make sure that you are also listening to the points changed and tier status changed events and updating profiles, to avoid missing any changes.

Trigger emails and update customer profiles based on loyalty events and milestones

To start, the brand must implement your webhook URL in their Yotpo Loyalty admin settings. The merchant can also add an authentication header within Yotpo that will help you securely identify the merchant and origin of the webhook events. We recommend allowing the merchant to provide both systems with the specific authentication header they would like to use as Yotpo supports multiple webhook URLs (comma separated) but only one authentication header. This will avoid forcing the merchant to work insecurely or sharing your private key on another platform.

Once the webhook URL is placed in the admin, we recommend listening to and exposing to the merchant all webhook events listed here. The points changed event is specifically relevant for updating the customer record in your platform and keeping both systems in sync in real-time. Note that some of the other event payloads may include the same information that is being updated, but may also include specific fields that are relevant to that event and should be available for the merchant in the email content. Make sure to document these fields and how to use them in your platform.

🚧
Important!

Multiple webhook URLs should be separated by a semicolon comma

Webhook authentication can be populated with one string value only

Other important considerations

For Email Marketing integrations, we strongly recommend exposing all webhook events listed here, as flow triggers in your system.
The points changed & VIP tier changed events are specifically relevant for updating the customer profile in your platform and keeping profiles in both systems in sync in real-time. This is required to allow merchants to use loyalty data accurately for segmentation and personalization of messages in your system.
Note that multiple events may fire at the same time, so merchants will need a way to determine priorities between events in flows.
Note that sometimes events may fire more than once, due to retries when a response was delayed on your end. In that case, it’s important to filter out the recurring event fired.
Most events will include the primary loyalty information on a customer, but may also include specific properties that are relevant to that specific event only (for example a personalized referral link or coupon code) that should be made available to be used in the specific flow as content and conditions (make sure to document these fields and how to use them in emails for your merchants).
The ideal situation is to let the merchant determine whether to send each loyalty event triggered email as marketing or transactional, as this could vary by country / industry & legal advisor. If you need to pre-define which of the events will be sent as marketing vs. transactional messages, this link provides our recommendation (but please note that this is not a legally binding recommendation and you should rely on your own legal / privacy experts to make a final decision).
The Referral Link Share event and Referral Share Reminder event includes both the information of the referrer and the referred friend. These events are primarily used to send an email to the referred friend with the link/code that gives them the discount. That being said, because the referred friend typically never opted-in to marketing emails, it is important to send this email as a one time email and not to opt-in the referred friend into other marketing emails, as they have not taken an action themselves to do so.

📘
Please note:
We strongly recommend creating email & flow templates for each of the Yotpo events so that your merchants can easily add to their accounts and save them valuable time. Recommended email copies / flows can be found here.

Toolkit last update - (April 2023)