Yotpo Api

The Yotpo Developer Hub

Welcome to the Yotpo developer hub. You'll find comprehensive guides and documentation to help you start working with Yotpo as quickly as possible, as well as support if you get stuck. Let's jump right in!

Guides    
Suggest Edits

Getting Started

This page contains general information about Yotpo API calls.

 

Welcome to Yotpo's Core API Reference :wave+:

Here you'll find all the endpoints you need to leverage UGC data from Yotpo throughout your store.
Yotpo's core API endpoints allow you to retrieve data on reviews, products, users, and much much more.

App Market API

If you're building a publicly-available app or integration, you'll find everything you need to get started in Yotpo's Developer Portal and App Market API reference!

Before you get started, we recommend reviewing the guidelines below :point-down+:

Protocol Support

The Yotpo API supports both HTTP and HTTPS requests.

Data Format

Data must be in JSON format. As such, the HTTP header content-type must be set to: application/json

Pagination

Use the following parameters to paginate results in API requests which support pagination:
page - Number of pages to return
count - Number of results to return per page

Status Code

Yotpo API uses standard HTTP response codes to indicate the success of failure status of an API endpoint.

Response Code
Status

200

Successful Response

401

Unauthorized Request

500

Internal Server Error e.g. Timeout

Note:

Certain API calls return special responses to indicate specific errors.
Special responses are noted for relevant API endpoints within the documentation.

Authentication

Yotpo uses tokens to authenticate and authorize an account. Tokens are generated by an API call that uses the client ID and client secret. See the Token API Reference Guide.
A token is required in non-public API calls to ensure private account data is accessible only by authorized users.

Note:

Each token expires after 14 days since creation and will no longer be useable.

Parameters

Email and URL parameters you send in the calls must be in the correct format, otherwise the call will not be processed.

Parameter
Format
Example

email

user@domain

jsmith@yotpo.com

Date

YYYY-MM-DD

2017-12-31

UTF-8 Support

The Yotpo API calls support special characters according to the UTF-8 coding.

Finding Your API Key (Appkey)

The API key and API secret are unique codes for your account. You need the API key to perform most API calls and the API secret to generate the utoken.

If you need help finding your API key and API secret, see this article.

API Secret

The API secret is only visible to Yotpo account administrators. Users with staff permissions cannot view the API secret.

Data Validation: `validate_data` settings and default.

The validate_data parameter provides additional input validation for the following Purchases endpoints:

By default, validate_data is set as true to help catch errors and prevent issues with your orders.
To disable data validation, simple set the validate_data parameter as false (not recommended).

Suggest Edits

Introduction to Account Platform

 

What is the Account Platform?

The Account Platform is the store platform that you use, for example Shopify. The platform can be hosted or unhosted.

What can you do with App?

POST /apps/{app_key}/account_platform

Suggest Edits

Set the Ecommerce Platform That This Account Integrates With

 
posthttps://api.yotpo.com/apps/:app_key/account_platform
POST https://api.yotpo.com/apps/YOUR_APP_KEY/account_platform
-------------------------------------------------------------------------

{
    "account_platform": {
        "shop_domain": "http://myshop.com",
        "platform_type_id": "4"
            },
    "utoken": "YOUR_UTOKEN"
} 
A binary file was returned

You couldn't be authenticated

200 (OK)
Content-Type: application/json
{
  "status" : {
    "code" : 200,
    "message" : "OK"
  },
  "response" : {
    "account_platform" : {
      "id" : 8,
      "shop_token" : "",
      "shop_domain" : "http://myshop.com",
      "shop_api_url" : null,
      "plan_name" : "",
      "platform_type" : {
        "id" : 4,
        "name" : "3dcart",
        "description" : null,
        "billable" : false
      },
      "deleted" : false,
      "shop_user_name" : null
    }
  }
} 

Body Params

account_platform
object
account_platform.shop_domain
string
required

Your shop’s domain, starting with http://, for example https://www.yourawesomeshop.com/

account_platform.platform_type_id
string
required

Your e-commerce platform, for example 3dcart

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your utoken.

 

Platform Type IDs

Platform ID
ID

Shopify

1

Any other platform

2

Bigcommerce

3

3dcart

4

Magento

5

Volusion

6

Shopping Cart Elite

7

Prestashop

8

CS-Cart

9

Opencart

10

ebay

11

WooCommerce

12

Storenvy

13

Tictail

17

Symphony

19

Commerce_Guys

20

Go_Daddy_Commerce

21

Lightspeed

22

Zepo

23

Suggest Edits

Yotpo Authentication

This endpoint uses your Yotpo App Key and Secret Key to generate the API utoken necessary to authenticate most of Yotpo's API calls. Note that utokens are valid for 14 days from the time they are generated. After 14 days, your utoken will expire and a new utoken must be generated.

 
posthttps://api.yotpo.com/oauth/token
{
  "client_id": "YOUR client_id",
  "client_secret": "YOUR client_secret",
  "grant_type": "client_credentials"
}
A binary file was returned

You couldn't be authenticated

{
  "access_token": "YOUR_UTOKEN",
  "token_type": "bearer"
}
{
    "status": {
        "message": "Couldn't find Account with app_key = ",
        "code": 404,
        "error_type": "Exceptions::RecordNotFound"
    }
}
{
  "error": "unsupported_grant_type"
}
{
    "error": "invalid_client"
}

Body Params

client_id
string
required

Also referred to as API key. See the note below.

client_secret
string
required

Also referred to as API secret. See the note below.

grant_type
string
required

Must be client_credentials.

 

Note:

The API key and API secret are unique codes for your account. You need the API key to perform most API calls and the API secret to generate the utoken.

To find your API key and API secret, see this article.

utokens (user tokens) are used to authenticate and authorize an account. A utoken is required in non-public API calls to ensure private account data is accessible only by authorized users.

Important:

utokens are valid for 14 days from the time they are generated. After 14 days, your utoken will expire and a new utoken must be generated.

Suggest Edits

Retrieve the Reviews Payload in HTML

 

Definition

Body

Parameter
Type
Description

app_key

string

Your Yotpo account API key

methods[method]

string

An array of widget types (methods) and an hash of the parameters for each method.

methods[params]

object

The specific parameters for the method

is_mobile

boolean false

Defines if the response should be for a mobile device or a desktop

Reviews Widget

In order for the Reviews Widget to appear on product pages, be sure to add the HTML below to your product page template. Replace each data element with the appropriate values of your website and product attributes. Note that the data-product-id attribute only supports alphanumeric (a...z, A...Z, 0...9) and "_" and "-" symbols. :point-down+:

<div class="yotpo yotpo-main-widget"
data-product-id="SKU/Product_ID"
data-price="Product Price"
data-currency="Price Currency"
data-name="Product Title"
data-url="The url to the page where the product is (url escaped)"
data-image-url="The product image url. Url escaped">
</div>

Batch Payload Types

Methods
Parameters
Batch Result

main_widget

pid - The product SKU for which to bring the main reviews widget.

page (optional) -
The page number of the reviews page as applied by the Reviews Widget.
The current reviews page will be passed as a query param called yoReviewsPage

Full HTML of a reviews widget which belongs to a specific product

bottomline

pid - The product SKU for which to bring the bottom line widget.

skip_average_score - Boolean value to show or hide the average score in the bottom line.

format - The format to return the result
HTML (default)
JSON

Star rating widget that belongs to the same specific product

testimonials

data-product-readonly - A flag to enable or disable the ability to write new reviews (false if not specified)

Reviews tab that opens the site and product reviews pop-up

embedded

per_page - Number of reviews per page

view - Customizations for the embedded widget. Refer to your Yotpo Admin page as well.
type
layout
width
headerText
transparency
headerBackgroundColor
bodyBackgroundColor
fontSize
fontColor

Embedded widget.

badge

None ("params" : {})

The Yotpo badge

questions_bottomline

pid- The product SKU for which to bring the questions and answers

A summary of the number of questions and answers per product

Example

POST http://staticw2.yotpo.com/batch?
{
  "methods": [{
      "method":"main_widget",
      "params": {
        "pid": "334342199",
         "page":"2"
       }
  },
{
  "method":"bottomline",
      "params": {
        "pid": "334342199"
       },
  "format": "json"
  }
],
"app_key":"YOUR_APP_KEY"
  },
{
  "methods": [{
      "method":"testimonials",
      "params":{"type":"testimonials","pid":"11643860358"}
  }
],
"app_key":"YOUR_APP_KEY"
}

Result Format

[
	{
		"method":"main_widget",
		"result":"<div class="yotpo-display-wrapper yotpo-no-reviews" style="visibility: hidden;">    <div class="yotpo-label yotpo-small-box "> ....... // HTML is cut for brevity"},
	{	"method":"bottomline",
	"result":"<span class="yotpo-display-wrapper" style="visibility: hidden;">  <div class="standalone-bottomline"> .... // HTML is cut for brevity"
	}
]

The methods parameter is an array of methods. Each method is a hash containing the method and parameters, which is an hash of the parameters for the method.

Note:

Include the an empty params attribute - "params" : {} - for the badge method.

Note:

The pid parameter is mandatory.
The pid parameter cannot contain the "/" symbol.

Note:

It is highly recommended to develop a cache mechanism to save the payload locally and to refresh it periodically. The purpose of this caching is to avoid long loading times every time the widget loads.

Suggest Edits

Introduction to Dynamic Coupons

Coupons are a great way to encourage your customers to write reviews and to give them an incentive to return to your store as repeat shoppers.

 

The Purchases resource is used to upload, delete and retrieve dynamic coupon codes. Dynamic codes are unique for each coupon.

Note:

Enable Dynamic Coupons in your Yotpo Admin before using the API calls. See the Coupons article at: https://support.yotpo.com/hc/en-us/articles/204102156-Coupons for information.

What can you do with Coupons?

The following calls API calls are available:

Delete a coupon action's unique codes

Retrieve all dynamic coupon codes

Retrieve dynamic code statistics

Upload dynamic coupon codes

Suggest Edits

Upload Dynamic Coupon Codes

 
posthttps://api.yotpo.com/apps/:app_key/coupons/unique
POST https://api.yotpo.com/apps/YOUR_APP_KEY/coupons/unique
------------------------------------------------------------------------


{
   "utoken": "YOUR_UTOKEN",
   "coupon_action": "map_review",
   "codes": ["sdfj789klvd", "sdfsfd1313jkl", "mkklwlwer43qkjl"]
}
A binary file was returned

You couldn't be authenticated

{
  "status: {
      "code": 200
      "message": "OK"
  }
  "response": {
      "total_codes": 20
      "errors": {
          "empty_cell": {
               "error_text": "Empty cells",
               "error_count": 0
      }
           "code_length": {
               "error_text": "Max/Min code digit requirements",
               "error_count": 0
      }
           "duplicate_code": {
               "error_text": "Duplicated content",
               "error_count": 0
      },
      "new-codes": 3
   }
}

Body Params

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your utoken.

coupon_action
string
required

Which review request mail to apply the coupon to.

codes
string
required

Array of dynamic coupon codes

 

Note:

You can upload up to 1,000 codes.

Coupon Actions

These are the available coupon actions:

Issue coupon when...
Parameter

The customer writes a product or site review

map_review

The customer shares a review on the Landing Page

map_share

The customer writes and shares a review

map_review_share

Error codes

These are the error codes that can appear in the response.

Code
Description

empty_cells
"Empty cells"

The array you uploaded contains empty dynamic coupon codes.

code_length
"Max/Min code digit requirements"

The dynamic coupon code is too long to too short.

duplicate_code
"Duplicated content"

You used the same dynamic coupon code more than once. The codes must be unique.

Suggest Edits

Retrieve All Dynamic Coupon Codes

 
gethttps://api.yotpo.com/apps/app_key/coupons/unique?utoken=:token
GET https://api.yotpo.com/apps/YOUR_APP_KEY/coupons/unique?utoken=YOUR_UTOKEN
A binary file was returned

You couldn't be authenticated

