Email Marketing & Communications

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

Main use cases covered in this guide:

  • 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

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

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

  • Sync SMS subscribers & lists to Yotpo
  • Sync email subscribers & lists from Yotpo

📘

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.

📘

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 updates once every 24 hours and 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 and wait 24 hours 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 sync Is essential for segmentation and personalization of general marketing emails (not triggered by Loyalty events) when a merchant migrates from a different Loyalty provider to Yotpo, or if a client already has Yotpo Loyalty and is new to Your platform. In addition, there are times when a merchant might pause their Loyalty program or integration and need to re-sync all customers.

Exporting customers' loyalty data can be done by checking each customer via the retrieve loyalty customer details by email endpoint in the App Developer API. Syncing all customers since the last update date is not currently available. Alternatively, you can import these customers using a CSV file. Follow these instructions

If you need to pull all customers who interacted with Yotpo (ever or since the last date) you can use the retrieve customer details by date endpoint, and then pull the loyalty data one by one with the retrieve loyalty customer details by email endpoint.

The merchant will need to upload the CSV into your platform.

Please make sure that while you are running the historical data sync, you are also listening to the Yotpo Loyalty events (points changed) so that you are able to keep the points in sync in real-time.

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.

1102

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

For a draft file that explains how we segment the events (marketing / transactional), please see here.

Ideally, you should let the merchant determine which loyalty events require a marketing opt-in trigger email.
Some loyalty events, for example, point redemption, are considered by many merchants to be transactional (since the customer actively redeems points for a monetary value). Others, however, for example, point reminders/points for a birthday campaign, can be considered purely marketing.

If you must determine for the merchant whether the event is transactional or marketing, we recommend you seek advice from your privacy counsel. Please note that this document is a reference and does not contain legal advice.

The referral link share and referral share reminder events include both the information of the referrer and the referred friend. This email should be sent to the referred friend with the link/code that gives them the discount.

It is important not to opt the referred friend into other marketing emails, as they have not taken an action themselves to do so.

An additional scenario is when 2 events are triggered, for example, points earned and higher VIP tier gained. Please make sure to address this and decide what you want to communicate to the client.

📘

Please note:

We recommend creating email templates for each of the Yotpo events that your merchants can easily add to their accounts and save them valuable time. You can find recommended email content here.

Yotpo SMSBump

Sync email subscribers & lists from Yotpo to Shopify

We are currently in the process of developing APIs and webhooks that will allow syncing email subscribers and lists. In the meantime, partners may consume this information from Shopify by following these steps:

Step 1: Merchants will need to first go to the Yotpo SMS admin and follow these steps:

  1. From the side navigation, go to Subscribers > Collect Subscribers > Create New.
  2. Select the Subscriber Capture Tool that you'd like to use and enable Email capture (available in Pop up, Floating Button, embedded form, and footer).
  3. Don’t forget to Save and Publish the tool you just created.

Step 2: Create a new flow on SMSBump:

  1. Set Trigger action to be New Subscriber Confirmation.
    select a specific SMSBump Form.
  2. Add action - Tag in Shopify.
  3. Add tags that will show up in the customer profile on Shopify.

Test the flow you build for collecting subscribers. The result should be reflected in the Customers section in the Shopify admin. A new customer was created with the tag that was given to him as part of the flow.

If you have any questions, don’t hesitate to reach out to [email protected]