{
  "status": {
      "code": 200
      "message": "OK"
  },
  "response": {
      "coupons": {
        {
              "code": "couponNum0"
        },
        {
              "code": "couponNum1"
        },
        {
              "code": "couponNum10" 
        },
        {
              "code": "couponNum100"
        },
        {
              "code": "couponNum1000"
        },
        {
              "code": "couponNum101"
        },
        {
              "code": "couponNum102"
        },
        {
              "code": "couponNum103"
        },
        {
              "code": "couponNum104"
        },
        {
              "code": "couponNum105"
        }
  }
}

Path Params

app_key
string
required

Your Yotpo account API key

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your utoken.

 
Suggest Edits

Retrieve Dynamic Coupon Code Statistics

 
gethttps://api.yotpo.com/apps/app_key/coupons/unique/stats?utoken=:token
GET https://api.yotpo.com/apps/YOUR_APP_KEY/coupons/unique/stats?utoken=YOUR_UTOKEN
A binary file was returned

You couldn't be authenticated

{
  "status": {
      "code": 200
      "message": "OK"
  }
  "response": {
      "stats": {
          "map_review": 17,
          "map_review_share": 1002
      }
  }
}

Path Params

app_key
string
required

Your Yotpo account API key

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your utoken.

 

Note:

The values in the result are the number of dynamic coupon codes for each action.

Suggest Edits

Delete a Dynamic Coupon Action's Codes

 
posthttps://api.yotpo.com/apps/:app_key/coupons/unique/delete
POST https://api.yotpo.com/apps/YOUR_APP_KEY/coupons/unique/delete
-------------------------------------------------------------------------------

{
   "utoken": "YOUR_UTOKEN",
   "coupon_action": "map_review"
}
A binary file was returned

You couldn't be authenticated

{
   "status": {
       "code": 200
       "message": "OK"
   }
}

Body Params

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your utoken.

coupon_action
string
required

Which review request mail to apply the coupon to.

 

Coupon Actions

Issue coupon when...
Parameter

The customer writes a product or site review

map_review

The customer shares a review on the Landing Page

map_share

The customer writes and shares a review

map_review_share

Suggest Edits

Intro to Email Analytics

Email analytics endpoints allow you to retrieve data on review request emails, reminder emails, coupons, comments, and other correspondences sent through the Yotpo system. Receive analytics on emails sent, read, and bounced as well as content generated through emails, click through rate from emails, and more. Retrieve analytics data as raw or grouped data for the data range specified and export data as a .csv file.

 

The tables below contain the email analytics metric types and supported email types.
Use these values for the metric_name and email_type parameters.

Note:

The since and until parameters always refer to sent emails, regardless of which metric was requested. Metrics are retrieved from emails which were sent within the date range defined.

For example, if you're requesting data on reviews within the date range of Jan 01 (since) - Jan 05 (until), note that while the review request emails were sent within the date range, the actual reviews may have only been created after Jan 05 (until).

Email Analytics Metrics

Use the metric names listed below to retrieve aggregated email analytics data.
Metric names are path parameters which describe the aggregated metric you'll receive in the response. Use one metric per request.

Note:

  • Each metric supports all parameters with the exception of answers_from_emails which only supports the date range since/until and date_bucket parameters.

  • Each metric supports all email types with the exception of reviews_from_emails which does not support: answer_request, comment_notification, answer_notification, coupon_email, coupon_reminder, coupons_and_notifications

Use the metrics listed below for the metric_name parameter for the following endpoints:

Metric Name
Description

emails_sent

The sum of all emails sent through Yotpo.

emails_opened

The sum of emails opened out of emails_sent

reviews_from_emails

The sum of reviews out of emails_sent

Supports all email types except:

  • answer_request
  • comment_notification
  • answer_notification
  • coupon_email
  • coupon_reminder
  • coupons_and_notifications

answers_from_emails

The sum of answers out of emails_sent

An 'Answer Request' is a request to provide an answer to a question.

click_throughs

The sum of clicks which drive customers from the email to the website.
e.g. clicking on the product page link

invalid_address

The sum of hard bounces.

A hard bounce might occur because the email address is invalid or because the recipient is unknown.

emails_failed

The sum of emails which were not delivered for reasons other than a hard bounce.

arrived_early

The sum of unique users that clicked on
"Did not receive the product" within the email.

marked_spam

The sum of unique users that clicked on "Mark as spam" within the email.

unsubscribed

The sum of unique users that clicked "unsubscribe" within the email.

Supported Email Types

Use the email type values below for the email_type parameter for the following endpoints:

Tip:

To retrieve data for all email types sent through Yotpo, exclude email_type from your request.

Supported Email Types
Description

all_review_emails

All review request emails sent.

e.g. mail after purchase, reminder, targeted_review_request, mail_after_service, mail_after_invoice

all_maps

All Mail After Purchase product and site review request emails including reminder emails.

e.g. mail after purchase, reminder

map

Mail After Purchase review request emails excluding reminder emails. Includes only the first email sent to a customer to request a site or product review.

all_reminders

All reminder emails. Includes all emails sent to remind a customer about pending site or product review requests.

reminder

A specific site or product review request reminder email. To target a specific reminder, the reminder email type should be accompanied by the reminder_num parameter.

e.g. If there are 3 emails configured and you'd like to retrieve analytics for the second email reminder sent, request reminder_num: 2

all_product_map

All sent Mail After Purchase product review request emails including reminders.

product_map

The first Mail After Purchase product review request email sent.

all_product_reminders

All subsequent reminder emails sent for product reviews.

e.g. If you have configured 3 emails to be sent (MAP +Reminder 1, Reminder 2) this value will return analytics for the two reminder emails.

product_reminder

A specific product review request reminder email. To target a specific reminder, the reminder email type should be accompanied by the reminder_num parameter.

e.g. If there are 3 emails configured and you'd like to retrieve analytics for the second email reminder sent, request reminder_num: 2

all_site_map

All mail after purchase requests for site review request emails including reminders.

site_map

The first email sent after purchase to request site reviews.

all_site_reminders

All subsequent reminder emails sent for site reviews.

e.g. If you have configured 3 emails to be sent (MAP +Reminder 1, Reminder 2) this value will return analytics for the two reminder emails.

site_reminder

A specific site review request reminder email. To target a specific reminder, the reminder email type should be accompanied by the reminder_num parameter.

e.g. If there are 3 emails configured and you'd like to retrieve analytics for the second email reminder sent, request reminder_num: 2

targeted_review_request

All emails sent by .csv upload including site and product review requests.

targeted_site_review_request

All site review request emails sent by .csv upload.

targeted_product_review_request

All product review request emails sent by .csv upload.

mail_after_service

The site review request email sent following a closed support ticket through Help Desk Integration.

mail_after_invoice

The email sent due to the configuration of site review automation.

answer_request

The answer request email sent to past shoppers.

e.g. Ask a past shopper to answer a question asked on site.

resend_map

A request to resend a review request email submitted through Moderation in the Yotpo Admin.

comment_notification

Emails sent to notify reviewers that the merchant has made a comment on their review.

answer_notification

Emails sent to notify shoppers that their question has been answered.

coupon_email

Emails which include a coupon code sent to eligible customers or reviewers.

coupon_reminder

A reminder email sent to coupon recipients which reminds them to use their coupon.

all_coupons

All coupons including the initial coupon email as well as any coupon reminder emails.

Group By

Use the grouping values below for the {group_by} parameter for the following endpoints:

group_by
Description

batch_subject

The subject of the CSV upload.

  • eg TRR

email_type

The type of email from this list.

reminder_num

The number of the MAP reminder email.
Must be an integer greater than zero.

Suggest Edits

Email Analytics

Retrieve aggregated data for email metrics based on the defined email type value and group data by metrics.

 
gethttps://api.yotpo.com/analytics/v1/emails/app_key/metric_name?token=token
GET: https://api.yotpo.com/analytics/v1/emails/YOUR_APP_KEY/emails_sent?token=YOUR_TOKEN&since=2017-07-01&until=2017-08-20&date_bucket=day&email_type=reminder&group_by=reminder_num
GET https://api.yotpo.com/analytics/v1/emails/YOUR_APP_KEY/emails_sent?token=YOUR_UTOKEN
A binary file was returned

You couldn't be authenticated

{
    "date_series_points": [
        {
            "since": "2017-07-01",
            "until": "2017-07-01",
            "values": {}
        },
        {
            "since": "2017-07-02",
            "until": "2017-07-02",
            "values": {}
        },
        {
            "since": "2017-07-03",
            "until": "2017-07-03",
            "values": {}
        }
    ]
}
{
    "date_series_points": [
        {
            "since": "2017-07-15",
            "until": "2017-07-31",
            "values": {}
        },
        {
            "since": "2017-08-01",
            "until": "2017-08-15",
            "values": {}
        }
    ]
}

Path Params

app_key
string
required

Your Yotpo account API key

metric_name
string
required

Supports one metric per request. Choose a metric from the table of Email Analytics Metrics

Query Params

token
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your token.

since
date

Retrieve email analytics since and including this date (Default: Last 30 days). Note: until is required when using this param.

until
date

Retrieve email analytics until and including this date (Default: Last 30 days). Note: since is required when using this param.

date_bucket
date

Retrieve dates by date_bucket. Values can be day, month, or year. Default=month

reminder_num
int32

The number of the MAP reminder email. Must be an integer greater than zero and can only be used when the email type is product_reminder or site_reminder

email_type
string

Choose one email_type value from the table of Supported Email Types or exclude this parameter to retrieve data for all emails.

group_by
string

Returns itemized grouped data. Choose a group_by value from this table

 

Note:

The since and until parameters always refer to sent emails, regardless of which metric was requested. Metrics are retrieved from emails which were sent within the date range defined.

For example, if you're requesting data on reviews within the date range of Jan 01 (since) - Jan 05 (until), note that while the review request emails were sent within the date range, the actual reviews may have only been created after Jan 05 (until).

Note:

The date_bucket default value is month and returns values as a calendar month:
For example, &since=2017-07-15&until=2017-08-15&date_bucket=month will return monthly buckets as July 15 -31, August 01 - 15

Suggest Edits

Overview

View a summary of all metrics as an itemized list for a specified email type.
Data can be segmented by email type and grouped by various metrics.

 
gethttps://api.yotpo.com/analytics/v1/emails/app_key?token=token&date_range.since=2017-07-01&date_range.until=2017-08-20
GET https://api.yotpo.com/analytics/v1/emails/YOUR_APP_KEY?token=YOUR_UTOKEN&since=2017-07-01&until=2017-11-01
A binary file was returned

You couldn't be authenticated

{
    "values": {
        "all_emails": {
            "values": {
                "answers_from_emails": 1,
                "arrived_early": 0,
                "click_throughs": 0,
                "emails_failed": 1,
                "emails_opened": 5,
                "emails_sent": 10,
                "invalid_address": 1,
                "marked_spam": 0,
                "reviews_from_emails": 3,
                "unsubscribed": 0
            }
        }
    }
}

Path Params

app_key
string
required

Your Yotpo account API key

Query Params

token
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your token.

email_type
string

Choose one email_type value from the table of Supported Email Types or exclude this parameter to retrieve data for all emails.

reminder_num
int32

The number of the MAP reminder email. Must be an integer greater than zero and can only be used when the email type is product_reminder or site_reminder

since
date

Retrieve email analytics until and including this date (Default: Last 30 days). Note: until is required when using this param.

until
date

Retrieve email analytics until and including this date (Default: Last 30 days). Note: since is required when using this param.

group_by
string

Returns itemized grouped data. Choose a group_by value from this table

 

Note:

The since and until parameters always refer to sent emails, regardless of which metric was requested. Metrics are retrieved from emails which were sent within the date range defined.

For example, if you're requesting data on reviews within the date range of Jan 01 (since) - Jan 05 (until), note that while the review request emails were sent within the date range, the actual reviews may have only been created after Jan 05 (until).

Suggest Edits

Raw Data

Use this request to return detailed data about every email sent from Yotpo including the email recipient, when the email was received, order information, delivery success or failure, when the email was opened, clicks, unsubscribe, etc.

 
gethttps://api.yotpo.com/analytics/v1/emails/app_key/export/raw_data?token=token
GET https://api.yotpo.com/analytics/v1/emails/YOUR_APP_KEY/export/raw_data?token=YOUR_UTOKEN&since=2017-05-01&until=2017-11-01
GET https://api.yotpo.com/analytics/v1/emails/YOUR_APP_KEY/export/raw_data?token=YOUR_UTOKEN
A binary file was returned

You couldn't be authenticated

{
    "records": [
        {
            "email_address": "max@greatstore.net",
            "order_id": null,
            "order_timestamp": null,
            "product_id": null,
            "sku": null,
            "email_type": "targeted_site_review_request",
            "reminder_num": null,
            "trr_bundle_id": "4b010d38-c3e3-4a35-84c9-7f25cef05a7d",
            "trr_bundle_subject": "{store_name} - We would love to hear your thoughts",
            "review_type": "site",
            "coupon_code": null,
            "email_sent_timestamp": "2017-09-19T15:45:30.000Z",
            "opened_timestamp": "2017-09-19T15:46:09.000Z",
            "clicked_through_timestamp": null,
            "content_creation_timestamp": "2017-09-19T15:46:57.000Z",
            "platform": "desktop",
            "invalid_address_timestamp": null,
            "failed_timestamp": null,
            "unsubscribed_timestamp": null,
            "marked_spam_timestamp": null,
            "arrived_early_timestamp": null
        },
        {
            "email_address": "moritz@20mm.eu",
            "order_id": null,
            "order_timestamp": null,
            "product_id": null,
            "sku": null,
            "email_type": "targeted_site_review_request",
            "reminder_num": null,
            "trr_bundle_id": "4b2bba4f-89b5-42a6-b68d-d8fb45e6ff98",
            "trr_bundle_subject": "{store_name} - We would love to hear your thoughts",
            "review_type": "site",
            "coupon_code": null,
            "email_sent_timestamp": "2017-09-19T16:06:17.000Z",
            "opened_timestamp": "2017-09-19T16:06:49.000Z",
            "clicked_through_timestamp": null,
            "content_creation_timestamp": "2017-09-19T16:07:18.000Z",
            "platform": "desktop",
            "invalid_address_timestamp": null,
            "failed_timestamp": null,
            "unsubscribed_timestamp": null,
            "marked_spam_timestamp": null,
            "arrived_early_timestamp": null
        },
        {
            "email_address": "janschulte@dinglebop.com",
            "order_id": null,
            "order_timestamp": null,
            "product_id": "9209743056",
            "sku": null,
            "email_type": "answer_request",
            "reminder_num": null,
            "trr_bundle_id": null,
            "trr_bundle_subject": null,
            "review_type": null,
            "coupon_code": null,
            "email_sent_timestamp": "2017-09-12T07:47:50.000Z",
            "opened_timestamp": "2017-09-12T07:49:33.000Z",
            "clicked_through_timestamp": null,
            "content_creation_timestamp": "2017-09-12T07:50:03.000Z",
            "platform": "desktop",
            "invalid_address_timestamp": null,
            "failed_timestamp": null,
            "unsubscribed_timestamp": null,
            "marked_spam_timestamp": null,
            "arrived_early_timestamp": null
        }
    ]
}

Path Params

app_key
string
required

Your Yotpo account API key

Query Params

token
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your token.

email_type
string

Choose one email_type value from the table of Supported Email Types or exclude this parameter to retrieve data for all emails.

reminder_num
int32

The number of the MAP reminder email. Must be an integer greater than zero and can only be used when the email type is product_reminder or site_reminder

since
date

Retrieve raw data since and including this date (Default: Last 30 days). Note: until is required when using this param.

until
date

Retrieve raw data until and including this date (Default: Last 30 days). Note: since is required when using this param.

sort
string

Sort by Ascending (oldest first by sent date) or Descending (newest first by sent date)

page
int32

Return page number from paginated response. Must be an integer greater than zero.

per_page
int32

The number of items to return in one paginated page. Must be an integer between 1 and 1,000

 

Note:

The since and until parameters always refer to sent emails, regardless of which metric was requested. Metrics are retrieved from emails which were sent within the date range defined.

For example, if you're requesting data on reviews within the date range of Jan 01 (since) - Jan 05 (until), note that while the review request emails were sent within the date range, the actual reviews may have only been created after Jan 05 (until).

Suggest Edits

Export Email Analytics

Export your Email Analytics data in .csv format. We'll email you a detailed spreadsheet based on the queried parameters.

 
gethttps://api.yotpo.com/analytics/v1/emails/app_key/export/csv?token=token
GET api.yotpo.com/analytics/v1/emails/YOUR_APP_KEY/export/csv?token=YOUR_UTOKEN&since=2017-07-01&until=2017-08-20&email_address=joe@email.com
GET api.yotpo.com/analytics/v1/emails/YOUR_APP_KEY/export/csv?token=YOUR_UTOKEN
A binary file was returned

You couldn't be authenticated

No response examples available

Path Params

app_key
string
required

Your Yotpo account API key

Query Params

token
string

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your token.

since
date

Retrieve export data since and including this date (Default: Last 30 days). Note: until is required when using this param.

until
date

Retrieve export data until and including this date (Default: Last 30 days). Note: since is required when using this param.

email_type
string

Choose one email_type value from the table of Supported Email Types or exclude this parameter to retrieve data for all emails.

reminder_num
int32

The number of the MAP reminder email. Must be an integer greater than zero and can only be used when the email type is product_reminder or site_reminder

email_address
string
required

In order to export you must include an email address. This is the email address that the export file will be sent to.

 
Use this endpoint to generate an itemized spreadsheet of your Email Analytics data based on the queried parameters.

Use this endpoint to generate an itemized spreadsheet of your Email Analytics data based on the queried parameters.

Note:

The since and until parameters always refer to sent emails, regardless of which metric was requested. Metrics are retrieved from emails which were sent within the date range defined.

For example, if you're requesting data on reviews within the date range of Jan 01 (since) - Jan 05 (until), note that while the review request emails were sent within the date range, the actual reviews may have only been created after Jan 05 (until).

Suggest Edits

Introduction to Mail After Purchase

 

What is Mail After Purchase?

What can you do with Mail After Purchase?

The Yotpo API lets you do the following with the MAP resource. More detailed versions of these general actions may be available:

POST /apps/{app_key}/reminders/send_test_email

Suggest Edits

Test Mail After Purchase

 
posthttps://api.yotpo.com/apps/:app_key/reminders/send_test_email?utoken=:token
POST https://api.yotpo.com/apps/YOUR_APP_KEY/reminders/send_test_email
-----------------------------------------------------------------------------------


{
    "utoken": "RHfbwCkjibq9yutpmIu2SlNunLQlhyS8u5bhBiHS",
    "email_type": "map",
    "email": "email@emailclient.com"
}
A binary file was returned

You couldn't be authenticated

{
  "status" : {
    "code" : 200,
    "message" : "OK"
  }
}

Body Params

utoken
string
required

Your Yotpo utoken generated using the Yotpo Authorization endpoint.

email_type
string
required

The email type. Value should be set as map

email
string
required

Email address to send the test email. If you do not specify a value, the account email is used.

 
Suggest Edits

Introduction to Products

Products endpoints allow you to create new products in the Yotpo system, update products, and retrieve data on existing products.

 

What can you do with Products?

The Yotpo API lets you do the following with the Products resources. More detailed versions of these general actions may be available:

Call
See

Create products in the Yotpo system

Retrieve All Products

Retrieve Promoted Products

Search for Missed Products

Retrieve detailed missing products information

Update products in the Yotpo system

Suggest Edits

Create Mass Products

 
posthttps://api.yotpo.com/apps/:app_key/products/mass_create
POST https://api.yotpo.com/apps/YOUR_APP_KEY/products/mass_create
------------------------------------------------------------------------------

{
  "utoken": "YOUR_UTOKEN",
  "products": {
    "gapi1": {
      "name": "16 GB USB",
      "url": "http://www.somestore.com/product123456.html"
    },
    "gapi2": {
      "name": "USB Mouse",
      "url": "http://www.somestore.com/product123457.html",
      "blacklisted": true
    }
  }
}
POST https://api.yotpo.com/apps/### YOUR APP_KEY HERE ###/products/mass_create
------------------------------------------------------------------------------

{
  "utoken": "### YOUR UTOKEN HERE ###",
  "products": {
    "123456": {
      "name": "16 GB USB",
      "url": "http://www.somestore.com/product123456.html",
      "image_url": "http://www.somestore.com/product123456/image.jpg",
      "description": "16 GB USB2 memory stick",
      "currency": "USD",
      "price": "20",
      "product_tags": "storage",
      "specs": {
        "upc": "USB161",
        "mpn": "DOK16USB2",
        "brand": "GKE",
        "isbn": "978-3-16-148410-0"
      }
    },
    "123457": {
      "name": "USB Mouse",
      "url": "http://www.somestore.com/product123457.html",
      "image_url": "http://www.somestore.com/product123457/image.jpg",
      "description": "Two-button USB optical Mouse",
      "currency": "USD",
      "price": "10",
      "product_tags": "mouse",
      "specs": {
        "upc": "USBMSE",
        "mpn": "USB Mouse",
        "brand": "Suntec"
      }
    }
  }
}
A binary file was returned

You couldn't be authenticated

{"code":200,
"message":"OK"}

Body Params

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your utoken.

products
object
products.product_id
object
required

The Product ID of the product.

product
object

product[description]

product.name
string
required

The name of the product

product.url
string
required

The URL of the product on your store web site

product.image_url
string

The URL of the image of the product

product.description
string

The description of the product

product.currency
string

The ISO code of the currency in which the order was made

product.price
string

The price of the product

product.product_tags
string

The tag you apply to a product in Custom Review Forms. This can only be a single string. Products can accept one tag per product and may not contain commas

specs
object
specs.upc
string

Universal Product Code (UPC)

specs.mpn
string

Manufacturer Part Number (MPN)

specs.brand
string

Brand

specs.isbn
string

International Standard Book Number (ISBN)

specs.external_sku
string

Stock-Keeping Unit (SKU)

blacklisted
boolean

Set this to true to stop sending review request emails for this product.

 

Product Specs

  • Universal Product Code upc: "upc-value",
  • Manufacturer Part Number mpn: "mpn-value",
  • Brand brand: "Yotpo",
  • International Standard Book Number isbn: "isbn-value"
  • Stock-keeping unit sku: "sku-value"
  • External stock-keeping unit external_sku: "external_sku value". This is a value you supply that represents a unique value within the domain.

Product Tagging

Products can accept one tag per product and may not contain commas (,)
Adding more than one product tag per product will result in a failed request (400 Error)
As a result, no new products will be created.

Note:

It is recommended to send 200 to 300 products per call.
Do no send more than 500 products per call.

Note

For a list of ISO currency codes, click here

Note:

  • Trailing spaces are automatically stripped in the product specification.
    • Any combination of leading zeros (“0”), leading spaces and leading dashes (“-“) are automatically stripped in the product specification.
    • The SKU only supports alphanumeric (a...z, A...Z, 0...9), "_" and "-" characters.
    • The product specification value is case-sensitive.
    • The product specification value “N/A” is invalid in any case and is ignored.

If there is an error in the data that you submit, you receive an errors object in the response with the following information:

Parameter Name
Description

field

The field where the error occurred.

error

Description of the error in the field.

Suggest Edits

Retrieve All Products

Use this endpoint to retrieves a list of all of your store's products.
By default, this endpoint will return the first 10 products in the product catalog.
Use the count and page parameters to retrieve more than 10 products in a paginated response.

 
gethttps://api.yotpo.com/v1/apps/app_key/products
GET  https://api.yotpo.com/v1/apps/YOUR_APP_KEY/products?utoken=YOUR_UTOKEN
GET  https://api.yotpo.com/v1/apps/YOUR_APP_KEY/products?utoken=YOUR_UTOKEN&page=1&count=4
A binary file was returned

You couldn't be authenticated

{
status: {
code: 200,
message: "ok"
},
pagination: {
page: 1,
count: 10,
total: 7
},
products: [
{
id: 22667584,
created_at: "2017-05-08T07:28:49.846Z",
updated_at: "2017-05-22T08:13:43.439Z",
average_score: 4.6,
total_reviews: 5,
url: "https://yotpo.com/go/cLUOmgOX",
external_product_id: "yotpo_site_reviews",
name: "http://myonlinestore.mystore.com",
description: null,
product_specs: [ ],
category: {
id: 1,
name: "Electronics"
},
images: [ ]
}

Path Params

app_key
string
required

Your Yotpo account API key

Query Params

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your utoken.

count
int32

Number of products to return

page
string

Page number to return products for

 

Note:

By default, this endpoint will return the first 10 products in the product catalog.
Use the count and page parameters to retrieve more than 10 products in a paginated response.

e.g. https://api.yotpo.com/v1/apps/YOUR_APP_KEY/products?utoken=YOUR_UTOKEN&page=1&count=100

Suggest Edits

Retrieve Promoted Products

 
gethttps://api.yotpo.com/v1/widget/app_key/products/promoted_products
GET https://api.yotpo.com/v1/widget/YOUR_APP_KEY/products/promoted_products
A binary file was returned

You couldn't be authenticated

{
 "status": {
   "code": 200,
   "message": "OK"
 },
 "response": {
   "products": [
     {
       "products_app_id": 13,
       "url": "https://yotpo.com/go/2HmcAhwP",
       "price": 12,
       "currency": “usd",
       "type": "widget_v2",
       "name": "Long Sleeves Shirt",
       "destination_app_key": "Ivvnw7H9irV43aCuUBNvcbWEwGNKXtujVJo7wI2H",
       "position": 1,
       "source_products_app_id": null,
       "matching_algorithm": null,
       "domain_key": "761060801",
       "image_title": "Best shirt",
       "average_score": 4,
       "total_review": 1,
       "image": "http://s3.amazonaws.com/yotpo-images-test/PromotedProduct/1/7/big.png?1440493754"
     },
     {
       "products_app_id": 14,
       "url": "https://yotpo.com/go/2HmcAhwQ",
       "price": 12,
       "currency": “usd",
       "type": "widget_v2",
       "name": "Short Sleeves Shirt",
       "destination_app_key": "Ivvnw7H9irV43aCuUBNvcbWEwGNKXtujVJo7wI2H",
       "position": 2,
       "source_products_app_id": null,
       "matching_algorithm": null,
       "domain_key": "761060802",
       "image_title": "Best T-shirt",
       "average_score": 5,
       "total_review": 47,
       "image": "http://s3.amazonaws.com/yotpo-images-test/PromotedProduct/1/7/short.png?1440493754"
     }
   ]
 }
}
{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response": {
        "products": [
            {
                "image_title": "",
                "average_score": 4.32812,
                "total_review": 64,
                "image": "https://ddcfq0gxiontw.cloudfront.net/Product/10227528/7644685/square.jpg?1401628531",
                "position": 1,
                "url": "https://yotpo.com/go/1234",
                "currency": "USD",
                "price": 140,
                "destination_app_key": "L5wHXYsgiB2gGZo6R4HSgfQuK0xYBgLSiv4EDUHF",
                "domain_key": "8021236041",
                "type": "MostLiked",
                "name": "Thingamabob - Onyx",
                "products_app_id": 16616013,
                "source_products_app_id": null
            },
            {
                "image_title": "",
                "average_score": 4.49333,
                "total_review": 150,
                "image": "https://ddcfq0gxiontw.cloudfront.net/Product/10227528/7644685/square.jpg?1401628531",
                "position": 2,
                "url": "https://yotpo.com/go/12345",
                "currency": "USD",
                "price": 125,
                "destination_app_key": "L5wHXYsgiB2gGZo6R4HSgfQuK0xYBgLSiv4EDUHF",
                "domain_key": "2110756101",
                "type": "MostLiked",
                "name": "Thingamajig - Black",
                "products_app_id": 7740414,
                "source_products_app_id": null
            },
            {
                "image_title": "",
                "average_score": 4.68493,
                "total_review": 73,
                "image": "https://ddcfq0gxiontw.cloudfront.net/Product/10227528/7644685/square.jpg?1401628531",
                "position": 3,
                "url": "https://yotpo.com/go/123456",
                "currency": "USD",
                "price": 120,
                "destination_app_key": "L5wHXYsgiB2gGZo6R4HSgfQuK0xYBgLSiv4EDUHF",
                "domain_key": "2647906053",
                "type": "MostLiked",
                "name": "Dinglebop - Black Leather",
                "products_app_id": 10282720,
                "source_products_app_id": null
            },
            {
                "image_title": "",
                "average_score": 4.41262,
                "total_review": 206,
                "image": "https://ddcfq0gxiontw.cloudfront.net/Product/10227528/7644685/square.jpg?1401628531",
                "position": 4,
                "url": "https://yotpo.com/go/4321",
                "currency": "USD",
                "price": 120,
                "destination_app_key": "L5wHXYsgiB2gGZo6R4HSgfQuK0xYBgLSiv4EDUHF",
                "domain_key": "2647892101",
                "type": "MostLiked",
                "name": "Doohickey - Black Tan",
                "products_app_id": 10124401,
                "source_products_app_id": null
            },
            {
                "image_title": "",
                "average_score": 4.45238,
                "total_review": 210,
                "image": "https://ddcfq0gxiontw.cloudfront.net/Product/10227528/7644685/square.jpg?1401628531",
                "position": 5,
                "url": "https://yotpo.com/go/43215",
                "currency": "USD",
                "price": 120,
                "destination_app_key": "L5wHXYsgiB2gGZo6R4HSgfQuK0xYBgLSiv4EDUHF",
                "domain_key": "2647598277",
                "type": "MostLiked",
                "name": "Trinket - Blue Brown",
                "products_app_id": 10129319,
                "source_products_app_id": null
            },
            {
                "image_title": "",
                "average_score": 4.56818,
                "total_review": 88,
                "image": "https://ddcfq0gxiontw.cloudfront.net/Product/10227528/7644685/square.jpg?1401628531",
                "position": 6,
                "url": "https://yotpo.com/go/445245",
                "currency": "USD",
                "price": 125,
                "destination_app_key": "L5wHXYsgiB2gGZo6R4HSgfQuK0xYBgLSiv4EDUHF",
                "domain_key": "2647867013",
                "type": "MostLiked",
                "name": "Thingy - Silver",
                "products_app_id": 10166622,
                "source_products_app_id": null
            },
            {
                "image_title": "",
                "average_score": 4.55303,
                "total_review": 132,
                "image": "https://ddcfq0gxiontw.cloudfront.net/Product/10227528/7644685/square.jpg?1401628531",
                "position": 7,
                "url": "https://yotpo.com/go/2334525",
                "currency": "USD",
                "price": 140,
                "destination_app_key": "L5wHXYsgiB2gGZo6R4HSgfQuK0xYBgLSiv4EDUHF",
                "domain_key": "1222516549",
                "type": "MostLiked",
                "name": "Thingamadoodle - Black Gold",
                "products_app_id": 6545964,
                "source_products_app_id": null
            },
            {
                "image_title": "",
                "average_score": 4.48649,
                "total_review": 111,
                "image": "https://ddcfq0gxiontw.cloudfront.net/Product/10227528/7644685/square.jpg?1401628531",
                "position": 8,
                "url": "https://yotpo.com/go/554234",
                "currency": "USD",
                "price": 115,
                "destination_app_key": "L5wHXYsgiB2gGZo6R4HSgfQuK0xYBgLSiv4EDUHF",
                "domain_key": "2110746053",
                "type": "MostLiked",
                "name": "Dingledoodle - Black Leather",
                "products_app_id": 7414159,
                "source_products_app_id": null
            },
            {
                "image_title": "",
                "average_score": 4.58873,
                "total_review": 355,
                "image": "https://ddcfq0gxiontw.cloudfront.net/Product/10227528/7644685/square.jpg?1401628531",
                "position": 9,
                "url": "https://yotpo.com/go/4325453",
                "currency": "USD",
                "price": 120,
                "destination_app_key": "L5wHXYsgiB2gGZo6R4HSgfQuK0xYBgLSiv4EDUHF",
                "domain_key": "2647270277",
                "type": "MostLiked",
                "name": "Didjeridoohickey - Rose Gold",
                "products_app_id": 10129095,
                "source_products_app_id": null
            }
        ]
    }
}

Path Params

app_key
string
required

Your Yotpo account API key

 

Note:

  • products_app_id is the Product ID.
  • The products_app_id only supports alphanumeric (a...z, A...Z, 0...9), "_" and "-" characters.
  • domain_key is the SKU
Suggest Edits

Retrieve Detailed Missed Products Information

 
gethttps://api.yotpo.com/missed_products/app_key/search_drill_down
GET https://api.yotpo.com/missed_products/YOUR_APP_KEY/search_drill_down.json?utoken=YOUR_UTOKEN&missed_products_ids=1,2,5,6
A binary file was returned

You couldn't be authenticated

{  
   "status":{  
      "code":200,
      "message":"OK"
   },
   "response":{  
      "pagination":{  
         "total":4,
         "start":0,
         "size":10
      },
      "missed_products":[  
         {  
            "id":1,
            "product_name":"Product2",
            "product_sku":"289724065",
            "user_email":"efef@efef.com",
            "user_display_name":"Gregory",
            "missed_product_date":"2015-06-06T07:47:33.123Z",
            "order_id":"346522189",
            "purchase_date":"2014-10-23T07:34:37.846Z",
            "mail_delivery_date":null
         },
         {  
            "id":2,
            "product_name":"Product12",
            "product_sku":"293116261",
            "user_email":"efef@efef.com",
            "user_display_name":"Tanya",
            "missed_product_date":"2015-07-02T07:48:49.846Z",
            "order_id":"346522189",
            "purchase_date":"2014-10-23T07:34:37.846Z",
            "mail_delivery_date":"2015-07-06T07:14:33.846Z"
         },
         {  
            "id":5,
            "product_name":"Product8",
            "product_sku":"293068145",
            "user_email":"zxc@asc.com",
            "user_display_name":"Steven",
            "missed_product_date":"2015-07-04T07:49:24.846Z",
            "order_id":"346522145",
            "purchase_date":"2014-10-23T07:33:38.846Z",
            "mail_delivery_date":"2015-07-06T07:14:37.846Z"
         },
         {  
            "id":6,
            "product_name":"Product2",
            "product_sku":"289724065",
            "user_email":"cas@acccs.com",
            "user_display_name":"Donna",
            "missed_product_date":"2015-06-12T07:49:33.846Z",
            "order_id":"346521461",
            "purchase_date":"2014-10-23T07:19:21.846Z",
            "mail_delivery_date":null
         }
      ]
   }
}

Path Params

app_key
string
required

Your Yotpo account API key

Query Params

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your utoken.

start
int32

Result offset

size
int32

Result size

missed_products_ids
string
required

Requested missed Product IDs, separated by a comma

 

Note:

The missed_product_ids parameter only supports alphanumeric (a...z, A...Z, 0...9), "_" and "-" characters.

Suggest Edits

Update Mass Products

 
puthttps://api.yotpo.com/apps/:app_key/products/mass_update
PUT https://api.yotpo.com/apps/YOUR_APP_KEY/products/mass_update
-----------------------------------------------------------------------------


{
  "utoken": "YOUR_UTOKEN",
  "products": {
    "123456": {
      "url": "http://www.somestore.com/product123456.html",
      "name": "16 GB USB",
      "description": "16 GB USB2 memory stick",
      "image_url": "http://www.somestore.com/product123456/image.jpg",
      "currency": "USD",
      "price": "20",
      "product_tags": "storage",
      "specs": {
        "upc": "USB161",
        "mpn": "DOK16USB2",
        "brand": "GKE",
        "external_sku": "GR3G0RY"
      },
      "blacklisted": false
    },
    "123457": {
      "url": "http://www.somestore.com/product123457.html",
      "name": "USB Mouse",
      "description": "Two-button USB optical Mouse",
      "image_url": "http://www.somestore.com/product123457/image.jpg",
      "currency": "USD",
      "price": "10",
      "product_tags": "mouse",
      "specs": {
        "upc": "USBMSE",
        "mpn": "USB Mouse",
        "brand": "Suntec",
        "external_sku": "K0HLL"
      },
      "blacklisted": true
    }
  }
}
A binary file was returned

You couldn't be authenticated

{"code":200,
"message":"OK"}

Body Params

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your utoken.

product
object

product[description]

product.product_id
string
required

The Product ID of the product.

product.name
string
required

The name of the product

product.url
string
required

The URL of the product on your store web site

product.image_url
string

The URL of the image of the product

product.description
string

The description of the product

product.currency
string

The ISO code of the currency in which the order was made

product.price
string

The price of the product

product.product_tags
string

The tag you apply to a product in Custom Review Forms. This can only be a single string. Products can accept one tag per product and may not contain commas

specs
object
specs.upc
string

Universal Product Code UPC

specs.mpn
string

Manufacturer Part Number MPN

specs.brand
string

Brand

specs.isbn
string

International Standard Book Number ISBN

specs.external_sku
string

Stock-Keeping Unit SKU

blacklisted
boolean

Set this to true to stop sending review request emails for this product.

 

Caution

Only valid parameters will overwrite existing data.

Excluding the description parameter or passing the description parameter without a value will override and erase any existing description.

Product Tagging

Products can accept one tag per product and may not contain commas (,)
Adding more than one product tag per product will result in a failed request (400 Error)
As a result, no new products will be created.

Note:

It is recommended to send 200 to 300 products per call. Do no send more than 500 products per call.

Product Specs

  • Universal Product Code upc: "upc-value",
  • Manufacturer Part Number mpn: "mpn-value",
  • Brand brand: "Yotpo",
  • International Standard Book Number isbn: "isbn-value"
  • Stock-keeping unit sku: "sku-value"
  • External stock-keeping unit external_sku: "external_sku value". This is a value you supply that represents a unique value within the domain.

Note

For a list of ISO currency codes, go to http://www.currency-iso.org/en/home/tables/table-a1.html

Note:

  • Trailing spaces are automatically stripped in the product specification.
  • Any combination of leading zeros (“0”), leading spaces and leading dashes (“-“) are automatically stripped in the product specification.
  • The product specification only supports alphanumeric (a...z, A...Z, 0...9), "_" and "-" characters.
  • The product specification value is case-sensitive.
  • The product specification value “N/A” is invalid in any case and is ignored.

If there is an error in the data that you submit, you receive an errors object in the response with the following information:

Parameter Name
Description

field

The field where the error occurred.

error

Description of the error in the field.

Suggest Edits

Introduction to Purchases

 

What are Purchases?

The Purchases resource is used to create, modify and retrieve orders in the Yotpo system. Orders in Yotpo system represents purchases made in the store. Yotpo uses these orders to help generate more reviews from past shoppers.

Note:

An order may contain several purchases. A purchase is a transaction for a specific product.

What can you do with Purchases?

The Yotpo API lets you do the following with the Purchase resources. More detailed versions of these general actions may be available:

Call
See

Create an order within the Yotpo sytem

Create mass orders within the Yotpo system

Retrieve Orders from the Yotpo System

Stop sending mails after purchase for a specific order and specific product. If you don't specify which product in the order then all products in that order.

Note:

  • If you use a Product ID that doesn't exist, the product is added to the database.
  • If you use the Product ID for more than one product, the Product ID is assigned to the last product you entered.

Tip:

The validate_data parameter provides additional input validation for the following Purchases endpoints:

By default, validate_data is set as true to help catch errors and prevent issues with your orders. To disable data validation, simple set validate_data as false (not recommended).

Suggest Edits

Create an Order within the Yotpo System

 
posthttps://api.yotpo.com/apps/:app_key/purchases/
POST https://api.yotpo.com/apps/YOUR_APP_KEY/purchases

{
  "validate_data": true,
  "platform": "general",
  "utoken": "YOUR_UTOKEN",
  "email": "client@abc.com",
  "customer_name": "bob",
  "order_id": "order_1",
  "order_date": "2010-10-14",
  "currency_iso": "USD",
  "products": {
    "SKUaaa12": {
      "url": "http://example_product_url1.com",
      "name": "product1",
      "image": "http://images2.fanpop.com/image/photos/13300000/A1.jpg",
      "description": "this is the description of a product",
      "price": "100",
      "specs": {
         "upc": "USB",
         "isbn": "thingy"
      },
      "product_tags": "book"
  }
 }
}
A binary file was returned

You couldn't be authenticated

{"code": 200,
    "message": "OK",
}

Body Params

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your utoken.

platform
string
required

Your eCommerce platform

email
string
required

The email address of the customer who made the order

customer_name
string
required

The name of the customer who made the order

order_id
string
required

The ID of the order

currency_iso
string

The ISO code of the currency in which the order was made

user_reference
string

Only used as an external reference for the Points and Rewards feature

products
object
products.product_id
object

The product ID of the product. REQUIRED

products.product_id.product_id
string
required

The product ID of the product. REQUIRED

products.product_id.name
string
required

The name of the product

products.product_id.url
string
required

The URL of the product on your store website

products.product_id.image
string
required

The URL of the image of the product

products.product_id.description
string
required

The description of the product

products.product_id.price
string
required

The price of the product

products.product_id.product_tags
string
required

The tag you apply to a product in Custom Review Forms. This can only be a single string. Products can accept one tag per product and may not contain commas

products.specs
object
required

The product specifications containing the spec values.

validate_data
boolean
required

A Boolean flag to indicate input validation in the response. true by default. See the Product Tagging note below for more info.

order_date
date
required

The date of the order in the format YYYY-MM-DD. If this is not provided, the time of the request will be used as the order date. order_date is mandatory when validate_data is set as true (default). It is not possible to send a MAP emails for orders older than six months.

 

Product Tagging

Products can accept one tag per product and may not contain commas (,)
If the validate_data parameter value is true(true by default) and the order contains an invalid tag for any of the products, the request will fail and no new order will be created.
If the validate_data parameter value is false (disabled) the order will be created regardless of any invalid product tags.

e-Commerce Platforms

Your Platform
Enter this for Platform Parameter in API call

3dcart

three_d_cart

AmeriCommerce

americommerce

Bigcommerce

bigcommerce

Commerce Guys

commerce_guys

CS-Cart

cscart

ebay

ebay

EC-CUBE

eccube

Lightspeed

seoshop

Magento

magento

OpenCart

opencart

PrestaShop

prestashop

Shopify

shopify

Shoplo

shoplo

Storenvy

storenvy

Volusion

volusion

WooCommerce

woocommerce

WP eCommerce

wp_ecommerce

Zepo

zepo

Any other platform

general

Error Messages

Parameter Name
Description

order_id

The ID of the purchase

field

The field where the error occurred

error

Description of the error in the field

Product Specs

  • Universal Product Code upc: "upc-value",
  • Manufacturer Part Number mpn: "mpn-value",
  • Brand brand: "Yotpo",
  • International Standard Book Number isbn: "isbn-value"
  • Stock-keeping unit sku: "sku-value"
  • External stock-keeping unit external_sku: "external_sku value"

Important:

It is not possible to send a MAP emails for orders older than six months.

Note:

  • The data-product-spec tag must be in lower case.
  • Trailing spaces are automatically stripped in the product specification.
  • Any combination of leading zeros (“0”), leading spaces and leading dashes (“-“) are automatically stripped in the product specification.
  • The product specification value is case-sensitive.
  • The product specification value “N/A” is invalid in any case and is ignored.
  • The product specification only supports alphanumeric (a...z, A...Z, 0...9), "_" and "-" characters.

Note:

For a list of ISO currency codes, go to http://www.currency-iso.org/en/home/tables/table-a1.html

Note:

The product_tag parameter can only be a single string.

Note:

The product_sku cannot include the "/" symbol.

Suggest Edits

Create Mass Orders within the Yotpo System

 
posthttps://api.yotpo.com/apps/:app_key/purchases/mass_create.json
POST https://api.yotpo.com/apps/YOUR_APP_KEY/purchases/mass_create.json
------------------------------------------------------------------------------------

{
  "validate_data": true,
  "platform": "general",
  "utoken": "YOUR_UTOKEN",
  "orders": [
    {
      "email": "bill@abc.com",
      "customer_name": "bill",
      "order_id": "aaa",
      "order_date": "2015-12-28",
      "currency_iso": "USD",
      "products": {
        "13241": {
          "url": "http://www.gkshops.com/USBthingy.html",
          "name": "USBthingy",
          "image": "http://images2.fanpop.com/image/photos/13300000/A1.jpg",
          "description": "This is the description of a product",
          "price": "39",
          "specs": {
            "upc": "USB",
            "isbn": "thingy"
          }
        },
        "bbb12": {
          "url": " http://www.gkshops.com/BigUSBthingy.html ",
          "name": " BigUSBthingy ",
          "image": "http://images2.fanpop.com/image/photos/13300000/A2.jpg",
          "description": "This is just what you always wanted. ",
          "price": "29",
          "specs": {
            "upc": "USB",
            "isbn": "Big"
          }
        }
      }
    },
    {
      "email": "bob@abc.com",
      "customer_name": "bob",
      "order_id": "bbb",
      "order_date": "2015-12-29",
      "currency_iso": "USD",
      "products": {
        "aaa22": {
          "url": "http://example_product_url1.com",
          "name": "product1",
          "image": "http://images2.fanpop.com/image/photos/13300000/A2.jpg",
          "description": "this is the description of a product",
          "price": "69",
          "specs": {
            "upc": "Mega-product"
          }
        }
      }
    }
  ]
}
A binary file was returned

You couldn't be authenticated

{
  "code": 200,
  "message": "OK",
  "uuid": "22e03d7c-aba557-467d-55-a60a7c28ad73"
}

Body Params

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your utoken.

platform
string
required

Your e-commerce platform

orders
object
orders.email
string
required

The email address of the customer who made the order

orders.customer_name
string
required

The name of the customer who made the order

orders.order_id
string
required

The ID of the order

orders.currency_iso
string

The ISO code of the currency in which the order was made

orders.user_reference
string

An external identifier used to link between the Yotpo user identity and an external user identity.

products
object
products.orders
object
products.orders.product_id
object

The unique product ID of the product. REQUIRED

products.orders.product_id.name
string
required

The name of the product

products.orders.product_id.url
string
required

The URL of the product on your store website

products.orders.product_id.image
string

The URL of the image of the product

products.orders.product_id.description
string

The description of the product

products.orders.product_id.price
double

Including the product price helps us rank and prioritize products by their price. For example, you can use this parameter to request reviews based on product price.

products.orders.product_id.product_tags
string

The tag you apply to a product in Custom Review Forms. One tag per product. Products can accept one tag per product and may not contain commas

products.orders.specs
object

The product specifications containing the spec values

validate_data
boolean
required

A Boolean flag to indicate input validation in the response. true by default. See the Product Tagging note below for more info.

order_date
date
required

The date of the order in the format YYYY-MM-DD. If this is not provided, the time of the request will be used as the order date. order_date is mandatory when validate_data is set as true (default). It is not possible to send a MAP emails for orders older than six months.

 

Product Tagging

Products can accept one tag per product and may not contain commas (,)
If the validate_data parameter value is true(true by default) and the order contains an invalid tag for any of the products, the request will fail and no new order will be created.
If the validate_data parameter value is false (disabled) the order will be created regardless of any invalid product tags.

Note:

Remember to take advantage of your Kickstart Credits. We recommend sending us past orders from the last two to 4 months (make sure you don't exceed your Kickstart Credit limit).
See the Kickstart Credits guide for more information.

Important:

It is not possible to send a MAP emails for orders older than six months.

Note:

Yotpo recommends passing batches of 200 orders per request

e-Commerce Platforms

Your Platform
Enter this for Platform Parameter in API call

3dcart

three_d_cart

AmeriCommerce

americommerce

Bigcommerce

bigcommerce

Commerce Guys

commerce_guys

CS-Cart

cscart

ebay

ebay

EC-CUBE

eccube

Lightspeed

seoshop

Magento

magento

OpenCart

opencart

PrestaShop

prestashop

Shopify

shopify

Shoplo

shoplo

Storenvy

storenvy

Volusion

volusion

WooCommerce

woocommerce

WP eCommerce

wp_ecommerce

Zepo

zepo

Any other platform

general

Product Specs

  • Universal Product Code upc: "upc-value",
  • Manufacturer Part Number mpn: "mpn-value",
  • Brand brand: "Yotpo",
  • International Standard Book Number isbn: "isbn-value"
  • Stock-keeping unit sku: "sku-value"
  • External stock-keeping unit external_sku: "external_sku value"

Note:

  • Trailing spaces are automatically stripped in the product specification.
  • Any combination of leading zeros (“0”), leading spaces and leading dashes (“-“) are automatically stripped in the product specification.
  • The product specification only supports alphanumeric (a...z, A...Z, 0...9), "_" and "-" characters.
  • The product specification value is case-sensitive.
  • The product specification value “N/A” is invalid in any case and is ignored.

Note:

For a list of ISO currency codes, go to http://www.currency-iso.org/en/home/tables/table-a1.html

Note:

The product ID only supports alphanumeric (a...z, A...Z, 0...9), "_" and "-" characters without spaces.

Sending an invalid character in the product ID will cause the transaction to be ignored with
no indication of failure.

Error Messages

If there is an error in the data that you submit, you receive an errors object in the response with the following information:

Parameter Name
Description

order_num

The position of the purchase (order) in the list that you submitted.

order_id

The ID of the purchase

field

The field where the error occurred. In the example below, the field is the user email.

error

Description of the error in the field.

Note:

The product_tag parameter can only be a single string.

Suggest Edits

Retrieve Orders from the Yotpo System

 
gethttps://api.yotpo.com/apps/app_key/purchases?utoken=:token
curl --request GET \
  --url 'https://api.yotpo.com/apps/app_key/purchases?utoken=%3Atoken'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.yotpo.com/apps/app_key/purchases',
  qs: { utoken: ':token' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.yotpo.com/apps/app_key/purchases?utoken=%3Atoken")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.yotpo.com/apps/app_key/purchases?utoken=%3Atoken");

xhr.send(data);
import requests

url = "https://api.yotpo.com/apps/app_key/purchases"

querystring = {"utoken":":token"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response": {
        "purchases": [
            {
                "id": 6225346,
                "user_email": "bruce@hotmail.com",
                "user_name": "Bruce Lee",
                "order_id": "10000",
                "product_sku": "242761577",
                "product_name": "Classic Black Leather",
                "product_url": "http://www.watchfactory.com/products/black-black-leather",
                "order_date": "2014-08-17T00:00:00.000Z",
                "product_description": "Black/Black Leather",
                "created_at": "2014-10-26T23:10:55.000Z"
            },
            {
                "id": 19578487,
                "user_email": "ron@hotmail.com",
                "user_name": "Ronald McDonald",
                "order_id": "100000",
                "product_sku": "242613653",
                "product_name": "Classic Black Tan",
                "product_url": "http://www.watchfactory.com/products/black-tan-leather",
                "order_date": "2015-02-16T13:04:36.000Z",
                "product_description": "Black/Tan Leather",
                "created_at": "2015-02-17T03:38:23.000Z"
            },
            {
                "id": 301697191,
                "user_email": "fred@gmail.com",
                "user_name": "Fred Flintstone",
                "order_id": "1000000",
                "product_sku": "2647270277",
                "product_name": "The 40 - Rose Gold Natural Tan",
                "product_url": "http://www.watchfactory.com/products/rose-gold-natural-tan-leather",
                "order_date": "2017-08-08T05:58:49.000Z",
                "product_description": "40 - Rose Gold/Natural Leather",
                "created_at": "2017-08-09T21:12:56.000Z"
            },
            {
                "id": 300834896,
                "user_email": "rick@hotmail.com",
                "user_name": "Rick Sanchez",
                "order_id": "1000001",
                "product_sku": "559165508",
                "product_name": "Chrono Gunmetal Sandstone",
                "product_url": "http://www.watchfactory.com/products/chrono-gun-metal-sandstone-leather",
                "order_date": "2017-08-07T15:05:46.000Z",
                "product_description": "Chrono Gun Metal/Leather",
                "created_at": "2017-08-08T01:05:05.000Z"
            },
            {
                "id": 301697207,
                "user_email": "bird@hotmail.com",
                "user_name": "Bird Person",
                "order_id": "1000002",
                "product_sku": "2110786565",
                "product_name": "Gold/Brown Leather",
                "product_url": "http://www.watchfactory.com/products/gold-brown-leather",
                "order_date": "2017-08-08T06:02:39.000Z",
                "product_description": "Gold/Brown Leather",
                "created_at": "2017-08-09T21:12:57.000Z"
            },
            {
                "id": 300834905,
                "user_email": "meeseeks@hotmail.com",
                "user_name": "Mister Meeseeks",
                "order_id": "1000005",
                "product_sku": "2647960005",
                "product_name": "The 40 - Rose Gold Brown",
                "product_url": "http://www.watchfactory.com/products/rose-gold-brown-leather",
                "order_date": "2017-08-07T15:05:33.000Z",
                "product_description": "The 40 - Rose Gold/Brown Leather",
                "created_at": "2017-08-08T01:05:05.000Z"
            },
            {
                "id": 301697234,
                "user_email": "peter@gmail.com",
                "user_name": "Peter Griffin",
                "order_id": "1000006",
                "product_sku": "379455772",
                "product_name": "Classic White Gold",
                "product_url": "http://www.watchfactory.com/products/white-gold-leather",
                "order_date": "2017-08-08T05:58:49.000Z",
                "product_description": "White Gold/Leather",
                "created_at": "2017-08-09T21:12:58.000Z"
            },
            {
                "id": 300834915,
                "user_email": "marge@outlook.com",
                "user_name": "Marge Simpson",
                "order_id": "1000007",
                "product_sku": "379456616",
                "product_name": "Classic Rose Gold Black",
                "product_url": "http://www.watchfactory.com/products/rose-gold-black-leather",
                "order_date": "2017-08-07T15:05:35.000Z",
                "product_description": "Rose Gold Black/Leather",
                "created_at": "2017-08-08T01:05:06.000Z"
            },
            {
                "id": 301697246,
                "user_email": "lisa@gmail.com",
                "user_name": "Lisa Simpson",
                "order_id": "1000008",
                "product_sku": "559220996",
                "product_name": "Chrono White Caramel",
                "product_url": "http://www.watchfactory.com/products/chrono-white-caramel-leather",
                "order_date": "2017-08-08T05:58:49.000Z",
                "product_description": "Chrono White/Leather",
                "created_at": "2017-08-09T21:12:59.000Z"
            },
            {
                "id": 301697256,
                "user_email": "pinky.brain@mousemail.com",
                "user_name": "Pinky Mouse",
                "order_id": "1000009",
                "product_sku": "2478011397",
                "product_name": "Classic - 24mm Black Leather",
                "product_url": "http://www.watchfactory.com/products/24mm-black-leather",
                "order_date": "2017-08-08T05:58:48.000Z",
                "product_description": "This 24mm wide interchangeable strap fits ONLY Classic Series Watches",
                "created_at": "2017-08-09T21:12:59.000Z"
            }
        ],
        "total_purchases": 1278421,
        "total_orders": 10
    }
}

Path Params

app_key
string
required

Your Yotpo account API key

Query Params

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your token.

since_id
string

The ID from which to start getting the elements

since_date
date

Retrieve all orders created starting from this date. The date format is YYYY-MM-DD.

page
int32

The page number of the paginated response.

count
int32

Number of orders to return. By default, ten orders are displayed.

 

Invalidated Orders

Orders which were invalidated will not be returned by this call.

Note:

This call will return a total of ten orders by default. To retrieve more than ten orders, query the count parameter to return the desired quantity of orders. Yotpo recommends querying 200 orders per request.

Note:

In the response, total_purchases represents the total number of existing orders while total_orders represents the total number of orders returned per call as defined using the count parameter. By default, total_orders will return 10 orders if the count parameter is excluded.

e.g.
"total_purchases": 1278421,
"total_orders": 10

Suggest Edits

Delete a Purchase

 
deletehttps://api.yotpo.com/apps/:app_key/purchases
DELETE https://api.yotpo.com/apps/YOUR_APP_KEY/purchases

{
  "utoken": "YOUR_UTOKEN",
  "orders": [
    {
      "order_id": "123",
      "skus": [
        "101",
        "102",
        "103",
        "104"
      ]
    },
    {
      "order_id": "124"
    }
  ]
}
A binary file was returned

You couldn't be authenticated

200
{
  "code": "200",
  "message": "OK"
}

Body Params

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your token.

orders
object
orders.order_id
string
required

The order ID

orders.sku
string

An array of SKUs to delete from the order

 

Note:

This call does not delete the purchase, it stops Yotpo sending out mails after order for the specific order and product. If you don't specify which product in the order then MAPS are not sent for all products in that order.

Suggest Edits

Introduction to Q&A

 

What is Q&A?

Yotpo Social Q&A enables visitors and prospective buyers to get real-time answers from store owners and past buyers. Questions will be directed to the store owner and to customers who had previously purchased the product.

Q&A are shown as part of the on- site widget, on a separate tab from the reviews.

What can you do with Q&A?

Q&A API endpoints allow you to retrieve Q&A data and create questions and answers.
See the breakdown below for a detailed description of each endpoint and its functions.

Call
Description
Documentation

GET /products/app_key/sku/questions

Retrieve Questions and Answers for a given product using the product SKU number.

GET/products/{app_key}/{sku}/qna_bottomline:

Retrieve the Bottom Line for a given product using the product SKU number. The Bottom Line will return the total questions and total answers for the desired product.

GET /apps/:app-key/questions.json

Retrieve all Questions for the designated account per Yotpo account API key.

POST/questions/:question_id/answers

Create a public or private Answer to a specific Question per question_id

POST /questions

Create and send a Question without sending your customer a confirmation email.

POST/questions/send_confirmation_mail

Create and send a Question which requires email confirmation.

POST /answers/answer_id/vote/vote_type

Vote up or down on a particular Answer to a Question by answer_id

Note:

Use the Retrieve Questions and Answers for a Product endpoint to retrieve an answer_id parameter.

Use the Retrieve all Questions endpoint to retrieve a question_id parameter.

Suggest Edits

Create a Question (Without sending a confirmation email)

Create and send a Question without sending your customer a confirmation email.

 
posthttps://api.yotpo.com/questions
https://api.yotpo.com/questions 
---------------------------------------------

{
   "review_content": "Do you have this in white?",
   "display_name": "John",
   "email": "john@yotpo.com",
   "appkey": "##### YOUR APP KEY HERE #####",
   "utoken": "#### YOUR UTOKEN HERE #####",
   "sku": "761060802",
   "product_title": "T-Shirt",
   "product_description": "The most comfortable shirt you will ever own.",
   "product_url": "http://john-doe.mystore.com/products/long-sleeve-t-shirt",
   "product_image_url": "//cdn.mystore.com/s/files/1/0864/8972/products/t-shirt-template-ljrmrs7o_large.png%3Fv=1423289315",
   "prevent_duplicate_review": "true",
   "product_tags": "t-shirts"
} 
A binary file was returned

You couldn't be authenticated

{
  "status": {
    "code": 200,
    "message": "ok"
  },
  "question": {
    "": {
      "account_id": 6,
      "allow_send": true,
      "archived": false,
      "content": "Do you have this in white?",
      "created_at": "2017-03-14T13:17:43Z",
      "id": 15,
      "products_app_id": 240,
      "updated_at": "2017-03-14T13:17:43Z",
      "user_id": 234,
      "user_type": "User"
    }
  }
}
}

Path Params

questions
string
required

Query Params

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your token.

Body Params

review_content
string
required

The content of the question itself

display_name
string
required

The customer's name

email
string
required

The customer's email

appkey
string
required

Your Yotpo account API key

sku
string
required

The unique ID of the product on your site (doesn't have to be the SKU)

product_title
string
required

The name of the product

product_url
string
required

The URL of the product

product_description
string

The description of the product

product_image_url
string

The URL of the image of the product

prevent_duplicate_review
boolean

Prevents sending of two identical questions. It is recommended to set this to true

product_tags
string

The tag you apply to a product in Custom Review Forms. This can only be a single string. Products can accept one tag per product and may not contain commas

 

Product Tagging

Products can accept one tag per product and may not contain commas (,)
Adding more than one product tag per product will result in a failed request (400 Error)
As a result, no new question will be created.

Suggest Edits

Create a Question (With confirmation email)

Create and send a Question which requires email confirmation.

 
posthttps://api.yotpo.com/questions/send_confirmation_mail
POST https://api.yotpo.com/questions/send_confirmation_mail?utoken=### YOUR UTOKEN HERE ###
-----------------------------------------------------------


{
   "review_content": "Do you have this in white?",
   "display_name": "John",
   "email": "questionemail@yotpo.com", 
   "appkey": "### YOUR APP_KEY HERE ###",
   "review_source": "widget_v2",
   "sku": "7610601",
   "product_title": "Long Sleeves Shirt",
   "product_description": "The best shirt ever (long sleeves version). It's a little pricey but totally worths it.",
   "product_url": "http://john-4.mystore.com/products/long-sleeve-t-shirt",
   "product_image_url": "//cdn.mystore.com/s/files/1/0864/8972/products/long-sleeve-t-shirt-template-ljrmrs7o_large.png%3Fv=1431523289",
   "prevent_duplicate_review": "true",
   "product_tags": "t-shirts"
}
A binary file was returned

You couldn't be authenticated

{
 "status": {
   "code": 200,
   "message": "OK"
 }
}

Body Params

review_content
string
required

The question the customer asks

display_name
string
required

The customer's name

email
string
required

The customer's email

appkey
string
required

Your Yotpo account API key

sku
string
required

The SKU param can be any unique stock-keeping unit. e.g. Product ID

product_title
string
required

The name of the product

product_url
string
required

The URL of the product

product_description
string

The description of the product

product_image_url
string

The URL of the image of the product

prevent_duplicate_review
boolean

Prevents sending of two identical questions. It is recommended to set this to true

product_tags
string

The tag you apply to a product in Custom Review Forms. This can only be a single string. Products can accept one tag per product and may not contain commas

 

Product Tagging

Products can accept one tag per product and may not contain commas (,)
Adding more than one product tag per product will result in a failed request (400 Error)
As a result, no new question will be created.

Note:

The sku parameter only supports alphanumeric (a...z, A...Z, 0...9), "_" and "-" characters.

Suggest Edits

Create an Answer to a Question

Create a public or private Answer to a specific Question per "question_id".

 
posthttps://api.yotpo.com/questions/question_id/answers
https://api.yotpo.com/questions/question_id/answers 
---------------------------------------------------------

{
   "utoken": "### YOUR UTOKEN ###",
    "answer": {
        "content": "This is a public answer to a question",
        "public": true
    }
}
https://api.yotpo.com/questions/question_id/answers 
---------------------------------------------------------

{
   "utoken": "### YOUR UTOKEN ###",
    "answer": {
        "content": "This is my private answer to your question",
        "public": false
    }
}
A binary file was returned

You couldn't be authenticated

 "response": {
    "comment": {
      "id": 19,
      "commentable_id": 14,
      "commentable_type": "Question",
      "content": "This is a public answer to a question",
      "votes_up": 0,
      "votes_down": 0,
      "public": true,
      "approved": true,
      "created_at": "2017-03-14T13:46:08Z",
      "store_owner_comment": true,
      "answerer": {
        "id": 10,
        "display_name": "John Doe",
        "slug": "john-doe",
        "social_image": null,
        "is_social_connected": false,
        "bio": null,
        "score": 0,
        "badges": []
      }
    }

Path Params

question_id
string
required

Retrieve this parameter from Retrieve All Questions

Body Params

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your token.

answer
string
required

The contents of your answer to a question

public
boolean

Public answer=true. Private answer=false

 

Note:

Retrieve the question_id parameter from Retrieve All Questions

Suggest Edits

Retrieve All Questions

Retrieve all Questions for the designated account per Yotpo account API key.
To return only new questions, query the status_type as status_type=new
new_questions refers to questions that are unanswered and have not been archived.

 
gethttps://api.yotpo.com/apps/app_key/questions.json
curl --request GET \
  --url 'https://api.yotpo.com/apps/app_key/questions.json?utoken=utoken'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.yotpo.com/apps/app_key/questions.json',
  qs: { utoken: 'utoken' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.yotpo.com/apps/app_key/questions.json?utoken=utoken")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.yotpo.com/apps/app_key/questions.json?utoken=utoken");

xhr.send(data);
import requests

url = "https://api.yotpo.com/apps/app_key/questions.json"

querystring = {"utoken":"utoken"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

"response":{  
      "total_questions":56,
      "new_questions":3,
      "questions":[  
         {  
            "id":700267,
            "content":"The content of the question",
            "asker":{  
               "id":11852573,
               "display_name":"Jane",
               "slug":"jane--2532987542962251174",
               "social_image":"https://server.net/images/anonymous_user.png",
               "is_social_connected":false,
               "bio":null,
               "score":0,
               "badges":[  
 
               ]
            },
            "user_type":"User",
            "created_at":"2017-06-20T22:07:14.346Z",
            "archived":false,
            "published":false,
            "allow_send":true,
            "answers":[  
 
            ],
            "products_app":{  
               "product":{  
                  "name":"Bracelet",
                  "images":[  
                     {  
                        "image_url":"http://ddcfq0gxiontw.server.net/Product/204014/15108217/thumb.jpg?1497996437"
                     }
                  ]
               },
               "product_url":"https://www.myonlinestore.com/uk/silver-bracelet-38001sbeb"
            }
         },
         
            "published":false,
            "allow_send":true,
            "answers":[  
 
            ],
            "products_app":{  
               "product":{  
                  "name":"Silver Bracelet",
                  "images":[  
                     {  
                        "image_url":"http://ddcfq0xgiontw.cloudfront.net/Product/20800596/15498768/thumb.jpg?1498005502"
            }
         }
      ]
   }
{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response": {
        "total_questions": 962,
        "new_questions": 227,
        "questions": [
            {
                "id": 200675,
                "content": "Is it water resistant?",
                "asker": {
                    "id": 5110289,
                    "display_name": "Ally",
                    "slug": "ally--108",
                    "social_image": "https://ddcfq0ogxintw.cloudfront.net/images/anonymous_user.png",
                    "is_social_connected": false,
                    "bio": null,
                    "score": 0,
                    "badges": []
                },
                "user_type": "User",
                "created_at": "2015-12-30T19:53:14.000Z",
                "archived": false,
                "published": true,
                "allow_send": false,
                "answers": [
                    {
                        "id": 496685,
                        "approved": true,
                        "public": true,
                        "content": "Yes, the watch is water resistant",
                        "is_store_owner_comment?": true,
                        "answerer": {
                            "id": 4244706,
                            "display_name": "Watch Store",
                            "slug": "john-smith--2",
                            "social_image": "https://ddcfq0gnxiotw.cloudfront.net/App/125660/7916569/thumb.png?1448148361",
                            "is_social_connected": false,
                            "bio": null,
                            "score": 14,
                            "badges": [
                                {
                                    "id": 1,
                                    "name": "Newbie",
                                    "description": "Hooray, you wrote your first review with Yotpo! Now you have this cool profile page, and you can earn Yotpo score and have even more badges.",
                                    "image_100": "http://s3.amazonaws.com/yotpo-static-images/badges/100/1.png",
                                    "image_300": "http://s3.amazonaws.com/yotpo-static-images/badges/300/1.png"
                                }
                            ]
                        },
                        "votes_up": 1,
                        "votes_down": 0,
                        "created_at": "2016-02-23T21:45:13.000Z"
                    },
                    {
                        "id": 432380,
                        "approved": true,
                        "public": true,
                        "content": "I went surfing with the watch and it worked great",
                        "is_store_owner_comment?": false,
                        "answerer": {
                            "id": 4991029,
                            "display_name": "Chad A.",
                            "slug": "rohan-a--11",
                            "social_image": "https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png",
                            "is_social_connected": false,
                            "bio": null,
                            "score": 0,
                            "badges": []
                        },
                        "votes_up": 1,
                        "votes_down": 0,
                        "created_at": "2015-12-31T22:51:30.000Z"
                    },
                    {
                        "id": 431180,
                        "approved": false,
                        "public": false,
                        "content": "I&#x27;m not really sure because I went swimming with it and it broke shortly after",
                        "is_store_owner_comment?": false,
                        "answerer": {
                            "id": 5103473,
                            "display_name": "Carlos A.",
                            "slug": "Carlos-a--208",
                            "social_image": "https://ddcfxiq0gontw.cloudfront.net/images/anonymous_user.png",
                            "is_social_connected": false,
                            "bio": null,
                            "score": 0,
                            "badges": []
                        },
                        "votes_up": 0,
                        "votes_down": 0,
                        "created_at": "2015-12-30T20:19:52.000Z",
                        "dirty_words": {
                            "id": 242522,
                            "model_id": 431180,
                            "model_type": "Comment",
                            "words": [
                                "strip"
                            ],
                            "created_at": "2015-12-30T20:19:52.000Z"
                        }
                    }
                ],
                "products_app": {
                    "product": {
                        "name": "Sports Watch - Great for an active lifestyle",
                        "images": [
                            {
                                "image_url": "https://ddcfq0gxiontw.cloudfront.net/Product/7609633/7286425/thumb.jpg?1512456475"
                            },
                            {
                                "image_url": "https://ddcfq0gxiontw.cloudfront.net/Product/7603693/7917652/thumb.jpg?1456002339"
                            },
                            {
                                "image_url": "https://ddcfq0gxiontw.cloudfront.net/Product/7606933/7999326/thumb.jpg?1456002339"
                            }
                        ]
                    },
                    "product_url": "http://www.watchstore.com/products/Sports Watch - Great for an active lifestyle"
                }
            }
        ],
        "page": "1",
        "per_page": "1"
    }
}

Path Params

app_key
string
required

Your Yotpo account API key

Query Params

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your token.

status_type
string

Filter for new questions by adding status_type=new

Body Params

total_questions
string

The total number of questions

new_questions
string

Refers to questions that are unanswered and have not been archived.

id
string

Your question ID. Use this param in Create an Answer to a Question

content
string

The content of the question.

 

Retrieving New Questions

To return only new questions, query the status_type as status_type=new

  • new_questions refers to questions that are unanswered and have not been archived.
GET: https://api.yotpo.com/apps/app_key/questions.json?utoken=your_utoken&status_type=new&count=1&page=1
Suggest Edits

Retrieve Questions and Answers for a Product

Retrieve Questions and Answers for a given product using the product SKU number.

 
gethttps://api.yotpo.com/products/app_key/sku/questions
GET https://api.yotpo.com/products/YOUR_APP_KEY/1234/questions
A binary file was returned

You couldn't be authenticated

  {
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response": {
        "total_questions": 2,
        "total_answers": 2,
        "questions": [
            {
                "id": 4682,
                "content": "Can I use the camera with gloves?",
                "asker": {
                    "id": 1009196,
                    "display_name": "john carter",
                    "slug": "john-carter",
                    "social_image": "https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png",
                    "is_social_connected": false,
                    "bio": null,
                    "score": 0,
                    "badges": []
                },
                "user_type": "User",
                "created_at": "2014-07-01T14:30:01.173Z",
                "sorted_public_answers": [
                    {
                        "id": 15421,
                        "content": "You can, as long as they are not too thick",
                        "store_owner_comment": true,
                        "answerer": {
                            "id": 1002730,
                            "display_name": "David davidson",
                            "slug": "vladi-testing",
                            "social_image": null,
                            "is_social_connected": false,
                            "bio": null,
                            "score": 16,
                            "badges": [
                                {
                                    "id": 1,
                                    "name": "Newbie",
                                    "description": "Hooray, you wrote your first review with Yotpo! Now you have this cool profile page, and you can earn Yotpo score and have even more badges.",
                                    "image_100": "http://s3.amazonaws.com/yotpo-static-images/badges/100/1.png",
                                    "image_300": "http://s3.amazonaws.com/yotpo-static-images/badges/300/1.png"
                                }
                            ]
                        },
                        "votes_up": 0,
                        "votes_down": 1,
                        "created_at": "2014-07-01T14:30:58.673Z"
                    }
                ]
            }
        ]
    }
}
{
    "status": {
        "message": "Feature is disabled questions_and_answers",
        "code": 401,
        "error_type": "Exceptions::FeatureDisabled"
    }
}
{
    "status": {
        "message": "Couldn't find Account with app_key = PdFT1iSNcIZr5EOmLUeDZvZV1Wx3mLa",
        "code": 404,
        "error_type": "Exceptions::RecordNotFound"
    }
}
{
    "status": {
        "message": "Couldn't find ProductsApp with domain_key = 20122",
        "code": 404,
        "error_type": "Exceptions::RecordNotFound"
    }
}

Path Params

app_key
string
required

Your Yotpo account API key

sku
string
required

The unique ID of the product on your site (does not have to be the SKU)

 

You can retrieve the answer_id from sorted_public_answers

"sorted_public_answers": [
                    {
                        "id": 15421,
Suggest Edits

Retrieve the Bottom Line for Questions and Answers

Retrieve the Bottom Line for a given product using the product SKU number. The Bottom Line will return the total questions and total answers for the desired product.

 
gethttps://api.yotpo.com/products/app_key/sku/qna_bottomline
GET https://api.yotpo.com/products/YOUR_APP_KEY/1234/qna_bottomline
A binary file was returned

You couldn't be authenticated

{
   status:{  
      code:200,
      message:"OK"
   },
   response:{  
      total_questions:7,
      total_answers:9
   }
}
{
    "status": {
        "message": "Feature is disabled questions_and_answers",
        "code": 401,
        "error_type": "Exceptions::FeatureDisabled"
    }
}
{
    "status": {
        "message": "Couldn't find Account with app_key = PdFT1iSNcIZr5EOmLUeDZvZV1Wx3mLa",
        "code": 404,
        "error_type": "Exceptions::RecordNotFound"
    }
}
{
    "status": {
        "message": "Couldn't find ProductsApp with domain_key = 20122",
        "code": 404,
        "error_type": "Exceptions::RecordNotFound"
    }
}

Path Params

app_key
string
required

Your Yotpo account API key

sku
string
required

The ID of the product on your site

 
Suggest Edits

Vote on Answers

Vote up or down on a particular answer to a question by answer_id.

 
posthttps://api.yotpo.com/answers/answer_id/vote/vote_type
POST https://api.yotpo.com/answers/1234/vote/down 
A binary file was returned

You couldn't be authenticated

{
 "status": {
   "code": 200,
   "message": "OK"
 },
 "response": {
   "vote": {
     "id": 11 //incremental vote id
   }
 }
}

Path Params

answer_id
string
required

The ID of the answer

vote_type
string
required

Vote type - up or down

 

Note:

Retrieve an answer_id param by utilizing the Retrieve Questions and Answers for a Product endpoint. Your answer_id will appear as such:

"sorted_public_answers": [
                    {
                        "id": 15421,

Note:

The id in the response is an index that is incremented. It is not connected to the review_id

Suggest Edits

Introduction to Reviews

 

What are Reviews?

Reviews are the core content generated using Yotpo. Yotpo helps generating reviews which can then later be displayed on the store's site and published on social networks.

What you can do with reviews?

The following calls API calls are available:

Call
See

Creating Reviews
This call is recommend for general use. Use this call to create reviews as an anonymous reviewer. Creating reviews using this method will send review verification emails to all the customers you've created reviews for.

Creating Reviews (Synchronous)
Note: This method is recommended for development only.

Retrieve reviews for a specific user using external user reference ID

Retrieve reviews for a specific product

Get bottom line (total reviews and average score) for all products

Get bottom line (total reviews and average score) for a specific product

Get detailed review information

Create votes for a review

Suggest Edits

Creating Reviews

This is the asynchronous method and is recommended for general use.

 
posthttps://api.yotpo.com/v1/widget/reviews
POST https://api.yotpo.com/v1/widget/reviews
-------------------------------------------

{
 "appkey": "### YOUR APP_KEY HERE ###",
 "domain": "http://www.shop.com",
 "sku": "10",
 "product_title": "Phone",
 "product_description": "Smart Phone",
 "product_url": "http://www.shop.com/phone.html",
 "product_image_url": "http://www.shop.com/phone.jpg",
 "display_name": "John Smith",
 "email": "john@shop.com",
 "review_content": "It’s really good",
 "review_title": "Great Phone",
 "review_score": 5
}
POST: https://api.yotpo.com/v1/widget/reviews
--------------------------------------------
{
 "appkey": "Fyhba57IlBTciQecZ8uMxpiI7N5Z0wp7EhLQih6M",
 "domain": "http://my-store.myshopify.com",
 "sku": "10",
 "product_title": "Black T-Shirt",
 "product_description": "A very nice T-Shirt made with 100% cotton",
 "product_url": "https://my-store.myshopify.com/products/Black T-Shirt",
 "display_name": "Johni Smith",
 "email": "jsmith@shopper.com",
 "review_content": "I love this shirt",
 "review_title": "I love T-Shirts",
 "review_score": 5,
 "custom_fields": {
     "--12159": "empty answers3? empty answers3?",
     "--12014": "123"
 }
}
POST https://api.yotpo.com/v1/widget/reviews
-------------------------------------------

{
"appkey": "PGIkyrrTBQ0VtQOn8rPpedQEEdBIL7vtr9Cu4LvA",
"domain": "http://www.shop.com",
"sku": "10",
"product_title": "Phone",
"product_description": "Smart Phone",
"product_url": "http://www.shop.com/phone.html",
"product_image_url": "http://www.shop.com/phone.jpg",
"display_name": "John Smith",
"email": "john@shop.com",
"review_content": "It’s really good",
"review_title": "Great Phone",
"review_score": 5,
"signature": "The SHA256 or HMAC signature goes here", 
"time_stamp": "1426770722",
"reviewer_type": "verified_buyer"
}
A binary file was returned

You couldn't be authenticated

{
    "code": 200,
    "message": "ok",
    "image_upload_token": "08733ce2540436bfe12ee87e5b26d7feffe22298"
}
{
    "status": {
        "message": "Missing email",
        "code": 500,
        "error_type": "Exceptions::InvalidParams"
    }
}

Body Params

appkey
string
required

Your Yotpo account API key

domain
string

The account domain

sku
string
required

The unique ID of the product on your site (doesn't have to be the SKU). To create a site review, use the value: yotpo_site_reviews

product_title
string
required

The title of the product

product_description
string

The description of the product

product_url
string
required

The url of the product

product_image_url
string

The url of the product image

display_name
string
required

The reviewer's name

email
string
required

The email of the reviewer

review_content
string
required

The content of the review

review_title
string
required

The title of the review

review_score
int32
required

The review score

signature
string

Relevant only when using the Trusted Vendors feature. The signature is the hexadecimal representation of a computed Hash-based Message Authentication Code, using SHA256 as the cryptographic function (HMAC-SHA256). The secret for the function is the account secret. Note: The time_stamp and reviewer_type parameters are mandatory when using the signature parameter.

time_stamp
date-time

Unix timestamp

reviewer_type
string

The reviewer type. Possible values: verified_buyer or verified_reviewer Note: This is relevant when creating reviews as a Trusted Vendor (signature is mandatory)

 

Important!

This call will create reviews only as anonymous and will send out review verification emails to all the customers you've created reviews for.

See Importing Your Reviews to Yotpo for information on importing reviews.

Custom Review Forms

Click the Create Review + Custom Fields tab to view a sample response of a review with custom review form fields. Contact your Yotpo Customer Success Manager if you need help identifying the custom_field slug.

e.g.
custom_fields": {
"--12159": "empty answers3? empty answers3?",
"--12014": "123"

Trusted Vendors

Trusted Vendors allows you to create verified buyers and verified reviewers without sending verification emails to shoppers you already know and trust. To enable this feature, please contact your Yotpo Customer Success Manager. Click on the Trusted Vendors tab to view a sample of a review with Trusted Reviews.

The reviewer_type parameter refers to a verified_buyer or verified_reviewer and requires a signature.

The signature, time_stamp, and reviewer_type parameters are only valid when using the Trusted Vendor feature.

The time_stamp, and reviewer_type parameters are mandatory when using the signature parameter.

To pass validation, the hash in your signature must be passed in lowercase characters.

Correct:
e3a30f856453983fc3884ca0c9ef1f31862e6ad25199803dbc192bf2a58f2b31
Incorrect:
E3A30F856453983FC3884CA0c9EF1F31862E6AD25199803DBC192BF2A58F2B31

Creating Site Reviews:

To create a site review, use the sku parameter with the value: yotpo_site_reviews

Note:

The sku parameter supports alphanumeric (a...z, A...Z, 0...9), "_" and "-" characters or the yotpo_site_reviews value.

Suggest Edits

Creating Reviews (Synchronous)

Note: This method is recommended for development only.

 
posthttps://api.yotpo.com/reviews/dynamic_create
POST: https://api.yotpo.com/reviews/dynamic_create
-------------------------------------------------

{
  "appkey": "### YOUR APP_KEY HERE###",
  "domain": "http://www.shop.com",
  "sku": "10",
  "product_title": "Phone",
  "product_description": "Smart Phone",
  "product_url": "http://www.shop.com/phone.html",
  "product_image_url": "http://www.shop.com/phone.jpg",
  "display_name": "John Smith",
  "email": "john@shop.com",
  "review_content": "It’s really good",
  "review_title": "Great Phone",
  "review_score": 5,
  "signature":"F9GJ3PbthaNLVImLB0Sk9PoAT6hZFzborCnkIWiE",
  "time_stamp":"1415107190",
  "reviewer_type":"verified_buyer"
}
POST: http://api.yotpo.com/reviews/dynamic_create
--------------------------------------------
{
 "appkey": "Fyhba57IlBTciQecZ8uMxpiI7N5Z0wp7EhLQih6M",
 "domain": "http://my-store.myshopify.com",
 "sku": "10",
 "product_title": "Black T-Shirt",
 "product_description": "A very nice T-Shirt made with 100% cotton",
 "product_url": "https://my-store.myshopify.com/products/Black T-Shirt",
 "display_name": "Johni Smith",
 "email": "jsmith@shopper.com",
 "review_content": "I love this shirt",
 "review_title": "I love T-Shirts",
 "review_score": 5,
 "custom_fields": {
     "--12159": "empty answers3? empty answers3?",
     "--12014": "123"
 }
}
POST: http://api.yotpo.com/reviews/dynamic_create
-------------------------------------------
{
"appkey": "PGIkyrrTBQ0VtQOn8rPpedQEEdBIL7vtr9Cu4LvA",
"domain": "http://www.shop.com",
"sku": "10",
"product_title": "Phone",
"product_description": "Smart Phone",
"product_url": "http://www.shop.com/phone.html",
"product_image_url": "http://www.shop.com/phone.jpg",
"display_name": "John Smith",
"email": "john@shop.com",
"review_content": "It’s really good",
"review_title": "Great Phone",
"review_score": 5,
"signature": "The SHA256 or HMAC signature goes here", 
"time_stamp": "1426770722",
"reviewer_type": "verified_buyer"
}
A binary file was returned

You couldn't be authenticated

{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response": {
        "reviews": [
            {
                "id": 2557878,
                "content": "It&#x27;s really good",
                "title": "Great Phone",
                "score": 5,
                "user": {
                    "id": 1597310,
                    "display_name": "John S.",
                    "slug": "john-s--1103",
                    "social_image": "https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png",
                    "is_social_connected": false,
                    "bio": null,
                    "score": 0,
                    "badges": []
                },
                "user_type": "User",
                "users": [],
                "products": [
                    {
                        "Location_idx": [
                            0,
                            0
                        ],
                        "Product": {
                            "product_url": "http:///www.shop.com/phone.html",
                            "id": 3512850,
                            "name": "Phone",
                            "slug": "phone--4",
                            "shorten_url": "https://yotpo.com/go/vqGhdhtG",
                            "images": [],
                            "social_network_links": {
                                "facebook": "https://yotpo.com/go/3uw3JT3N",
                                "twitter": "https://yotpo.com/go/lwQUYeb2",
                                "linkedin": "https://yotpo.com/go/4IZQlBAg",
                                "google_oauth2": "https://yotpo.com/go/9tYsZMej"
                            },
                            "facebook_testemonials_page_product_url": "https://yotpo.com/go/ztcfKvZl"
                        }
                    }
                ],
                "votes_up": 0,
                "votes_down": 0,
                "user_vote": 0,
                "created_at": "2014-12-10T15:03:16Z",
                "deleted": false,
                "new": true,
                "verified_buyer": true,
                "archived": false,
                "social_pushed": false,
                "facebook_pushed": 0,
                "twitter_pushed": 0,
                "account": {
                    "id": 15906,
                    "domain": " http://www.shop.com",
                    "map_image": {
                        "id": 3371260,
                        "image_url": "http://d2zookpajyck3d.cloudfront.net/Account/75365/3371260/thumb.png?1418043528",
                        "big_image_url": "http://d2zookpajyck3d.cloudfront.net/Account/75365/3371260/big.png?1418043528",
                        "image_content_type": "image/png",
                        "image_width": 165,
                        "image_height": 144,
                        "imageable_type": "Account",
                        "imageable_id": 75365
                    },
                    "comments_avatar": {
                        "id": 3371711,
                        "image_url": "http://d2zookpajyck3d.cloudfront.net/Account/75365/3371711/thumb.jpg?1418201566",
                        "big_image_url": "http://d2zookpajyck3d.cloudfront.net/Account/75365/3371711/big.jpg?1418201566",
                        "image_content_type": "image/jpeg",
                        "image_width": 857,
                        "image_height": 805,
                        "imageable_type": "Account",
                        "imageable_id": 75365
                    },
                    "comments_display_name": "Eli Belly"
                },
                "products_apps": [
                    {
                        "id": 3443620,
                        "product_url": "http:///www.shop.com/phone.html",
                        "domain_key": "10",
                        "product": {
                            "id": 3512850,
                            "name": "Phone"
                        }
                    }
                ]
            }
        ]
    }
}

Body Params

appkey
string
required

Your Yotpo account API key

domain
string

The account domain

sku
string
required

The ID of the product on your site

product_title
string
required

The title of the product

product_description
string

The description of the product

product_url
string

The url of the product on your ecommerce site

product_image_url
string

The url of the product image

display_name
string
required

The name of the reviewer

email
string
required

The email of the reviewer

review_content
string
required

The content of the review

review_title
string
required

The title of the review

review_score
string
required

The review score

signature
string

The signature is the hexadecimal representation of a computed Hash-based Message Authentication Code, using SHA256 as the cryptographic function (HMAC-SHA256). The secret for the function is the account secret.

time_stamp
string

Unix timestamp

reviewer_type
string

The reviewer type. Use this field only if there is also a reviews widget on the same page Possible values: verified_buyer or verified_reviewer Note: This is relevant when creating reviews as a Trusted Vendor (signature is mandatory)

user_reference
string

External user id, can be used later on to retrieve reviews associated with this user

 

Note:

The signature, time_stamp and reviewer_type parameters are only valid if you use the Trusted Vendor feature.

Trusted Vendors

Trusted Vendors allows you to create verified buyers and verified reviewers without sending verification emails to shoppers you already know and trust. To enable this feature, please contact your Yotpo Customer Success Manager. Click on the Trusted Vendors tab to view a sample of a review with Trusted Reviews.

The reviewer_type parameter refers to a verified_buyer or verified_reviewer and requires a signature.

The signature, time_stamp, and reviewer_type parameters are only valid when using the Trusted Vendor feature.

The time_stamp, and reviewer_type parameters are mandatory when using the signature parameter.

To pass validation, the hash in your signature must be passed in lowercase characters.

Correct:
e3a30f856453983fc3884ca0c9ef1f31862e6ad25199803dbc192bf2a58f2b31
Incorrect:
E3A30F856453983FC3884CA0c9EF1F31862E6AD25199803DBC192BF2A58F2B31

Custom Review Forms

Click the Create Review + Custom Fields tab to view a sample response of a review with custom review form fields. Contact your Yotpo Customer Success Manager if you need help identifying the custom_field slug.

e.g.
custom_fields": {
"--12159": "empty answers3? empty answers3?",
"--12014": "123"

Note:

This method is recommended for development only.

Note:

The sku only supports alphanumeric (a...z, A...Z, 0...9), "_" and "-" characters.

Suggest Edits

Vote on Reviews

Vote up or down on a particular review by review_id.

 
posthttps://api.yotpo.com/reviews/review_id/vote/vote_type
POST: https://api.yotpo.com/reviews/8/vote/up
A binary file was returned

You couldn't be authenticated

{
 "status": {
   "code": 200,
   "message": "OK"
 },
 "response": {
   "vote": {
     "id": 10
   }
 }
}

Path Params

review_id
string
required

The review id of the review you want to add vote to

vote_type
string
required

Vote type - up or down

 

Note:

The "id" in the response is an index that is incremented. It is not connected to the review_id.

Suggest Edits

Retrieve All Reviews

 
gethttps://api.yotpo.com/v1/apps/app_key/reviews?utoken=utoken
GET https://api.yotpo.com/v1/apps/YOUR_APP_KEY/reviews?utoken=YOUR_UTOKEN&page=1&count=4
A binary file was returned

You couldn't be authenticated

{
    "reviews": [
        {
            "id": 34789515,
            "title": "GREAT shirts",
            "content": "I now have several of these shirts and they are great. Great quality and look. My only minor complaint is that I have had one or two that have been SLIGHTLY on the small side. That said, their order process is easy and the product is great I will continue to buy most of my shirts from them.",
            "score": 4,
            "votes_up": 0,
            "votes_down": 0,
            "created_at": "2016-12-27T14:43:58.000Z",
            "updated_at": "2017-04-13T18:56:19.000Z",
            "sentiment": 0.963555,
            "sku": "1",
            "name": "Robert S.",
            "email": "robsmith@email.com",
            "reviewer_type": "verified_buyer",
            "deleted": false,
            "user_reference": null
        },
        {
            "id": 34950796,
            "title": "Very Good Shirts",
            "content": "These shirts fit well and are excellent quality. Need more non-iron and buttoned down choices.",
            "score": 4,
            "votes_up": 0,
            "votes_down": 0,
            "created_at": "2016-12-27T15:12:44.000Z",
            "updated_at": "2017-06-14T20:10:40.000Z",
            "sentiment": 0.981573,
            "sku": "1",
            "name": "Giorgio A.",
            "email": "garmani@email.com",
            "reviewer_type": "verified_buyer",
            "deleted": false,
            "user_reference": null
        },
        {
            "id": 34768928,
            "title": "Great shirts!",
            "content": "All four shirts I have purchsed are the perfect fit for me, and customer service is excellent. Can&#x27;t that beat that combination!",
            "score": 4,
            "votes_up": 0,
            "votes_down": 0,
            "created_at": "2016-12-27T15:56:45.000Z",
            "updated_at": "2017-04-13T19:23:01.000Z",
            "sentiment": 0.99147,
            "sku": "1",
            "name": "David M.",
            "email": "davidmancuso@loft.com",
            "reviewer_type": "verified_buyer",
            "deleted": false,
            "user_reference": null
        },
        {
            "id": 34878412,
            "title": "Great fabric and fit",
            "content": "Very pleased with the fit of all of the products that I brought a total of three shirts",
            "score": 4,
            "votes_up": 0,
            "votes_down": 0,
            "created_at": "2016-12-29T23:19:16.000Z",
            "updated_at": "2017-04-13T19:26:13.000Z",
            "sentiment": 0.98101,
            "sku": "1",
            "name": "Frankie K.",
            "email": "knuckles@warehouse.com",
            "reviewer_type": "verified_buyer",
            "deleted": false,
            "user_reference": null
        }
    ]
}

Path Params

app_key
string
required

Your Yotpo account API key

Query Params

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your token.

since_id
string

Lowest ID of the returned reviews

since_date
string

Earliest creation date of returned reviews

since_updated_at
string

Earliest update date of returned reviews

count
string

Number of reviews to return

page
string

Page number to return reviews for

deleted
boolean

Include unpublished reviews

user_reference
string

Filter by user reference

 

Note:

Yotpo recommends querying of up to 100 reviews per request. The default is 10.

Suggest Edits

Retrieve a Review by Review ID

 
gethttps://api.yotpo.com/reviews/review_id
GET https://api.yotpo.com/reviews/1010591
A binary file was returned

You couldn't be authenticated

{  
   status:{  
      code:200,
      message:"OK"
   },
   response:{  
      review:{  
         id:1010591,
         content:"Tolles Produkt zu fairen Preisen",
         title:"Tolles Produkt",
         score:5,
         user:{  
            id:650200,
            display_name:"Wolfgang Mau",
            slug:"wolfgang-mau",
            social_image:"https://lh3.googleusercontent.com/-XdUIqdMkCWA/AAAAAAAAAAI/AAAAAAAAAAA/4252rscbv5M/photo.jpg",
            is_social_connected:true,
            bio:null,
            score:0,
            badges:[  
               {  
                  id:1,
                  name:"Newbie",
                  description:"Hooray, you wrote your first review with Yotpo! Now you have this cool profile page, and you can earn Yotpo score and have even more badges.",
                  image_100:"http://s3.amazonaws.com/yotpo-static-images/badges/100/1.png",
                  image_300:"http://s3.amazonaws.com/yotpo-static-images/badges/300/1.png"
               }
            ]
         },
         user_type:"User",
         users:[  

         ],
         products:[  
            {  
               Location_idx:[  
                  0,
                  0
               ],
               Product:{  
                  product_url:"http://my.yotpo.com",
                  id:1739260,
                  name:"Canon EOS 5D Mark II",
                  slug:"canon-eos-5d-mark-ii--2",
                  shorten_url:"https://yotpo.com/go/8sPQAjFl",
                  images:[  
                     {  
                        id:1705775,
                        image_url:"http://ddcfq0gxiontw.cloudfront.net/Product/1739260/1705775/square.jpg?1455184269",
                        big_image_url:"http://ddcfq0gxiontw.cloudfront.net/Product/1739260/1705775/big.jpg?1455184269"
                     }
                  ],
                  social_network_links:{  
                     facebook:"https://yotpo.com/go/3gfFbHuY",
                     twitter:"https://yotpo.com/go/8RneA6fJ",
                     linkedin:"https://yotpo.com/go/1dxwNwR1",
                     google_oauth2:"https://yotpo.com/go/iiJdm1XC"
                  },
                  facebook_testemonials_page_product_url:"https://yotpo.com/go/hLGFhtvz"
               }
            }
         ],
         votes_up:1,
         votes_down:0,
         user_vote:0,
         sentiment: 0.732,
         created_at:"2014-03-18T09:27:45.792Z",
         deleted:false,
         new:false,
         verified_buyer:false,
         archived:false,
         social_pushed:false,
         facebook_pushed:0,
         twitter_pushed:0,
         account:{  
            id:4,
            domain:"widget.yotpo.com"
         },
         products_apps:[  
            {  
               id:1696312,
               product_url:"http://my.yotpo.com",
               domain_key:"B000HT3P7E",
               product:{  
                  id:1739260,
                  name:"Canon EOS 5D Mark II"
               }
            }
         ]
      }
   }
}

Path Params

review_id
int32
required

The review id

 
Suggest Edits

Retrieve Reviews for a Product

 
gethttps://api.yotpo.com/v1/widget/app_key/products/product_id/reviews.json
curl --request GET \
  --url https://api.yotpo.com/v1/widget/app_key/products/product_id/reviews.json
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.yotpo.com/v1/widget/app_key/products/product_id/reviews.json' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.yotpo.com/v1/widget/app_key/products/product_id/reviews.json")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.yotpo.com/v1/widget/app_key/products/product_id/reviews.json");

xhr.send(data);
import requests

url = "https://api.yotpo.com/v1/widget/app_key/products/product_id/reviews.json"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{  
  "status":{  
     "code":200,
     "message":"OK"
  },
  "response":{  
     "pagination":{  
        "page":2,
        "per_page":5,
        "total":9
     },
     "bottomline":{  
        "total_review":11,
        "average_score":4.81818,
        "star_distribution":{  
           "4":2,
           "5":9,
           "1":0,
           "2":0,
           "3":0
        },
        "custom_fields_bottomline":null
     },
     "products":[  
        {  
           "id":13,
           "domain_key":"412790437",
           "name":"Yotpo Mug",
           "social_links":{  
              "facebook":"https://yotpo.com/go/r1wYoVa9",
              "twitter":"https://yotpo.com/go/pg4zelyR",
              "linkedin":"https://yotpo.com/go/6PvD9jsG",
              "google_oauth2":"https://yotpo.com/go/srIsHCrr"
           },
           "embedded_widget_link":"https://yotpo.com/go/mjbdNtvQ",
           "testimonials_product_link":"https://yotpo.com/go/45Vp7nuj",
           "product_link":"https://yotpo.com/go/lnhRGFr0"
        }
     ],
     "product_tag":[  

     ],
     "reviews":[  
        {  
           "id":110,
           "score":5,
           "votes_up":1,
           "votes_down":0,
           "content":"Great mug",
           "title":"Perfect",
           "sentiment": 0.852,
           "created_at":"2016-06-16T12:16:05.354Z",
           "verified_buyer":true,
           "source_review_id":null,
           "custom_fields":null,
           "product_id":13,
           images_data:[
                           {
                           id: 13,
                           thumb_url: "http://s3.amazonaws.com/yotpo-images-test/Review/29/13/square.jpeg?1457513657",
                           original_url: "http://s3.amazonaws.com/yotpo-images-test/Review/29/13/original.jpeg?1457513657"
                          },
                          {
                          id: 14,
                          thumb_url: "http://s3.amazonaws.com/yotpo-images-test/Review/29/14/square.jpeg?1457513714",
                          original_url: "http://s3.amazonaws.com/yotpo-images-test/Review/29/14/original.jpeg?1457513714"
                          },
                       ],
          
           "user":{  
              "user_id":18,
              "display_name":"John Doe",
              "social_image":"https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png",
              "user_type":"User",
              "is_social_connected":0
           }
        },
       "comment": {
          "id": 1336007,
          "content": "Thanks for your review",
          "created_at": "2017-05-03T07:19:25.734Z",
          "comments_avatar": null
        }
     ]
  }
}
{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response": {
        "pagination": {
            "page": 1,
            "per_page": 1,
            "total": 82
        },
        "bottomline": {
            "total_review": 82,
            "average_score": 4.90244,
            "total_organic_reviews": 0,
            "organic_average_score": 0,
            "star_distribution": {
                "1": 1,
                "2": 0,
                "3": 0,
                "4": 4,
                "5": 77
            },
            "custom_fields_bottomline": null
        },
        "syndication_data": {},
        "grouping_data": {},
        "products": [
            {
                "id": 25066514,
                "domain_key": "domain key",
                "name": "White Sneakers",
                "social_links": {
                    "facebook": "https://yotpo.com/go/3WyJHb1w",
                    "twitter": "https://yotpo.com/go/ssniEAg4",
                    "linkedin": "https://yotpo.com/go/rhstgPxO",
                    "google_oauth2": "https://yotpo.com/go/Sm9zyBzc"
                },
                "embedded_widget_link": "https://yotpo.com/go/0cS3riZz",
                "testimonials_product_link": "https://yotpo.com/go/cFDmjHmG",
                "product_link": "https://yotpo.com/go/ZgpCJJ3t",
                "image_url": "https://dxogntwdcfq0i.cloudfront.net/Product/25066514/18972967/square.jpg?1507141113"
            }
        ],
        "product_tags": [],
        "reviews": [
            {
                "id": 47405454,
                "score": 5,
                "votes_up": 0,
                "votes_down": 0,
                "content": "I like everything about the sneakers",
                "title": "I love my new kicks",
                "created_at": "2017-11-08T01:23:18.000Z",
                "verified_buyer": true,
                "source_review_id": null,
                "sentiment": 0.526509,
                "custom_fields": {
                    "--6688": {
                        "title": "Recommended",
                        "form_id": 7144,
                        "value": "Yes",
                        "field_type": "SingleChoice"
                    },
                    "--6689": {
                        "title": "Comfort",
                        "form_id": 7144,
                        "value": 5,
                        "field_type": "Rating"
                    },
                    "--6690": {
                        "title": "How was the delivery service?",
                        "form_id": 7144,
                        "field_type": "CustomerFreeText",
                        "value": "The package arrived intact and on time"
                    },
                    "--6691": {
                        "title": "What is your favorite thing about the shoes?",
                        "form_id": 7144,
                        "field_type": "ProductFreeText",
                        "value": "I love the fact that they are lightweight and comfy"
                    }
                },
                "product_id": 25066514,
                "user": {
                    "user_id": 14229046,
                    "display_name": "Fred P.",
                    "social_image": null,
                    "user_type": "User",
                    "is_social_connected": 0
                }
            }
        ]
    }
}

Path Params

app_key
string
required

Your Yotpo account API key

product_id
string
required

The ID of the product on your site

Query Params

per_page
string

Reviews per page

page
string

Page number to return reviews for

star
int32

Star rating for the product (1 to 5)

sort
string

Responses can be sorted by: date, votes_up, votes_down, time, rating, or reviewer_type

direction
string

Sort order: desc or asc

 

Note:

The product_id only supports alphanumeric (a...z, A...Z, 0...9), "_" and "-" characters.

Custom Review Forms

Click the Create Review + Custom Fields tab to view a sample response of a review with custom review form fields. Contact your Yotpo Customer Success Manager if you need help identifying the custom_field slug.

Suggest Edits

Retrieve Reviews for a User Using External User Reference ID

This endpoint requires a Yotpo premium plan. To learn more about this feature, click here.

 
gethttps://api.yotpo.com/products/app_key/yotpo_global_reviews/reviews.json?user_reference=5853381989
curl --request GET \
  --url 'https://api.yotpo.com/products/app_key/yotpo_global_reviews/reviews.json?user_reference=5853381989'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.yotpo.com/products/app_key/yotpo_global_reviews/reviews.json',
  qs: { user_reference: '5853381989' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.yotpo.com/products/app_key/yotpo_global_reviews/reviews.json?user_reference=5853381989")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.yotpo.com/products/app_key/yotpo_global_reviews/reviews.json?user_reference=5853381989");

xhr.send(data);
import requests

url = "https://api.yotpo.com/products/app_key/yotpo_global_reviews/reviews.json"

querystring = {"user_reference":"5853381989"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response": {
        "bottomline": {
            "total_reviews": 4328,
            "average_score": 4.81
        },
        "reviews": [
            {
                "id": 48264478,
                "title": "Perfect, great fit and quality",
                "content": "Perfect, great fit and quality fabric.",
                "score": 5,
                "votes_up": 0,
                "votes_down": 0,
                "user_type": "User",
                "user_vote": 0,
                "deleted": false,
                "new": false,
                "verified_buyer": true,
                "archived": false,
                "social_pushed": false,
                "facebook_pushed": 0,
                "twitter_pushed": 0,
                "created_at": "2017-11-13T18:10:05.000Z",
                "updated_at": "2017-11-13T22:54:37.000Z",
                "user_reference": "5853381989",
                "users": [],
                "user": {
                    "id": 14220530,
                    "display_name": "Laura S.",
                    "slug": "laura-s-14188339604672942810",
                    "social_image": "https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png",
                    "is_social_connected": false,
                    "bio": null,
                    "score": 0,
                    "badges": []
                },
                "products": [
                    {
                        "Location_idx": [
                            0,
                            0
                        ],
                        "Product": {
                            "id": 19059423,
                            "name": "Casablanca",
                            "slug": "casablanca--15026822254372427",
                            "product_url": "http://www.shirtstore.com/products/casablanca-1",
                            "shorten_url": "https://yotpo.com/go/zdYLqwyf",
                            "images": [
                                {
                                    "id": 14088727,
                                    "image_url": "https://ddcfq0gxiontw.cloudfront.net/Product/19059423/14088727/square.jpg?1512208919",
                                    "big_image_url": "https://ddcfq0gxiontw.cloudfront.net/Product/19059423/14088727/big.jpg?1512208919"
                                }
                            ],
                            "social_network_links": {
                                "facebook": "https://yotpo.com/go/9rE7vkSV",
                                "twitter": "https://yotpo.com/go/b8DLD0se",
                                "linkedin": "https://yotpo.com/go/xPuuMNQn",
                                "google_oauth2": "https://yotpo.com/go/6eiPnlxP"
                            },
                            "facebook_testemonials_page_product_url": "https://yotpo.com/go/unavuR5y"
                        }
                    }
                ],
                "products_apps": {
                    "id": 18880628,
                    "product_url": "http://www.shirtstore.com/products/casablanca-1",
                    "domain_key": "360430337",
                    "product": {
                        "id": 19059423,
                        "name": "Casablanca"
                    }
                },
                "account": {
                    "id": 187091,
                    "domain": "http://www.shirtstore.com",
                    "map_image": {
                        "id": 13577180,
                        "image_url": "https://ddcfq0gxiomtw.cloudfront.net/Account/187091/13577180/thumb.?1486410867",
                        "big_image_url": "https://ddcfq0gxiomtw.cloudfront.net/Account/187091/13577180/big.?1486410867",
                        "image_content_type": "image/png",
                        "image_width": 2550,
                        "image_height": 409
                    }
                }
            }
        ]
    }
}

Path Params

app_key
string
required

Your Yotpo account API key

Query Params

user_reference
string
required

External User ID for which to return the reviews.

since_id
string

Minimum ID of the returned reviews

since_date
date

Earliest creation date of returned reviews

since_updated_at
date

Earliest update date of returned reviews

count
string

Number of reviews to return

page
string

Page number to return reviews for

 

Important:

This endpoint requires a Yotpo premium plan. To learn more about this feature, click here.

Suggest Edits

Retrieve Widget Site Reviews

 
gethttps://api.yotpo.com/v1/widget/app_key/products/yotpo_site_reviews/reviews.json
GET https://api.yotpo.com/v1/widget/YOUR_APP_KEY/products/yotpo_site_reviews/reviews.json?per_page=3&page=1
A binary file was returned

You couldn't be authenticated

{
 "status": {
   "code": 200,
   "message": "OK"
 },
   "response": {
        "pagination": {
            "page": 1,
            "per_page": 3,
            "total": 226
        },
        "bottomline": {
            "total_review": 0,
            "average_score": 0,
            "star_distribution": {
                "1": 0,
                "2": 0,
                "3": 0,
                "4": 11,
                "5": 215
            }
        },
        "products": [
            {
                "id": 13701,
                "domain_key": "yotpo_site_reviews",
                "name": "http://www.yotpo.com",
                "social_links": {
                    "facebook": "https://staging.yotpo.com/go/osCcXZ59",
                    "twitter": "https://staging.yotpo.com/go/wfmwZq1n",
                    "linkedin": "https://staging.yotpo.com/go/suxQA3tX",
                    "google_oauth2": "https://staging.yotpo.com/go/eryV9Etw"
                },
                "embedded_widget_link": "http://www.yotpo.com",
                "testimonials_product_link": "https://staging.yotpo.com/go/94DY1dA7"
            }
        ],
        "reviews": [
            {
                "id": 28101,
                "score": 5,
                "votes_up": 7,
                "votes_down": 1,
                "content": "I Love everything about Yotpo!! Phenomenal customer service plus the product selection is enormous... Anything you could imagine...wait...AND MORE!!",
                "title": "Best Store Hands Down",
                "sentiment": 0.989,
                "created_at": "2013-03-06T23:08:21.634Z",
                "verified_buyer": false,
                "product_id": 13701,
                "user": {
                    "user_id": 19541,
                    "display_name": "Peter K.",
                    "social_image": "https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png",
                    "user_type": "User",
                    "is_social_connected": 0
                }
            },
            {
                "id": 28102,
                "score": 5,
                "votes_up": 7,
                "votes_down": 1,
                "content": "This is my first time online shopping at Yotpo, but i did shop in store several times and i found this store price is way cheaper than any other Ny gift store in Manhattan. My purchase is quite a lot, with assorted, but Yotpo could handle and shipped it very quick, with neat package. I already recommend this store to all of my friends. If i could make a suggestion, maybe Yotpo could update the online product for more, because i couldn&#x27;t find some of the product i bought in store, on line. Thank you",
                "title": "Great Selection, Great Prices",
                "created_at": "2013-03-06T23:09:24.472Z",
                "verified_buyer": false,
                "product_id": 13701,
                "user": {
                    "user_id": 19567,
                    "display_name": "Ria A.",
                    "social_image": "https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png",
                    "user_type": "User",
                    "is_social_connected": 0
                }
            },
            {
                "id": 29879,
                "score": 5,
                "votes_up": 4,
                "votes_down": 0,
                "content": "Good price, good product and very fast delivery. would buy again",
                "title": "Triple Crown",
                "sentiment": 0.758,
                "created_at": "2013-03-11T18:45:44.635Z",
                "verified_buyer": false,
                "product_id": 13701,
                "user": {
                    "user_id": 20852,
                    "display_name": "Steve E.",
                    "social_image": "https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png",
                    "user_type": "User",
                    "is_social_connected": 0
                }
            }
        ]
    }
}

Path Params

app_key
string
required

Your Yotpo account API key

Query Params

per_page
string

Number of reviews to return per page

page
string

Page number to return reviews for

 

Note:

Yotpo recommends querying of 50 reviews per request.

Suggest Edits

Retrieve Bottom Line (Total Reviews and Average Score) for a Specific Product

 
gethttps://api.yotpo.com/products/app_key/product_id/bottomline
GET https://api.yotpo.com/products/YOUR_APP_KEY/product_id/bottomline
A binary file was returned

You couldn't be authenticated

{
   "status":{
      "code":200,
      "message":"OK"
   },
   "response":{
      "bottomline":{
         "average_score":4.52,
         "total_reviews":23
      }
   }
}

Path Params

app_key
string
required

Your Yotpo account API key

product_id
string
required

The ID of the product on your site

 
Suggest Edits

Retrieve Bottom Line (Total Reviews and Average Score) for All Products

A request to retrieve all bottomlines (average score and review count of an account). The request is paginated and limited for a maximum of 100 items per page

 
gethttps://api.yotpo.com/v1/apps/app_key/bottom_lines?count=5&page=5
curl --request GET \
  --url 'https://api.yotpo.com/v1/apps/app_key/bottom_lines?count=5&page=5'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.yotpo.com/v1/apps/app_key/bottom_lines',
  qs: { count: '5', page: '5' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.yotpo.com/v1/apps/app_key/bottom_lines?count=5&page=5")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.yotpo.com/v1/apps/app_key/bottom_lines?count=5&page=5");

xhr.send(data);
import requests

url = "https://api.yotpo.com/v1/apps/app_key/bottom_lines"

querystring = {"count":"5","page":"5"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response": {
        "bottomlines": [
            {
                "domain_key": "1518844613",
                "product_score": 4.86,
                "total_reviews": 28
            },
            {
                "domain_key": "158482417",
                "product_score": 4.74,
                "total_reviews": 31
            },
            {
                "domain_key": "158483079",
                "product_score": 4.84,
                "total_reviews": 32
            },
            {
                "domain_key": "158486229",
                "product_score": 5,
                "total_reviews": 8
            },
            {
                "domain_key": "158489459",
                "product_score": 5,
                "total_reviews": 5
            }
        ],
        "page": "5",
        "per_page": "5"
    }
}

Path Params

app_key
string
required

Your Yotpo account API key

Query Params

count
int32
required

The amount of bottom lines to return per page. Maximum 100 per page.

page
int32
required

The page number of the paginated response.

since_date
date

Earliest creation date of returned reviews (YYYY-MM-DD)

since_id
string

Minimum ID of the returned reviews.

 
Suggest Edits

Retrieve Bottom Line (Total Reviews and Average Score) for All Site Reviews

Retrieve all bottom lines (average score and total site review count per account).

 
gethttps://api.yotpo.com/products/app_key/yotpo_site_reviews/bottomline
curl --request GET \
  --url https://api.yotpo.com/products/app_key/yotpo_site_reviews/bottomline
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.yotpo.com/products/app_key/yotpo_site_reviews/bottomline' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.yotpo.com/products/app_key/yotpo_site_reviews/bottomline")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.yotpo.com/products/app_key/yotpo_site_reviews/bottomline");

xhr.send(data);
import requests

url = "https://api.yotpo.com/products/app_key/yotpo_site_reviews/bottomline"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response": {
        "bottomline": {
            "average_score": 4.9,
            "total_reviews": 120
        }
    }
}

Path Params

app_key
string
required

Your Yotpo account API key

 
Suggest Edits

Introduction to SEO

 

What are Rich Snippets?

Rich snippets are extra pieces of information which are shown within Google search results to provide more information to the person running the search.

What can you do with Rich Snippets?

The Yotpo API lets you do the following with the Rich Snippets and SEO resources. More detailed versions of these general actions may be available:

Call
See

/apps/:app_key/bottom_lines?utoken=:utoken&since_date=:since_date&since_id=:since_id

/products/:app_key/:product_id/bottomline?callback=:callback

What is In-Line SEO?

It is possible to use the Yotpo API to store all the reviews directly on the product pages, in in-line SEO. This is the best and most organic way to increase SEO.

What can you do with in-line SEO?

The Yotpo API lets you do the following with the in-line SEO and SEO resources. More detailed versions of these general actions may be available:

Call
See

/batch?methods=[]

S

Suggest Edits

Find if your yopto.me Subdomain is Available

 
gethttps://api.yotpo.com/apps/app_key/subomain_check/subdomain?utoken=utoken
GET https://api.yotpo.com/apps/YOUR_APP_KEY/subomain_check/MySite/?utoken=YOUR_UTOKEN
A binary file was returned

You couldn't be authenticated

{"status" : {
    "code" : 200,
    "message" : "OK"
  },
  "response" : {
    "subdomain" : {
      "available" : "true",
      "subdomain" : "MySite"
    }
  }
}

Path Params

app_key
string
required

Your Yotpo account API key, also known as the client_id.

subdomain
string
required

The name of the subdomain you wish to verify.

Query Params

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your token.

 

If the “available” result is “true”, then the subdomain name is available.

Suggest Edits

Retrieve your reviews.me URL

Reviews.me generates SEO friendly pages to be used in various SEO features, such as Rich Snippets

 
gethttps://api.yotpo.com/v1/reviews_me/url/app_key/product_id
curl --request GET \
  --url https://api.yotpo.com/v1/reviews_me/url/app_key/product_id
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.yotpo.com/v1/reviews_me/url/app_key/product_id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.yotpo.com/v1/reviews_me/url/app_key/product_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.yotpo.com/v1/reviews_me/url/app_key/product_id");

xhr.send(data);
import requests

url = "https://api.yotpo.com/v1/reviews_me/url/app_key/product_id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{"code":200,
 "message":"ok",
 "response":{
   "reviews_me_url":"http://reviews.me/apparel-accessories/store-slug/id"
 }
}

Path Params

app_key
string
required

Your Yotpo account API key

product_id
string
required

The product id you want to get the URL for (leave blank for site reviews)

 
Suggest Edits

Introduction to Unsubscribers

 

What are Unsubscribers?

Unsubscribers are your customers who unsubscribed from one of Yotpo's emails. Once unsubscribed, a customer stops receiving all Yotpo emails of any type. Using the API you can re-subscribe an unsubscribed customer. By default, all customers are subscribed.
The un-subscriber resource is used to manage mailing lists in the Yotpo system. Customers are opted in by default: using this resource you can add and remove customers from specific bulk mails.

What Can You Do With Unsubscribers?

The following calls API calls are available:

Call
See

POST /apps/{app_key}/unsubscribers/mass_create

DELETE /apps/{app_key/unsubscribers/mass_delete

GET /apps/:app_key/unsubscribers?utoken=:utoken

Suggest Edits

Remove a Set of Email Addresses from Email Distribution Lists

 
posthttps://api.yotpo.com/apps/:app_key/unsubscribers/mass_create
POST https://api.yotpo.com/apps/YOUR_APP_KEY/unsubscribers/mass_create
-----------------------------------------------------------------------------------

{
  "utoken": "### YOUR UTOKEN HERE ###",
  "email_list": {
    "1": [
      "test@gmail.com",
      "test2@gmail.com",
      "test4@gmail.com"
    ],
    "3": [
      "test@gmail.com",
      "test2@gmail.com",
      "test4@gmail.com"
    ]
  }
}
A binary file was returned

You couldn't be authenticated

{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "response": {
    "unsubscribers": [
      {
        "id": 105158,
        "user_email": "test@gmail.com",
        "email_type_id": 1,
        "unsubscirbed_by_name": "MODERATOR"
      },
      {
        "id": 105159,
        "user_email": "test2@gmail.com",
        "email_type_id": 1,
        "unsubscirbed_by_name": "MODERATOR"
      },
      {
        "id": 105160,
        "user_email": "test4@gmail.com",
        "email_type_id": 1,
        "unsubscirbed_by_name": "MODERATOR"
      },
      {
        "id": 105161,
        "user_email": "test@gmail.com",
        "email_type_id": 3,
        "unsubscirbed_by_name": "MODERATOR"
      },
      {
        "id": 105162,
        "user_email": "test2@gmail.com",
        "email_type_id": 3,
        "unsubscirbed_by_name": "MODERATOR"
      },
      {
        "id": 105163,
        "user_email": "test4@gmail.com",
        "email_type_id": 3,
        "unsubscirbed_by_name": "MODERATOR"
      }
    ]
  }
} 
{
    "status": {
        "message": "Feature is disabled MapBlackList",
        "code": 401,
        "error_type": "Exceptions::FeatureDisabled"
    }
}
{
  "status": {
    "code": 200,
    "message": "OK"
  }
}  
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "errors": [
    {
      "value": "14",
      "error": "email type ID is not valid"
    },
    {
      "value": "invalid-email-1",
      "error": "email is not valid"
    },
    {
      "value": "invalid-email-2",
      "error": "email is not valid"
    }
  ]
}

Body Params

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your token.

email_list
object
email_list.email_type
object

Email type

email_list.email_type.email
array of strings
required

Email address

async
boolean

Perform subscription changes asynchronously.

validate_data
boolean

Validate the email_list. You can only use this parameter with async.

 

Note:

  • For multiple requests, Yotpo recommends passing batches of 150 emails per request.
  • If you use the async parameter, the response does not contain "unsubscribers".
  • If you use the validate_data parameter, the response will contain errors if the requested parameters are not valid.

Email Types

Number
Email Type

1

Mails After Purchase and other reminder emails

2

Targeted Review Requests

3

Mail after service: emails sent as a follow-up in Zendesk integration

4

Comment requests: store owners with comments feature, get this after a new review is written

5

Comment notification: reviewers get this after store owner comments on a review

6

Site reminder: site review requests that sent with the 'slider' feature

7

Mail after invoice: emails sent from the "Site Review Automation" feature

8

Question confirmation: mail sent to confirm the email of a user who asks a question. Questions are only submitted once the poser confirms their email.

9

Answer request shop owner

10

Answer request shoppers

11

Answer notification shop owner

12

Answer notification shoppers: the notification sent to the user that asked the question that the question has been answered

13

Resend reminder: this is only sent when a reminder is resent manually from the Admin

14

Anonymous testimonials request: HubSpot integration emails

15

Targeted Product Review request: the Targeted Product Review request email

16

Coupon Reminder

17

Coupon Notification

Suggest Edits

Retrieve a List of Unsubscribers

 
gethttps://api.yotpo.com/apps/app_key/unsubscribers?utoken=utoken
GET https://api.yotpo.com/apps/YOUR_APP_KEY/unsubscribers?utoken=YOUR_UTOKEN
A binary file was returned

You couldn't be authenticated

{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response": {
        "unsubscribers": [
            {
                "id": 2038,
                "user_email": "test@gmail.com",
                "email_type_id": 1,
                "unsubscirbed_by_name": "USER"
            },
            {
                "id": 2226,
                "user_email": "test2@gmail.com",
                "email_type_id": 1,
                "unsubscirbed_by_name": "USER"
            },
            {
                "id": 2732,
                "user_email": "test3@gmail.com",
                "email_type_id": 1,
                "unsubscirbed_by_name": "USER"
            },
            {
                "id": 2912,
                "user_email": "test4@gmail.com",
                "email_type_id": 1,
                "unsubscirbed_by_name": "USER"
            }
        ]
    }
}

Path Params

app_key
string
required

Your Yotpo account API key

Query Params

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your token.

count
string

Number of unsubscribers to return

page
string

Page number to return unsubscribers for

 

Important

Please note that this call will return the first 5000 responses only. If your list of unsubscribers exceeds 5000 email addresses, you will be required to query the 'count' and 'page' params.

Suggest Edits

Re-Add Email Addresses to Email Distribution Lists

 
deletehttps://api.yotpo.com/apps/:app_key/unsubscribers/mass_delete
DELETE https://api.yotpo.com/apps/YOUR_APP_KEY/unsubscribers/mass_delete
-----------------------------------------------------------------------------------

{
  "utoken": "### YOUR UTOKEN HERE ###",
  "email_list": {
    "1": [
      "test@gmail.com",
      "test2@gmail.com",
      "test4@gmail.com"
    ],
    "3": [
      "test@gmail.com",
      "test2@gmail.com",
      "test4@gmail.com"
    ]
  }
}
A binary file was returned

You couldn't be authenticated

{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "response": {
    "unsubscribers": [
      {
        "id": 18637,
        "user_email": "test@gmail.com",
        "email_type_id": 1,
        "unsubscirbed_by_name": "USER"
      },
      {
        "id": 18638,
        "user_email": "test2@gmail.com",
        "email_type_id": 1,
        "unsubscirbed_by_name": "USER"
      },
      {
        "id": 18639,
        "user_email": "test4@gmail.com",
        "email_type_id": 1,
        "unsubscirbed_by_name": "USER"
      },
      {
        "id": 18640,
        "user_email": "test@gmail.com",
        "email_type_id": 3,
        "unsubscirbed_by_name": "USER"
      },
      {
        "id": 18641,
        "user_email": "test2@gmail.com",
        "email_type_id": 3,
        "unsubscirbed_by_name": "USER"
      },
      {
        "id": 18642,
        "user_email": "test4@gmail.com",
        "email_type_id": 3,
        "unsubscirbed_by_name": "USER"
      }

    ]  }}
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "errors": [
    {
      "value": "14",
      "error": "email type ID is not valid"
    },
    {
      "value": "invalid-email-1",
      "error": "email is not valid"
    },
    {
      "value": "invalid-email-2",
      "error": "email is not valid"
    }
  ]
}
{
  "status": {
    "code": 200,
    "message": "OK"
  }
}  

Body Params

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your token.

email_list
object
email_list.email_type
object

Email type

email_list.email_type.email
array of strings
required

Email address

async
boolean

Perform subscription changes asynchronously.

validate_data
string

Validate the email_list. You can only use this parameter with async.

 

Note:

  • For multiple requests, Yotpo recommends passing batches of 150 emails per request.
  • If you use the async parameter, the response does not contain "unsubscribers".
  • If you use the validate_data parameter, the response will contain errors if the requested parameters are not valid.

Email Types

Number
Email Type

1

Mails After Purchase and other reminder emails

2

Targeted Review Requests

3

Mail after service: emails sent as a follow-up in Zendesk integration

4

Comment requests: store owners with comments feature, get this after a new review is written

5

Comment notification: reviewers get this after store owner comments on a review

6

Site reminder: site review requests that sent with the 'slider' feature

7

Mail after invoice: emails sent from the "Site Review Automation" feature

8

Question confirmation: mail sent to confirm the email of a user who asks a question. Questions are only submitted once the poser confirms their email.

9

Answer request shop owner

10

Answer request shoppers

11

Answer notification shop owner

12

Answer notification shoppers: the notification sent to the user that asked the question that the question has been answered

13

Resend reminder: this is only sent when a reminder is resent manually from the Admin

14

Anonymous testimonials request: HubSpot integration emails

15

Targeted Product Review request: the Targeted Product Review request email

16

Coupon Reminder

17

Coupon Notification

Suggest Edits

Introduction to Users

 

What are Users?

A Yotpo user is an e-commerce store owner who has opened a Yotpo account with an email and password. Yopto users use their accounts to optimize the review experience, moderate reviews, and administer standard and optional premium functionality.
Users are represented in the Yotpo system by the following:
• User ID
• Account ID
• App ID

What can you do with Users?

The following calls API calls are available:

Suggest Edits

Create a New User in the System

 
posthttps://api.yotpo.com/users
POST https://api.yotpo.com/users
--------------------------------

{
    "user": {
        "email": "lou@company.com",
        "display_name": "lou reed",
        "password": "1234567",
        "url": "http://www.yotpo.com"
    }
}
A binary file was returned

You couldn't be authenticated

{{
  "status" : {
    "code" : 200,
    "message" : "OK"
  },
  "response" : {
    "user_id" : 11,
    "token" : "NkLHXnkIRrb3MUUVpCtI0conaoYUEIHFEMzgpYXt",
    "app_key" :"a3lmMnNmz0ZcHfC3u4S3lODeIYMQwt9LETWXRdDP",
    "secret" :"NumuaTwnCCvdvlCGOY5BRAh1LTCGibFptYxfvebm"
  }
}
}

Body Params

email
string
required

The user's email

display_name
string
required

The user's name as it appears in Yotpo

password
string
required

The user's password

url
string
required

The main URL of the user

 

Important:

Save the response of this call. You cannot generate the app_key and secret using other calls.

Suggest Edits

Retrieve a User’s Profile Data

 
gethttps://api.yotpo.com/users/user_id
GET https://api.yotpo.com/users/11
A binary file was returned

You couldn't be authenticated

{"response": {
        "user": {
            "id": 11,
            "slug": "jtalabot",
            "score": 0,
            "display_name": "john talabot",
            "bio": null,
            "social_image": "https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png"
        }
    }
} 

Path Params

user_id
string
required

The user_id generated by the POST /users call.

 
Suggest Edits

Get a Sign-In URL for yap.yotpo.com

 
gethttps://api.yotpo.com/users/yap_login.json?app_key=app_key&secret=secret
GET https://api.yotpo.com/users/yap_login.json?app_key= YOUR_APP_KEY&secret=### SECRET ###
A binary file was returned

You couldn't be authenticated

{
  "status" : {
    "code" : 200,
    "message" : "OK"
  },
  "response" : {
    "code" : "pStQjjzuiUfRGX0EMhqi",
    "signin_url" : "https://yap.yotpo.com/callbacks/login?code=pStQjjzuiUfRGX0EMhqi&app_key= a3lmMnC3u0ZcHf3lODeI4SNmzYM9LEQwtTWXRdDP”
  }
}

Path Params

app_key
string
required

The app_key generated by the post/users call

secret
string
required

The secret generated by the post/users call

 
Suggest Edits

Top Three 5-Star Reviews

Retrieve the top three 5-star reviews per account. This endpoint will return the top three 5-star reviews (including unpublished reviews) based on Yotpo's smart algorithm in JSON or HTML format.

 
gethttps://api.yotpo.com/apps/app_key/top_reviews
GET https://api.yotpo.com/apps/YOUR_APP_KEY/top_reviews.json
GET https://api.yotpo.com/apps/YOUR_APP_KEY/top_reviews.html
A binary file was returned

You couldn't be authenticated

{
	status: {
	code: 200,
	message: "ok"
},
	reviews: [
	{
		id: 3,
		product_id: 2,
		featured_image_id: 3,
		image: 1,
		good_length: 0,
		title: "This is the review title",
		content: "This is the review content",
		score: 5,
		created_at: "2015-03-02T11:08:01.123Z",
		product_url: "http://www.yotpo.com",
		image_url: "https://www.yotpo.com/wp-content/uploads/2015/11/Yotpo-Logo.png"
	},
	{
		id: 3,
		product_id: 2,
		featured_image_id: 3,
		image: 1,
		good_length: 0,
		title: "This is the review title",
		content: "This is the review content",
		score: 5,
		created_at: "2015-03-02T11:08:01.567Z",
		product_url: "http://www.yotpo.com",
		image_url: "https://www.yotpo.com/wp-content/uploads/2015/11/Yotpo-Logo.png"
	},{
		id: 3,
		product_id: 2,
		featured_image_id: 3,
		image: 1,
		good_length: 0,
		title: "This is the review title",
		content: "This is the review content",
		score: 5,
		created_at: "2015-03-02T11:08:01.632Z",
		product_url: "http://www.yotpo.com",
		image_url: "https://www.yotpo.com/wp-content/uploads/2015/11/Yotpo-Logo.png"
	}
	]
}

Path Params

app_key
string
required

Your Yotpo account API key

 

Yotpo's Smart Algorithm

Yotpo's smart algorithm considers the review sentiment, purchase count, content length, and when the review was created. Top reviews must have a 5-star rating/score, contain at least 100 characters, and include a product image.

Note:

This endpoint returns results for published and unpublished 5-Star Reviews alike.

Suggest Edits

Introduction to Product Grouping

 

Product Grouping allows you to create groups of related products and share reviews between all the products in the same group.

For example, say you sell a certain style of shoe in a range of colors. Your customers may only leave a small number of reviews for each color. By grouping products, you can show reviews for all the colors for that style.

Creating product groups via the API is easy and divided into three steps: creating the group, listing the groups, and filling the group with products.

  1. Create a product group
  2. Use the group name (the same name you used in order to create the group) in order to fill it with products.
    The products are identified by the product id which is sent to Yotpo from the platform (store). If you are not sure what is the product id, browse to your product page and search for a div with a class "yotpo-main-widget" in the source code, the product id listed under the data-product-id attribute of that div is usually the product id Yotpo will have stored
Suggest Edits

Create a product group

 
posthttps://api.yotpo.com/v1/apps/app_key/products_groups
POST https://api.yotpo.com/v1/apps/YOUR_APP_KEY/products_groups
{    
  "group_name":"p_one",
  "utoken": "### YOUR UTOKEN HERE ###"
} 
A binary file was returned

You couldn't be authenticated

{
    "status": {
        "code": 200,
        "message": "ok"
    }
}

Path Params

app_key
string
required

Your Yotpo account API key

Body Params

utoken
string

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your utoken.

group_name
string

The name of the product group

 
Suggest Edits

Retrieve product groups for account

 
gethttps://api.yotpo.com/v1/apps/app_key/products_groups?utoken=utoken
GET https://api.yotpo.com/v1/apps/YOUR_APP_KEY/products_groups?utoken=YOUR_UTOKEN
A binary file was returned

You couldn't be authenticated

{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response": {
        "products_groups": [
            {
                "id": 1234,
                "display_name": "group_one",
                "account_id": 12345
            }
        ]
    }
}

Path Params

app_key
string
required

Your Yotpo account API key

Query Params

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your utoken.

 
Suggest Edits

Retrieve details for a specific product group

 
gethttps://api.yotpo.com/v1/apps/app_key/products_groups/group_name?utoken=utoken
GET https://api.yotpo.com/v1/apps/YOUR_APP_KEY/products_groups/:group_name?utoken=YOUR_UTOKEN
A binary file was returned

You couldn't be authenticated

{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response": {
        "products_group": {
            "display_name": "group_one",
            "created_at": "2017-01-04T16:20:36.432Z",
            "updated_at": "2017-01-04T16:20:36.567Z",
            "products_apps": [
                {
                    "sku": "40",
                    "product_url": "http://mystore.com&product_id=40"
                },
                {
                    "sku": "30",
                    "product_url": "http://mystore.com&product_id=30"
                }
            ]
        }
    }
}

Path Params

app_key
string
required

Your Yotpo account API key

group_name
string
required

Product group name (the one you used when you created the group)

Query Params

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your utoken.

 
Suggest Edits

Add/Remove Products

Add or remove products from a product group.

 
puthttps://api.yotpo.com/v1/apps/app_key/products_groups/group_name
{
"product_ids_to_remove":[
   "###Product_ID###",
   "###Product_ID###"
], 
 "utoken": "### YOUR UTOKEN HERE ###"
}
A binary file was returned

You couldn't be authenticated

{
    "status": {
        "code": 200,
        "message": "ok"
    }
}

Path Params

app_key
string
required

Your Yotpo account API key

group_name
string
required

Product group name (the one you used when you created it)

Body Params

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your utoken.

product_ids_to_add
array of strings

Your product id to add to the group (use the same id's you use in your store, like SKUs)

product_ids_to_remove
array of strings

Your product id to remove from the group (use the same id's you used when added the products)

 
Suggest Edits

Delete a product group

 
deletehttps://api.yotpo.com/v1/apps/app_key/products_groups/group_name
{    
  "utoken": "### YOUR UTOKEN HERE ###"
}
A binary file was returned

You couldn't be authenticated

{
    "status": {
        "code": 200,
        "message": "ok"
    }
}

Path Params

app_key
string
required

Your Yotpo account API key

group_name
string
required

Product group name (the one you used when you created the group)

 

Note:

You cannot delete a product group that has products assigned to it. Delete the assignments before deleting the product group.

Suggest Edits

Introduction to Visual Marketing

Visual marketing endpoints allow you to leverage user-generated photos on your site, social pages, and ads. Check out the table below for an overview of each endpoint and its capabilities.

 

In order to use Visual Marketing endpoints, your Yotpo plan must include Yotpo's Visual Marketing Suite. Learn more

Endpoint
Description

Use this endpoint to seamlessly import an array of up to three images to Yotpo. To import more than three photos at a time, please contact Yotpo support.

Get an export of up to 7 days of images by source. Image source could be from a review, import, onsite_upload, or social. All photos may be retrieved by running a script to pull photos in 7-day batches by since / until date range (similar to pagination).

Fetches the names and ID's of all existing custom albums per account app_key.

Fetches the custom album payload including album images, tags, names, and ID's of all existing custom albums per account app_key.

Use this endpoint to retrieve product images where were curated to product albums.

Suggest Edits

Create Images

Use this endpoint to seamlessly import an array of up to three images to Yotpo. You may also leverage this endpoint to build your own custom widget. To import more than three photos at a time, please contact Yotpo support.

 
posthttps://api.yotpo.com/v1/widget/:app_key/images/create_batch
{
	"images": [{
		"user_name": "Joe User",
		"user_email": "joe@email.com",
		"tagged_products": ["298686079", "1"],
		"image_url": "https://upload.storage.org/image_server/user_generated/d/dd/image.jpg",
		"caption": "Big",
		"creation_date": "2018-01-31"
	},{
		"user_name": "Jane User",
		"user_email": "jane@email.com",
		"image_url": "https://upload.storage.org/image_server/user_generated/d/dd/image.jpg"
	}]
}
A binary file was returned

You couldn't be authenticated

No response examples available

Body Params

images
array
required

The array of images to create as a batch. This array cannot be empty and may contain a maximum of 3 entries (images).

user_name
string
required

The name of the user who provided the image

user_email
string

The email address of the reviewer who provided the image

tagged_products
array of strings

The unique product ID of the products to tag in this photo. Each image can accept a maximum of three product tags.

image_url
string
required

The URL of the image you want to create

caption
string

The image caption text

creation_date
date

The date of album creation in ISO8601 format. This cannot be a future date

 
Suggest Edits

Export Images

Get an export of up to 7 days of images by source. The image source could be from review, import, onsite_upload, or social. You can retrieve all of your photos by running a script to retreive photos in 7-day batches (similar to pagination).

 
gethttps://api.yotpo.com/v1/apps/app_key/images/export
curl --request GET \
  --url 'https://api.yotpo.com/v1/apps/app_key/images/export?utoken=utoken&source=source'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.yotpo.com/v1/apps/app_key/images/export',
  qs: 
   { utoken: 'utoken',
     source: 'source' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.yotpo.com/v1/apps/app_key/images/export?utoken=utoken&source=source")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.yotpo.com/v1/apps/app_key/images/export?utoken=utoken&source=source");

xhr.send(data);
import requests

url = "https://api.yotpo.com/v1/apps/app_key/images/export"

querystring = {"utoken":"utoken","source":"source"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response": {
        "pagination": {
            "page": 1,
            "per_page": 10,
            "total": 2
        },
        "images": [
            {
                "source": "onsite_upload",
                "image_id": "20079",
                "standard_resolution": "https://s3.amazonaws.com/yotpo-images-test/Account/251/20079/standard.jpg?1518941117",
                "thumbnail": "https://s3.amazonaws.com/yotpo-images-test/Account/251/20079/square.jpg?1518941117",
                "low_resolution": "https://s3.amazonaws.com/yotpo-images-test/Account/251/20079/medium_square.jpg?1518941117",
                "facebook_resolution": "https://s3.amazonaws.com/yotpo-images-test/Account/251/20079/facebook.jpg?1518941117",
                "twitter_resolution": "https://s3.amazonaws.com/yotpo-images-test/Account/251/20079/twitter.jpg?1518941117",
                "instagram_resolution": "https://s3.amazonaws.com/yotpo-images-test/Account/251/20079/instagram.jpg?1518941117",
                "original_image_url": "https://s3.amazonaws.com/yotpo-images-test/Account/251/20079/original.jpg?1518941117",
                "tagged_products": [
                    "1",
                    "298686079"
                ],
                "post": {
                    "content": "Big",
                    "user_name": "Jane User",
                    "user_email": "jane@email.com"
                },
                "albums": [
                    {
                        "type": "CustomAlbum",
                        "name": "UGC Gallery"
                    }
                ]
            },
            {
                "source": "onsite_upload",
                "image_id": "20080",
                "standard_resolution": "https://s3.amazonaws.com/yotpo-images-test/Account/251/20080/standard.jpg?1518944946",
                "thumbnail": "https://s3.amazonaws.com/yotpo-images-test/Account/251/20080/square.jpg?1518944946",
                "low_resolution": "https://s3.amazonaws.com/yotpo-images-test/Account/251/20080/medium_square.jpg?1518944946",
                "facebook_resolution": "https://s3.amazonaws.com/yotpo-images-test/Account/251/20080/facebook.jpg?1518944946",
                "twitter_resolution": "https://s3.amazonaws.com/yotpo-images-test/Account/251/20080/twitter.jpg?1518944946",
                "instagram_resolution": "https://s3.amazonaws.com/yotpo-images-test/Account/251/20080/instagram.jpg?1518944946",
                "original_image_url": "https://s3.amazonaws.com/yotpo-images-test/Account/251/20080/original.jpg?1518944946",
                "tagged_products": [
                    "1",
                    "298686079"
                ],
                "post": {
                    "content": "Big",
                    "user_name": "Joe User",
                    "user_email": "joe@email.com"
 },
                "albums": [
                    {
                        "type": "CustomAlbum",
                        "name": "UGC Gallery"
                    },
                    {
                        "type": "ProductAlbum",
                        "name": "1176242051"
                    }
                ]
            }
        ]
    }
}

Path Params

app_key
string
required

Your Yotpo account API key

Query Params

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your token.

source
string
required

Must choose one of the following values: review, import, onsite_upload, social

since
date

Default is 7 days back. Must be positive and less or equal to 7 days from the until date.

until
date

until default is current date. Must take place after since date

page
int32

Default is 1 page

per_page
int32

Default: 10 Maximum: 100

 

Please note that the Export Images endpoint is currently in beta.

Export Images - Images Array Response Attributes

Attribute
Description

images

The images array

source

The source of the image. e.g. 'review', 'import', 'onsite_upload', 'social'

image_id

The unique ID of the image

standard_resolution

The image in its standard resolution

low_resolution

The image in low resolution

facebook_resolution

The image cropped to Facebook resolution

twitter_resolution

The image cropped to Twitter resolution

instagram_resolution

The image cropped to Instagram resolution

original_image_url

The original image in its original resolution

tagged_products

This array includes the unique product ID of the tagged_products including the product(s) tagged to the image.

post

This hash includes the content of the image post as well as the user_name and user_email of the reviewer who posted the image.

content

The textual content of the post

user_name

The name of the reviewer who posted the image

user_email

The email address of the reviewer who posted the image

albums

The array of albums including the album type and albumname`

type

The type of album in which the image is located. This could be CustomAlbum or ProductAlbum

name

The name of the album in which the image is located. If the album type is ProductAlbum, the album name is represented by the product ID of the product tagged in the album.

Suggest Edits

Custom Albums

Fetches the names and ID's of all existing custom albums per account app_key.

 
gethttps://api.yotpo.com/albums/app_key
curl --request GET \
  --url 'https://api.yotpo.com/albums/app_key?utoken=utoken'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.yotpo.com/albums/app_key',
  qs: { utoken: 'utoken' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.yotpo.com/albums/app_key?utoken=utoken")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.yotpo.com/albums/app_key?utoken=utoken");

xhr.send(data);
import requests

url = "https://api.yotpo.com/albums/app_key"

querystring = {"utoken":"utoken"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "albums": [
        {
            "id": "5a97d283e31670685bc87539",
            "name": "UGC Gallery"
        },
        {
            "id": "5a97d283e31670685bc8753a",
            "name": "Shoppable Instagram"
        },
        {
            "id": "5a9819796efb092e2a31f3d2",
            "name": "Best Photos"
        },
        {
            "id": "5a9819c06efb09322d31ca72",
            "name": "Homepage"
        },
        {
            "id": "5a981d0d6efb092e2a320ac0",
            "name": "Fall 2017"
        },
        {
            "id": "5a9c295b505b7d437d04282f",
            "name": "Winter 2017"
        },
        {
            "id": "5a9ea6b2505b7d0012088ee2",
            "name": "Favorites"
        },
        {
            "id": "5acb8dea5d7aa0323e948981",
            "name": "Bulk"
        },
        {
            "id": "5acc694b4e904b4c471a1239",
            "name": "Good Vibes"
        },
        {
            "id": "5acc6b9b5d7aa0352094921d",
            "name": "New Shirts"
        },
        {
            "id": "5acc75924e904b60511840a0",
            "name": "T Shirts"
        },
        {
            "id": "5acdb8d676798100070e261d",
            "name": "Davids Album"
        },
        {
            "id": "5acde8164e904b00112e08ae",
            "name": "Lots of photos"
        },
        {
            "id": "5ad3140776798136170e06ec",
            "name": "New Album"
        },
        {
            "id": "5ad330c94e904b4f8a2d98c7",
            "name": "Another Album"
        },
        {
            "id": "5ad33a144e904b472b2dc922",
            "name": "New from Instagram"
        },
        {
            "id": "5ad3652b4e904b54d72e869c",
            "name": "Tal's Album"
        },
        {
            "id": "5afa841972ddd34a956b85c3",
            "name": "All Added Photos"
        },
        {
            "id": "5b0c77141b0ee5102dd01d10",
            "name": "Baryo"
        },
        {
            "id": "5b1ee5f38e45397d889f04dc",
            "name": "Women"
        },
        {
            "id": "5b2d10628e45390245526db6",
            "name": "Hats"
        }
    ]
}

Path Params

app_key
string
required

Your Yotpo account API key.

Query Params

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication to learn how to generate your token.

 
Suggest Edits

Photos by Album

Fetches the custom album payload including album images, tags, names, and ID's of all existing custom albums per account app_key.

 
gethttps://api.yotpo.com/v1/widget/app_key/albums/by_name
curl --request GET \
  --url 'https://api.yotpo.com/v1/widget/app_key/albums/by_name?album_name=album_name'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.yotpo.com/v1/widget/app_key/albums/by_name',
  qs: { album_name: 'album_name' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.yotpo.com/v1/widget/app_key/albums/by_name?album_name=album_name")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.yotpo.com/v1/widget/app_key/albums/by_name?album_name=album_name");

xhr.send(data);
import requests

url = "https://api.yotpo.com/v1/widget/app_key/albums/by_name"

querystring = {"album_name":"album_name"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response": {
        "pagination": {
            "page": 1,
            "per_page": 3,
            "total": 0
        },
        "images": [
            {
                "source": "instagram",
                "image_id": "5a98197f6efb092db231f695",
                "low_resolution_image_url": "//scontent.cdninstagram.com/vp/da9f5101451fa862caabf874716755f6/5B2B50AF/t51.2885-15/e35/p320x320/28156507_165346500940639_6306343443274661888_n.jpg",
                "original_image_url": "//scontent.cdninstagram.com/vp/88cae9a00ac8b10265bd97b7d5ef1159/5B3ECDF8/t51.2885-15/sh0.08/e35/p640x640/28156507_165346500940639_6306343443274661888_n.jpg",
                "image_url": "//scontent.cdninstagram.com/vp/c26ee077c49ceb4567d77ff073439d4e/5B37EEA0/t51.2885-15/s150x150/e35/c0.43.1080.1080/28156507_165346500940639_6306343443274661888_n.jpg",
                "external_media_id": "1724914648462926403_3220168402",
                "tagged_products": [
                    {
                        "id": 23626625,
                        "name": "Classy Signature T-Shirt",
                        "domain_key": "6",
                        "product_link": "https://yotpos-demo-store-2.myshopify.com/products/classy-signature",
                        "product_url": "https://yotpos-demo-store-2.myshopify.com/products/classy-signature",
                        "image_url": "https://ddcfq0gxiontw.cloudfront.net/Product/23827964/18687703/square.jpg?1499177861",
                        "score": null,
                        "reviews_count": null
                    }
                ],
                "post": {
                    "profile_picture": "https://scontent.cdninstagram.com/vp/ad77096025c93ac62127bc4788dd5350/5B35AAB4/t51.2885-19/s150x150/18879688_1351838138239441_1502256565162344448_a.jpg",
                    "username": "dey_ag1112",
                    "location_name": "",
                    "created_time": "2018-02-28T19:24:31.000+00:00",
                    "hashtags": [
                        "spicyblackbeanburger",
                        "lemon",
                        "terradelyssa",
                        "saladfordays",
                        "lunchtime",
                        "himalayansalt",
                        "homemadedressing",
                        "morningstarfarms",
                        "oliveoil"
                    ],
                    "content": "🍴\n#lunchtime #saladfordays #morningstarfarms #spicyblackbeanburger #homemadedressing #oliveoil #lemon #himalayansalt #terradelyssa",
                    "votes_up": 0,
                    "votes_down": 0
                }
            },
            {
                "source": "review",
                "image_id": 29087960,
                "review_id": 48902637,
                "low_resolution_image_url": "//ddcfq0gxiontw.cloudfront.net/Review/48902637/29087960/medium_square.jpg?1511673183",
                "image_url": "//ddcfq0gxiontw.cloudfront.net/Review/48902637/29087960/square.jpg?1511673183",
                "original_image_url": "//ddcfq0gxiontw.cloudfront.net/Review/48902637/29087960/original.jpg?1511673183",
                "review": {
                    "id": 48902637,
                    "review_type_id": 1,
                    "rejected": false,
                    "title": "Excellent",
                    "content": "Thank you I love them",
                    "score": 5,
                    "created_at": "2017-11-26T05:13:05.000Z",
                    "verified_buyer": 1,
                    "archived": 0,
                    "deleted": 0,
                    "votes_up": 0,
                    "votes_down": 0,
                    "user": {
                        "display_name": "renee",
                        "social_image": null,
                        "email": "renee_40057171-470c-47d8-abed-6fe8a63e84ba@staging.yotpo.com"
                    }
                },
                "product": {
                    "domain_key": "1",
                    "name": "Crewneck Pocket T-Shirt",
                    "product_url": "https://yotpos-demo-store-2.myshopify.com/products/crewneck-pocket",
                    "product_link": "https://yotpos-demo-store-2.myshopify.com/products/crewneck-pocket",
                    "image_url": "https://ddcfq0gxiontw.cloudfront.net/Product/23827969/18687695/square.jpg?1499177859"
                },
                "album_image": {
                    "_id": {
                        "$oid": "5ad367f076798169130df80d"
                    },
                    "album_id": {
                        "$oid": "5a97d283e31670685bc87539"
                    },
                    "image_created_date": "2017-11-26T05:13:05.000Z",
                    "image": {
                        "external_id": "29087960",
                        "source": "Review",
                        "_id": {
                            "$oid": "5ae9c7131b0ee527fb4098e7"
                        }
                    },
                    "favorite": false,
                    "invalidated": false,
                    "created_at": "2018-04-15T14:55:44.423Z",
                    "updated_at": "2018-04-15T14:55:44.423Z",
                    "album_name": "UGC Gallery"
                }
            },
            {
                "source": "instagram",
                "image_id": "59f73c3b3fa5a35e927847ae",
                "low_resolution_image_url": "//scontent.cdninstagram.com/vp/b4fbe8dc582627cd755d961533559c7b/5B4EB108/t51.2885-15/s320x320/e35/22860435_1627650820618673_6136770394897514496_n.jpg",
                "original_image_url": "//scontent.cdninstagram.com/vp/af4b4d91706d4f7e4ac281c8c8c6884e/5B544D45/t51.2885-15/s640x640/sh0.08/e35/22860435_1627650820618673_6136770394897514496_n.jpg",
                "image_url": "//scontent.cdninstagram.com/vp/9a1be59c71d9258922e947ff484c3f4a/5B6FD538/t51.2885-15/s150x150/e35/22860435_1627650820618673_6136770394897514496_n.jpg",
                "external_media_id": "1636642758793837508_4065356078",
                "tagged_products": [],
                "post": {
                    "profile_picture": "https://scontent.cdninstagram.com/vp/d2a9ff0d24c73924ed59ef664b0a9082/5B397663/t51.2885-19/s150x150/14717358_368701900129822_7310002550739042304_a.jpg",
                    "username": "boz_rich",
                    "location_name": "",
                    "created_time": "2017-10-30T00:24:02.000+00:00",
                    "hashtags": [
                        "wornandwound",
                        "danhenrywatches",
                        "windupnyc"
                    ],
                    "content": "Not too crazy about quartz these days but if there is ever a quartz to have in my collection, this is the one. Enter the Dan Henry Multiscale Chronograph 1939. Saw this at Wind-up Watch Fair today. And yes I will get this soon. @danhenrywatches @wornandwound  #danhenrywatches #windupnyc #wornandwound",
                    "votes_up": 0,
                    "votes_down": 0
                }
            }
        ]
    }
}

Path Params

app_key
string
required

Your Yotpo account API key

Query Params

album_name
string
required

The name of your custom album. The album name can be found by using the "Get All Album Names" endpoint.

page
int32

The page number of a paginated response. Must be greater than zero. Default: 1

per_page
int32

The number of results to return per page.

 
Suggest Edits

Product Images

Use this endpoint to retrieve images curated to product albums.

 
gethttps://api.yotpo.com/v1/widget/app_key/albums/product/product_id
curl --request GET \
  --url https://api.yotpo.com/v1/widget/app_key/albums/product/product_id
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.yotpo.com/v1/widget/app_key/albums/product/product_id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.yotpo.com/v1/widget/app_key/albums/product/product_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.yotpo.com/v1/widget/app_key/albums/product/product_id");

xhr.send(data);
import requests

url = "https://api.yotpo.com/v1/widget/app_key/albums/product/product_id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response": {
        "pagination": {
            "page": 1,
            "per_page": 3,
            "total": 0
        },
        "images": [
            {
                "source": "instagram",
                "image_id": "5acc67ab4e904b4f68197b7e",
                "low_resolution_image_url": "//scontent.cdninstagram.com/vp/768b1d9ebd06f60cf12c7847821fbd6d/5B681B7F/t51.2885-15/s320x320/e35/20986874_695325423991497_2749685599597232128_n.jpg",
                "original_image_url": "//scontent.cdninstagram.com/vp/d7ec5f13b54c190010edc3a3511aa348/5B686E3C/t51.2885-15/s640x640/sh0.08/e35/20986874_695325423991497_2749685599597232128_n.jpg",
                "image_url": "//scontent.cdninstagram.com/vp/8548e36d016cdafb184ecad8237aaf8f/5B59C938/t51.2885-15/s150x150/e35/20986874_695325423991497_2749685599597232128_n.jpg",
                "external_media_id": "1587020048554520701_27693384",
                "tagged_products": [
                    {
                        "id": 23626629,
                        "name": "Athletic T-Shirt",
                        "domain_key": "8",
                        "product_link": "https://yotpo.com/go/n78k812O",
                        "product_url": "https://yotpos-demo-store-2.myshopify.com/products/athletic",
                        "image_url": "https://ddcfq0gxiontw.cloudfront.net/Product/23827967/18687701/square.jpg?1499177862",
                        "score": null,
                        "reviews_count": null
                    },
                    {
                        "id": 23626635,
                        "name": "Deep V-Neck",
                        "domain_key": "7",
                        "product_link": "https://yotpo.com/go/ej5VgEIZ",
                        "product_url": "https://yotpos-demo-store-2.myshopify.com/products/deep-cut",
                        "image_url": "https://ddcfq0gxiontw.cloudfront.net/Product/23827971/18687696/square.jpg?1499177861",
                        "score": null,
                        "reviews_count": null
                    },
                    {
                        "id": 23626639,
                        "name": "Striped V-Neck",
                        "domain_key": "3",
                        "product_link": "https://yotpo.com/go/fCH2ZGUC",
                        "product_url": "https://yotpos-demo-store-2.myshopify.com/products/striped-v",
                        "image_url": "https://ddcfq0gxiontw.cloudfront.net/Product/23827975/18687702/square.jpg?1499177861",
                        "score": null,
                        "reviews_count": null
                    }
                ],
                "post": {
                    "profile_picture": "https://scontent.cdninstagram.com/vp/071f4a200310eb9eec2beaa53c7eb810/5B5D8455/t51.2885-19/s150x150/10598276_885098761603741_1222504716_a.jpg",
                    "username": "pakalupapito",
                    "location_name": "Yotpo",
                    "created_time": "2017-08-22T13:12:34.000+00:00",
                    "hashtags": [
                        "movingday",
                        "yotpo"
                    ],
                    "content": "",
                    "votes_up": 0,
                    "votes_down": 0
                }
            },
            {
                "source": "review",
                "image_id": 18075918,
                "review_id": 40490790,
                "low_resolution_image_url": "//ddcfq0gxiontw.cloudfront.net/Review/40490790/18075918/medium_square.jpg?1497174598",
                "image_url": "//ddcfq0gxiontw.cloudfront.net/Review/40490790/18075918/square.jpg?1497174598",
                "original_image_url": "//ddcfq0gxiontw.cloudfront.net/Review/40490790/18075918/original.jpg?1497174598",
                "review": {
                    "id": 40490790,
                    "review_type_id": 1,
                    "rejected": false,
                    "title": "Quality product",
                    "content": "Nice to purchase from a company with a wide selection of products locally. Product was exactly what I wanted and shipment arrived in a couple of days. Quality product and excellent experience. Highly recommend this vendor.",
                    "score": 5,
                    "created_at": "2017-06-11T09:49:59.000Z",
                    "verified_buyer": 1,
                    "archived": 0,
                    "deleted": 0,
                    "votes_up": 0,
                    "votes_down": 0,
                    "user": {
                        "display_name": "jerrod_demetrius_owen_59124",
                        "social_image": null,
                        "email": "jerrod_demetrius_owen_59124@staging.yotpo.com"
                    }
                },
                "product": {
                    "domain_key": "8",
                    "name": "Athletic T-Shirt",
                    "product_url": "https://yotpos-demo-store-2.myshopify.com/products/athletic",
                    "product_link": "https://yotpo.com/go/zqQETbVo",
                    "image_url": "https://ddcfq0gxiontw.cloudfront.net/Product/23827967/18687701/square.jpg?1499177862"
                },
                "album_image": {
                    "_id": {
                        "$oid": "5ac9e59d4e904b1529183d4d"
                    },
                    "album_id": {
                        "$oid": "5ac9e59d4e904b1529183d4c"
                    },
                    "created_at": "2018-04-08T09:49:17.402Z",
                    "favorite": false,
                    "image": {
                        "_id": {
                            "$oid": "5ae9cd331b0ee532a2409b59"
                        },
                        "created_at": null,
                        "external_id": "18075918",
                        "source": "Review",
                        "updated_at": null
                    },
                    "image_created_date": "2017-06-11T09:49:59.000+00:00",
                    "invalidated": false,
                    "updated_at": "2018-04-08T09:49:17.402Z"
                }
            }
        ]
    }
}

Path Params

app_key
string
required

Your Yotpo account API key

product_id
string
required

The unique product identifier.

Query Params

page
int32

The page number of a paginated response. Must be greater than zero. Default: 1

per_page
int32

The number of results to return per page.

 
Suggest Edits

Introduction to Insights API

 

To enjoy Yotpo Insights, you must be subscribed to a Yotpo Insights plan. To learn more, contact your Yotpo representative.

Authentication

Before you get started, you'll need to get your authorization credentials ready. Insights API calls are authenticated using the same Yotpo uToken used in other Yotpo endpoints. If you haven't already done so, be sure to generate a uToken bypassing your API Credentials through the Yotpo Authentication endpoint.

Once generated, pass your uToken in the API header where

  • Key: Authorization
  • Value: Bearer <###-uToken-goes-here-###>
  • e.g. "Bearer YTJZm0J7XaIcpzVN8HsWzhOcAzwdbzFJ1HDQJXSk"

Token expiration

Each uToken is valid for 14 days from the time it is generated.

Locations

Most Insights endpoints allow you to filter by reviewer location by passing country and/or state values as abbreviations through the country and state params (e.g. US, CA, NY).
For a list of supported country and state locations, see the lists below:

Suggest Edits

Topics

Retrieves topics mentioned in reviews. The response includes Insights data such as topic sentiment score, industry average, the number of opinions detected per topic, and the opinion polarity. You can filter your request by date, product, reviewer location, review score, and much more. For a full breakdown, see the body params list below.

 
posthttps://api.yotpo.com/insights/v1/topics
{
  "filter": {
    "app_key": "Your app_key here",
    "date_range": {
      "start_date": "2017-04-23T00:00:00.000Z",
      "end_date": "2018-04-23T23:59:59.999Z"
    },
    "minimum_mentions": 10,
    "external_product_ids": ["325","526","295"],
    "location": {
      "countries": ["US"],
      "states": ["CA","AZ","UT","NV"]
    },
    "product_groups": [],
    "product_collections": [],
    "minimum_score": 3,
    "topics": ["flavor"]
  },
  "paging": {
    "page": 0,
    "per_page": 10
  },
  "sorting": {
    "sorting_field": "yotpo_default_sorting",
    "sorting_direction": "ASC"
  }
}
A binary file was returned

You couldn't be authenticated

{
    "topics": [
        {
            "topic": "flavor",
            "sentiment_score": 44.334976,
            "industry_average": {
                "value": 51.5839958190918,
                "error": ""
            },
            "sentiment_change": {
                "value": -14.511178476695719,
                "error": ""
            },
            "positive_mentions": 131,
            "negative_mentions": 41,
            "neutral_mentions": 31,
            "products_count": 3,
            "opinions_count": 203,
            "included_keywords": []
        }
    ],
    "paging": {
        "page": 0,
        "page_count": 1,
        "per_page": 10,
        "total": 1
    }
}

Body Params

app_key
string
required

Your Yotpo app_key

start_date
date

Start date and time of your request. YYYY-MM-DDT00:00:00.000Z

end_date
date

End date and time of your request. YYYY-MM-DDT00:00:00.000Z

minimum_mentions
int32

The minimum number of times this topic was mentioned Should always be set to no less than 10 mentions Topics associated with a low number of opinions may result in a statistically insignificant sentiment score. Default: 0

external_product_ids
array of strings

The unique product IDs (supports multiple products). This parameter is also sometimes referred to as SKU or domain_key

countries
array of strings

Abbreviation of reviewer origin country (e.g US). Supports multiple countries. See List

states
array of strings

Abbreviation of reviewer origin state (e.g. CA, NY,). Supports multiple states. See List

product_group
array of strings

The name of the product group as defined in your Yotpo product catalog

product_collections
array of strings

The name of the product collection as defined in your Yotpo product catalog

minimum_score
int32

Filter by minimum star-rating. Must be an integer between 1 and 5(stars)

topics
array of strings

The name of the topic. Supports multiple topics.

page
int32

Page number

per_page
int32

Results per page. Default: 0

sorting_field
string

Accepted values: yotpo_default_sorting,sentiment_score,positive_mentions,negative_mentions,topic (alphabetically) Note: yotpo_default_sorting leverages a sorting logic which includes sentiment score, and the number of opinions to surface the most significant and polarized topics. This sorting parameter is equal to "most relevant" in the Insights dashboard.

sorting_direction
string

ASC or DESC (Case sensitive)

Headers

content type
string

application /JSON

authorization
string

Bearer <### Your uToken goes here ###> e.g. Bearer YTJZm0J7XaIcpzVN8HsWzhOcAzwdbzFJ1HDQJXSk

 
Suggest Edits

Reviews per Topic

Retrieves reviews on specific products according to topics. The response includes review data such as reviewer email, review id, title, content, star-rating, opinions, and can be filtered accordingly. For a full breakdown, see the Body Params list below.

 
posthttps://api.yotpo.com/insights/v1/topics/reviews
{
  "filter": {
    "app_key": "Your app_key here",
    "date_range": {
      "start_date": "2018-01-23T00:00:00.000Z",
      "end_date": "2018-04-23T23:59:59.999Z"
    },
    "minimum_mentions": 10,
    "external_product_ids": ["2055"],
    "location": {
      "countries": ["US"],
      "states": ["CA","FL"]
    },
    "product_groups": [],
    "product_collections": [],
    "topics": ["flavor","taste"],
    "exclude_topics": [],
    "sentiment_filter": {
      "sentiment_type": "POSITIVE",
      "sentiment_field": "sentiment"
    },
    "minimum_score": 3,
    "exclude_unpublished": true
  },
  "paging": {
    "page": 0,
    "per_page": 10
  },
  "sorting": {
    "sorting_direction": "DESC"
  }
}
A binary file was returned

You couldn't be authenticated

{
    "paging": {
        "page": 0,
        "page_count": 1,
        "per_page": 10,
        "total": 3
    },
    "reviews": [
        {
            "review_id": 55920385,
            "email": "reviewer1@gmail.com",
            "title": "My Favorite !!",
            "content": "I have a ton of mods. Big mods, little mods, expensive mods, cheap mods. This one is my favorite, Compact with smooth edges that ride in my pocket perfectly. Huge tank that lasts days. The JVIC coils rock !! I use the .6ohm for DTL hits and its perfect. Air daw is great even without adjustable flow control. Im not a cloud chaser but, this thing makes great clouds, Flavor is excellent. Battery lasts all day. All around a perfect mod for my vaping style. I bought 2 so i always have one ready to go. Protip: Thoroughly clean all parts for the unit where you fill it or it may leak. if its clean and dry. no problems.",
            "reviewed_at": 1521728328000,
            "score": 5,
            "opinions": [
                {
                    "opinion": "excellent",
                    "sentence": "im not a cloud chaser but, this thing makes great clouds, flavor is excellent."
                }
            ]
        },
        {
            "review_id": 56301440,
            "email": "reviewer2@gmail.com",
            "title": "Solid device..",
            "content": "If you're looking for an all in one, easy to use, cute little device.. This little guy is for you. Provides a great rip, and amazing flavor. I'm a mouth to lung girl. Hubby is a straight to lung guy. We both get what we need from this device. Enjoy!",
            "reviewed_at": 1522500878000,
            "score": 4,
            "opinions": [
                {
                    "opinion": "amazing flavor",
                    "sentence": "provides a great rip, and amazing flavor."
                }
            ]
        },
        {
            "review_id": 57397817,
            "email": "reviewer3@gmail.com",
            "title": "Great power and great flavor with some drawbacks",
            "content": "The tank on this little thing leaks like crazy, so I drip fluid everywhere I go. The coils (I use .6 coils) also seem to be pretty unreliable -- one will last 10 days, the next one starts tasting burnt after 2.",
            "reviewed_at": 1523501544000,
            "score": 3,
            "opinions": [
                {
                    "opinion": "great flavor with some drawbacks",
                    "sentence": "great power and great flavor with some drawbacks"
                }
            ]
        }
    ]
}

Body Params

app_key
string
required

Your Yotpo app_key

start_date
date

Start date and time of your request YYYY-MM-DDT00:00:00.000Z

end_date
date

End date and time of your request YYYY-MM-DDT00:00:00.000Z

minimum_mentions
int32

The minimum number of times this topic was mentioned. Should always be set to no less than 10 mentions. Default: 0

external_product_ids
array of strings

Product ID. Supports multiple products. This parameter is also sometimes referred to as SKU or domain_key

countries
array of strings

Abbreviation of reviewer origin country (e.g US). Supports multiple countries. See List

states
array of strings

Abbreviation of reviewer origin state (e.g. CA, NY,). See List

product_groups
array of strings

The name of the product group as defined in your Yotpo product catalog. Learn More

product_collections
array of strings

The name of the product collection as defined in your Yotpo product catalog Learn More

topics
array of strings
required

The name of the topic. Supports multiple topics.

exclude_topics
string

Use this param to filter out a certain topic from the response.

sentiment_type
string
required

The sentiment associated with a topic in a review. Possible values: POSITIVE,NEGATIVE, NEUTRAL Case sensitive, must be in uppercase.

sentiment_field
string
required

Should remain defined as sentiment

minimum_score
int32

Filter by minimum star-rating. Must be an integer between 1 and 5(stars)

exclude_unpublished
string

Set as true to exclude unpublished reviews from your response

page
int32

Page number

per_page
int32

Results per page. Default: 0

sorting_direction
string

ASC or DESC Case sensitive.

Headers

content type
string

application /JSON

authorization
string

Bearer <### Your uToken goes here ###> e.g. Bearer YTJZm0J7XaIcpzVN8HsWzhOcAzwdbzFJ1HDQJXSk

 
Suggest Edits

Products

Get the average star rating score, sentiment, sentiment change, organic reviews counts, and reviews sentiment distribution for specific products in your store.

 
posthttps://api.yotpo.com/insights/v1/products
{
    "filter": {
        "app_key": "YTJZm0J7XaIcpzVN8HsWzhOcAzwdbzFJ1HDQJXSk",
        "date_range": {
           "start_date": "2018-01-01T00:00:00.000Z",
           "end_date": "2018-07-09T00:00:00.000Z"
       },
       "location": {
       		"countries": [],
       		"states": []
       },
     "product_groups": [],
	   "product_collections": [],
	   "minimum_score": 4,
	   "exclude_unpublished": false,
	   "external_product_ids": []
    },
    "sorting": {
    	"sorting_field": "yotpo_default_sorting",
    	"sorting_direction": "ASC"
    }, 
    "paging": {
    	"page": 0,
    	"per_page": 3
    }
}
A binary file was returned

You couldn't be authenticated

{
    "products": [
        {
            "product_id": "19059407",
            "product_name": "Durif - Wrinkle Free",
            "average_star_rating": 4.8793969849246235,
            "sentiment_score": 77.88945,
            "sentiment_change": {
                "value": 6.815067070891658,
                "error": ""
            },
            "positive_reviews": 160,
            "negative_reviews": 5,
            "neutral_reviews": 34,
            "reviews_count": 199
        },
        {
            "product_id": "23930322",
            "product_name": "Bordeaux - Wrinkle Free",
            "average_star_rating": 4.7923497267759565,
            "sentiment_score": 69.39891,
            "sentiment_change": {
                "value": -5.20426749934947,
                "error": ""
            },
            "positive_reviews": 137,
            "negative_reviews": 10,
            "neutral_reviews": 36,
            "reviews_count": 183
        },
        {
            "product_id": "19059442",
            "product_name": "Sangiovese - Wrinkle Free",
            "average_star_rating": 4.867816091954023,
            "sentiment_score": 73.56322,
            "sentiment_change": {
                "value": 6.634084532536875,
                "error": ""
            },
            "positive_reviews": 136,
            "negative_reviews": 8,
            "neutral_reviews": 30,
            "reviews_count": 174
        }
    ],
    "paging": {
        "page": 0,
        "page_count": 302,
        "per_page": 3,
        "total": 904
    }
}

Body Params

app_key
string
required

Your Yotpo app_key

start_date
date

Start date and time of your request. YYYY-MM-DDT00:00:00.000Z

end_date
date

End date and time of your request. YYYY-MM-DDT00:00:00.000Z

countries
array of strings

Abbreviation of reviewer origin country (e.g US). Supports multiple countries. See List

states
array of strings

Abbreviation of reviewer origin state (e.g. CA, NY,). Supports multiple states. See List

product_groups
string

The name of the product groups as defined in your Yotpo product catalog

product_collections
string

The name of the product collection as defined in your Yotpo product catalog

minimum_score
int32

Filter by minimum star-rating. Must be an integer between 1 and 5(stars)

exclude_unpublished
boolean

Set as false to exclude unpublished reviews

external_product_ids
string

Product ID. Supports multiple products. This parameter is also sometimes referred to as SKU or domain_key

sorting_field
string

Possible values: yotpo_default_sorting, sentiment_score, average_star_rating, positive_reviews, negative_reviews

sorting_direction
string

ASC or DESC Case sensitive

page
int32

Page number

per_page
int32

Results per page. Default: 0

 

Note:

The reviews count returned in this endpoint only includes organic reviews. Reviews from grouped products are not counted in the reviews_count.

Suggest Edits

Reviews per Product

Get detailed organic reviews per product including top opinions and best sentences found within the review content.

 
posthttps://api.yotpo.com/insights/v1/products/reviews
{
    "filter": {
        "app_key": "YTJZm0J7XaIcpzVN8HsWzhOcAzwdbzFJ1HDQJXSk",
        "date_range": {
           "start_date": "2018-01-01T00:00:00.000Z",
           "end_date": "2018-07-09T00:00:00.000Z"
       },
       "sentiment_filter": {
       		"sentiment_type": "POSITIVE", 
       		"sentiment_field": "review_sentiment"
       },
       "location": {
       		"countries": [],
       		"states": []
       },
       "minimum_mentions": 10,
       "product_groups": [],
       "topics": [],
       "exclude_topics": [],
	   "product_collections": [],
	   "minimum_score": 3,
	   "exclude_unpublished": false,
	   "external_product_ids": []
    },
    "sorting": {
    	"sorting_direction": "ASC"
    }, 
    "paging": {
    	"page": 0,
    	"per_page": 3
    }
}
A binary file was returned

You couldn't be authenticated

{
    "paging": {
        "page": 0,
        "page_count": 43,
        "per_page": 3,
        "total": 129
    },
    "reviews": [
        {
            "review_id": 59353058,
            "email": "anne.taylor@email.com",
            "title": "",
            "content": "The size 8 (which was the exchange for the size 10) is a perfect fit. How can I return the size 10. Would you kindly provide an address?",
            "reviewed_at": 1526398665000,
            "score": 5,
            "opinions": [
                {
                    "opinion": "is a perfect fit",
                    "sentence": "the size 8 (which was the exchange for the size 10) is a perfect fit."
                }
            ]
        },
        {
            "review_id": 54890171,
            "email": "dennis@email.net",
            "title": "A disappointment",
            "content": "Well the shirt is of great quality, wash is nicely, and is wrinkle free, I was disappointed in the fact that the shirt tail is too long. It’s the right size and fits me fine everywhere, but as I said it’s not as short as the ones shown with the models.",
            "reviewed_at": 1519763233000,
            "score": 3,
            "opinions": [
                {
                    "opinion": "right size",
                    "sentence": "it’s the right size and fits me fine everywhere, but as i said it’s not as short as the ones shown with the models."
                }
            ]
        },
        {
            "review_id": 59357759,
            "email": "kathleenk12345@email.net",
            "title": "A good experience.",
            "content": "Great fresh color; good fabric weight for Spring/Summer. It&#x27;s always hard to gauge the right size on a first-time purchase, so had to exchange an XL for a L. Dealing with the return was very easy; got the new shirt in no time. A pleasure doing business here.",
            "reviewed_at": 1526409770000,
            "score": 5,
            "opinions": [
                {
                    "opinion": "right size on a first-time purchase",
                    "sentence": "it's always hard to gauge the right size on a first-time purchase, so had to exchange an xl for a l. dealing with the return was very easy; got the new shirt in no time."
                }
            ]
        }
    ]
}

Body Params

app_key
string
required

Your Yotpo app_key

start_date
date

Start date and time of your request. YYYY-MM-DDT00:00:00.000Z

end_date
date

End date and time of your request. YYYY-MM-DDT00:00:00.000Z

countries
array of strings

Abbreviation of reviewer origin country (e.g US). Supports multiple countries. See List

states
array of strings

Abbreviation of reviewer origin state (e.g. CA, NY,). Supports multiple states. See List

product_groups
string

The name of the product group as defined in your Yotpo product catalog

product_collections
string
required

The name of the product collection as defined in your Yotpo product catalog

minimum_score
int32

Filter by minimum star-rating. Must be an integer between 1 and 5(stars)

exclude_unpublished
boolean

Pass as true to include unpublished reviews in your response.

external_product_ids
string
required

The unique product IDs (supports multiple products). This parameter is also sometimes referred to as SKU or domain_key

sorting_direction
string

ASC or DESC Case sensitive.

page
int32

Page number

per_page
int32

Results per page. Default: 0

sentiment_type
string
required

The sentiment associated with a topic in a review. Possible values: POSITIVE,NEGATIVE, NEUTRAL Case sensitive, must be in uppercase.

sentiment_field
string
required

Default: review_sentiment

 

Note:

This endpoint only returns organic reviews. Reviews from grouped products are not counted or returned in the response.

Suggest Edits

Product Collections

Get the average star rating score, sentiment, sentiment change, and reviews sentiment distribution for specific product collections in your store.

 
posthttps://api.yotpo.com/insights/v1/topics/products
{
    "filter": {
        "app_key": "ddY0OFQeb180KIjdOe65vsRoSyC0DK2Mo50L3vhX",
        "date_range": {
           "start_date": "2018-01-11T00:00:00.000Z",
           "end_date": "2018-11-12T00:00:00.000Z"
       },
       "location": {
       		"countries": [],
       		"states": []
       },
     "product_groups": [],
	   "product_collections": ["Cool Watches"],
	   "minimum_score": 4,
	   "exclude_unpublished": false,
	   "external_product_ids": []
    },
    "sorting": {
    	"sorting_field": "yotpo_default_sorting",
    	"sorting_direction": "ASC"
    }, 
    "paging": {
    	"page": 0,
    	"per_page": 10
    }
}
A binary file was returned

You couldn't be authenticated

{
    "product_collections": [
        {
            "product_collections": "Cool Watches",
            "average_star_rating": 4.882443928847641,
            "sentiment_score": 85.60082,
            "sentiment_change": {
                "value": 0.29634076789936614,
                "error": ""
            },
            "positive_reviews": 3418,
            "negative_reviews": 77,
            "neutral_reviews": 406,
            "reviews_count": 3903,
            "products_in_collection": [
                {
                    "product_id": "1850285"
                },
                {
                    "product_id": "10228864"
                },
                {
                    "product_id": "24857299"
                },
                {
                    "product_id": "24857295"
                },
                {
                    "product_id": "35392356"
                },
                {
                    "product_id": "35787751"
                }
            ],
            "products_count": 6
        }
    ],
    "paging": {
        "page": 0,
        "page_count": 6,
        "per_page": 1,
        "total": 6
    }
}

Body Params

app_key
string
required

Your Yotpo app_key

start_date
date

Start date and time of your request. YYYY-MM-DDT00:00:00.000Z

end_date
date

End date and time of your request. YYYY-MM-DDT00:00:00.000Z

countries
array of strings

Abbreviation of reviewer origin country (e.g US). Supports multiple countries. See List

states
array of strings

Abbreviation of reviewer origin state (e.g. CA, NY,). Supports multiple states. See List

product_groups
string

The name of the product groups as defined in your Yotpo product catalog

product_collections
array of strings

The name of the product collection(s) as defined in your Yotpo product catalog

minimum_score
int32

Filter by minimum star-rating. Must be an integer between 1 and 5(stars)

exclude_unpublished
boolean

Set as false to exclude unpublished reviews

external_product_ids
string

Product ID. Supports multiple products. This parameter is also sometimes referred to as SKU or domain_key

sorting_field
string

Possible values: yotpo_default_sorting, sentiment_score, average_star_rating, positive_reviews, negative_reviews

sorting_direction
string

ASC or DESC Case sensitive. Note: Sorting direction does not apply to the yotpo_default_sorting sorting field.

page
int32

Page number

per_page
int32

Results per page. Default: 0

 
Suggest Edits

Introduction to Privacy API

Check for any existing user data in the Yotpo system.

 

Yotpo is all about providing consumers with a trustworthy shopping experience, and that extends to reviewers who share their thoughts, photos, and more. This is why our merchants have our commitment to transparency and GDPR compliance privacy protection to ensure that all merchants and their customers feel confident with every Yotpo interaction.

Data Processing Agreement

Learn more about our Processor and Controller compliance guidlines in Yotpo's Data Processing Agreement

In line with Yotpo's GDPR commitments, Yotpo offers two API endpoints which allow you to check for any existing account data in the Yotpo system.

Endpoint
Description

A synchronous request that checks for existing user data (true/false) in the Yotpo system.

An asynchronous request that retrieves existing user data in the Yotpo system. User data is sent as a JSON file to the account email address associated with the Yotpo account utoken.

Suggest Edits

Data Exists

A synchronous request that checks for existing account data (true/false) in the Yotpo system.

 
gethttps://api.yotpo.com/privacy/data/exists
curl --request GET \
  --url 'https://api.yotpo.com/privacy/data/exists?utoken=utoken&email=email'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.yotpo.com/privacy/data/exists',
  qs: 
   { utoken: 'utoken',
     email: 'email' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.yotpo.com/privacy/data/exists?utoken=utoken&email=email")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.yotpo.com/privacy/data/exists?utoken=utoken&email=email");

xhr.send(data);
import requests

url = "https://api.yotpo.com/privacy/data/exists"

querystring = {"utoken":"utoken","email":"email"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response": {
        "has_data": true
    }
}

Query Params

utoken
string
required

Your Yotpo account uToken generated using Yotpo Authentication

email
string
required

Check if data exists for the user associated with this email address.

 
Repsonse
Description

has_data: true

The user associated with the email queried has existing data in the Yotpo system associated with the account/utoken. To fetch the existing user data, use the User Data endpoint.

has_data: false

There is no existing data in the Yotpo System for the email queried in association with the account/utoken.

Suggest Edits

User Data

An asynchronous request that retrieves existing user data in the Yotpo system. User data is sent as a JSON file to the account email address associated with the Yotpo account utoken.

 
gethttps://api.yotpo.com/privacy/data
curl --request GET \
  --url 'https://api.yotpo.com/privacy/data?utoken=utoken&email=email'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.yotpo.com/privacy/data',
  qs: 
   { utoken: 'utoken',
     email: 'email' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.yotpo.com/privacy/data?utoken=utoken&email=email")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.yotpo.com/privacy/data?utoken=utoken&email=email");

xhr.send(data);
import requests

url = "https://api.yotpo.com/privacy/data"

querystring = {"utoken":"utoken","email":"email"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "status": {
        "code": 200,
        "message": "OK"
    }
}

Query Params

utoken
string
required

Your Yotpo account uToken generated using Yotpo Authentication

email
string
required

The email address of the user you want to retrieve data about.

 

To check for existing data about a specific customer, the merchant's utoken should be passed as the utoken and the customer's email address should be passed as the email

What happens next?

If you received a 200 OK response and the Data Exists endpoint returned a response attribute of "has_data": true, you'll receive the user data via an email sent to the email address associated with the account utoken. The email contains a link to a JSON file which includes any existing user data as shown in the response below:

Important

The link to the user data JSON file will expire 48 hours after the request is generated.

{
    reviews: [
      {
        id: 32,
        title: "This product changed my life",
        content: "I can't reccomend this product enough!",
        images: [ ],
        social_shares: [ ]
      }
],
    orders: [
     {
       id: 44,
       external_order_id: "1524729980",
       name: "Randy S.",
       email: "randy@example.com"
     }
],
    questions: [
     {
       id: 4,
       content: "Do you have this in white?"
     }
],
answers: [
     {
      id:8
      content: Yes! We have this product in every color!
     }
],
uploaded_on_site: [
    {
        id: "39712118",             
        image_url:     "https://ddcfq0gxiontw.cloudfront.net/Account/208659/39711849/original.png?1523443483"
    }
],
photo_imports: null
}

If you your response came back with a 200 | OK code and you haven't received an email from Yotpo within 24 hours, please contact Yotpo support and let us know.

Response Param
Description

Reviews

The reviews array includes data on reviews associated with the queried account.

id

The review ID

title

The review title

content

The review content

images

Any customer photos included with the review

social_shares

Social media network where the review was shared

Orders

The orders array includes data on orders associated with the queried account.

id

Yotpo's internal order ID

external_order_id

Your eCommerce platform order ID (e.g. Shopify order ID).

name

The customer's name

email

The customer's email address

Questions

The questions array includes data on questions asked by reviewers per the queried account.

id

The question ID

content

The question content

Answers

The answers array includes data on questions asked by reviewers per the queried account.

id

The answer ID

content

The answer content

Uploaded On Site

Photos uploaded by customers through your on-site UGC or Product gallery

id

The photo upload ID

image_url

The image URL of the uploaded image

Photo Imports

Photos imported to Yotpo via .csv upload.