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!

Documentation    
Suggest Edits

Read Me First

This page contains general information about Yotpo API calls.

 

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 page 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.

Error 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

UTF-8 Support

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

Finding Your API Key (Appkey)

  1. Log in to your Yotpo Admin page.
  2. Choose Settings under the User Settings menu (or Account Settings menu if you are using the new Yotpo Admin).
  3. Click Store Settings.
  4. Scroll down to API Credentials.

  5. Your App Key is the API key.

The "validate_data" parameter

When set to "true", this parameter provides additional data validation, prior to sending it to the API pipe for selected Purchases API calls.
It is recommended to set this to true, as it may catch errors that are otherwise missed.

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 http://omricohen.me.

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

API authentication basics

 
posthttps://api.yotpo.com/oauth/token
POST https://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:

Each utoken expires after 14 days after you generate it and will no longer be usable.

Each account can use up to 100 utokens simultaneously. Once this limit is reached, older utokens are deleted on a first-in first-out (FIFO) basis.

Suggest Edits

Retrieve the Reviews Payload in HTML

 

Definition

Body Parameters

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

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"
}

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

 

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

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.

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

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

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

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 Email Statistics (Deprecated)

This endpoint will be deprecated in favor of Email Analytics endpoints (beta) which include a wider array of metrics and email types as well as improved data capabilities.

 
gethttps://api.yotpo.com/apps/app_key/email_stats/since_date/to_date
GET https://api.yotpo.com/apps/### YOUR APP_KEY HERE ###/email_stats/2015-06-01/2015-06-29/?utoken=### YOUR UTOKEN HERE ###&categories=mail_after_service,map&aggregate=week
A binary file was returned

You couldn't be authenticated

{  
   "status":{  
      "code":200,
      "message":"OK"
   },
   "response":{  
      "mail_after_service":{  
         "2015-06-01,2015-06-07":{  
            "delivered":12,
            "unsubscribes":0,
            "invalid_email":0,
            "bounces":0,
            "repeat_unsubscribes":0,
            "unique_clicks":0,
            "blocked":0,
            "spam_drop":0,
            "repeat_bounces":1,
            "repeat_spamreports":0,
            "requests":13,
            "spamreports":0,
            "clicks":0,
            "opens":13,
            "unique_opens":6
         },
         "2015-06-08,2015-06-14":{  
            "delivered":5,
            "unsubscribes":0,
            "invalid_email":0,
            "bounces":1,
            "repeat_unsubscribes":0,
            "unique_clicks":0,
            "blocked":0,
            "spam_drop":0,
            "repeat_bounces":0,
            "repeat_spamreports":0,
            "requests":6,
            "spamreports":0,
            "clicks":0,
            "opens":5,
            "unique_opens":1
         },
         "2015-06-15,2015-06-21":{  
            "delivered":18,
            "unsubscribes":0,
            "invalid_email":0,
            "bounces":0,
            "repeat_unsubscribes":0,
            "unique_clicks":1,
            "blocked":0,
            "spam_drop":0,
            "repeat_bounces":0,
            "repeat_spamreports":0,
            "requests":18,
            "spamreports":0,
            "clicks":1,
            "opens":11,
            "unique_opens":9
         },
         "2015-06-22,2015-06-28":{  
            "delivered":6,
            "unsubscribes":0,
            "invalid_email":0,
            "bounces":0,
            "repeat_unsubscribes":0,
            "unique_clicks":0,
            "blocked":0,
            "spam_drop":0,
            "repeat_bounces":0,
            "repeat_spamreports":0,
            "requests":6,
            "spamreports":0,
            "clicks":0,
            "opens":5,
            "unique_opens":4
         },
         "2015-06-29,2015-06-29":{  
            "delivered":0,
            "unsubscribes":0,
            "invalid_email":0,
            "bounces":0,
            "repeat_unsubscribes":0,
            "unique_clicks":0,
            "blocked":0,
            "spam_drop":0,
            "repeat_bounces":0,
            "repeat_spamreports":0,
            "requests":0,
            "spamreports":0,
            "clicks":0,
            "opens":0,
            "unique_opens":0
         }
      },
      "map":{  
         "2015-06-01,2015-06-07":{  
            "delivered":19,
            "unsubscribes":0,
            "invalid_email":0,
            "bounces":0,
            "repeat_unsubscribes":0,
            "unique_clicks":3,
            "blocked":0,
            "spam_drop":0,
            "repeat_bounces":0,
            "repeat_spamreports":0,
            "requests":19,
            "spamreports":0,
            "clicks":6,
            "opens":31,
            "unique_opens":12
         },
         "2015-06-08,2015-06-14":{  
            "delivered":15,
            "unsubscribes":0,
            "invalid_email":0,
            "bounces":0,
            "repeat_unsubscribes":0,
            "unique_clicks":2,
            "blocked":0,
            "spam_drop":0,
            "repeat_bounces":0,
            "repeat_spamreports":0,
            "requests":15,
            "spamreports":0,
            "clicks":3,
            "opens":29,
            "unique_opens":11
         },
         "2015-06-15,2015-06-21":{  
            "delivered":21,
            "unsubscribes":0,
            "invalid_email":0,
            "bounces":0,
            "repeat_unsubscribes":0,
            "unique_clicks":0,
            "blocked":0,
            "spam_drop":0,
            "repeat_bounces":0,
            "repeat_spamreports":0,
            "requests":21,
            "spamreports":0,
            "clicks":0,
            "opens":50,
            "unique_opens":12
         },
         "2015-06-22,2015-06-28":{  
            "delivered":20,
            "unsubscribes":0,
            "invalid_email":0,
            "bounces":0,
            "repeat_unsubscribes":0,
            "unique_clicks":3,
            "blocked":0,
            "spam_drop":0,
            "repeat_bounces":0,
            "repeat_spamreports":0,
            "requests":20,
            "spamreports":0,
            "clicks":5,
            "opens":29,
            "unique_opens":12
         },
         "2015-06-29,2015-06-29":{  
            "delivered":4,
            "unsubscribes":0,
            "invalid_email":0,
            "bounces":0,
            "repeat_unsubscribes":0,
            "unique_clicks":0,
            "blocked":0,
            "spam_drop":0,
            "repeat_bounces":0,
            "repeat_spamreports":0,
            "requests":4,
            "spamreports":0,
            "clicks":0,
            "opens":0,
            "unique_opens":0
         }
      }
   }
}

Path Params

app_key
string
required

Your Yotpo account API key

since_date
string
required

Retrieve email statistics from this date

to_date
string
required

Retrieve email statistics until this date

Query Params

aggregate
string
required

Aggregate result dates. valid values are one of the following: ["day", "week", "month", "quarter", "year"]

categories
string
required

Each mail is defined by a single category. Should be comma separated.

utoken
string
required

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

 

Note:

This endpoint will be deprecated in favor of Email Analytics endpoints (beta) which include a wider array of metrics and email types as well as improved data capabilities.
Contact your Yotpo CSM or Yotpo Support to learn more.

Categories

These are the applicable categories:

  • "reminder"
  • "testimonials_request"
  • "anonymous_testimonials_request"
  • "mail_after_service"
  • "comment_request"
  • "comment_notification"
  • "site_reminder"
  • "mail_after_invoice"
  • "question_confirmation"
  • "answer_request_shop_owner"
  • "answer_request_shoppers"
  • "answer_notification_shop_owner"
  • "answer_notification_shoppers"
  • "resend_reminder"
  • "resend_custom_map"
  • "resend_map"
  • "custom_map"
  • "map"
Suggest Edits

Intro to Email Analytics (Beta)

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.

 

Important:

Email Analytics is currently in beta.
Please contact your Yotpo success manager or Yotpo support to learn more.

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_address

A specific email address.

  • e.g. joe@email.com

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.

order_id

The Order ID.

product_id

The ID of the product on your site.

sku

The stock-keeping unit (SKU).

review_type

The type of review.

  • e.g. Site or Product review.

coupon_code

The code included within the coupon email.

review_form

The type of review form.

  • e.g. In-Mail Form or Landing Page

platform

The platform or device on which the review was written.

  • e.g. Desktop, Mobile, or Tablet

Tip:

Click here to learn how to find the product ID per platform.

Suggest Edits

Email Analytics (Beta)

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

Important:

Email Analytics is currently in beta. Please contact your Yotpo success manager or Yotpo support to learn more.

Suggest Edits

Overview (Beta)

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 (Beta)

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. 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).

Important:

Email Analytics is currently in beta. Please contact your Yotpo success manager or Yotpo support to learn more.

Suggest Edits

Export Email Analytics (Beta)

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": "YOUR_UTOKEN",
    "email": "test@test.com"
}
A binary file was returned

You couldn't be authenticated

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

Body Params

email
string

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

 
Suggest Edits

Introduction to Products

 

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.

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

Search for Missed Products

Retrieve detailed missing products information

Retrieve promotes products

Retrieve All Products

Create products in the Yotpo system

Update products in the Yotpo system

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_productids parameter only supports alphanumeric (a...z, A...Z, 0...9), "" and "-" characters.

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"
     }
   ]
 }
}

Path Params

app_key
string
required

Your Yotpo account API key

 

Note:

  • "products_app_id" is the Product ID.
  • The products_appid only supports alphanumeric (a...z, A...Z, 0...9), "" and "-" characters.
    • "domain_key" is the SKU
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

Note:

This call does not return product tags and product specs.

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": "electronics,storage,USB",
      "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": "electronics,peripheral,USB",
      "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.

product
object
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.

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.

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

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": "electronics,storage,USB",
      "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_tag": "electronics,peripheral,USB",
      "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.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
required

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.

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 over-write existing data.

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

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:

When set to "true", the ""validate_data" provides additional data validation prior to sending it to the API pipe for selected Purchases API calls.
It is recommended to set this to true, as it may catch errors that are otherwise missed.

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_tag": "books"
  }
 }
}
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 e-commerce 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 en external reference for the Points and Rewards feature. See

products
object
products.product_id
object
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

The URL of the image of the product

products.product_id.description
string

The description of the product

products.product_id.price
string

The price of the product

products.product_id.product_tags
string

The tag you apply to a product in Custom Review Forms. This can only be a single string.

products.specs
object

The product specifications containing the spec values.

validate_data
boolean
required

A Boolean flag to indicate input validation in the response

order_date
date

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. 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. This parameter is mandatory if "validate_data" is set to true. It is not possible to send a MAP emails for orders older than six months.

 

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
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.orders.specs
object

The product specifications containing the spec values.

validate_data
boolean

A Boolean flag to indicate input validation in the response

order_date
date

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. This parameter is mandatory if "validate_data" is set to true. It is not possible to send a MAP emails for orders older than six months.

 

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
GET https://api.yotpo.com/apps/YOUR_APP_KEY/purchases?utoken=YOUR_UTOKEN
A binary file was returned

You couldn't be authenticated

{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response": {
        "purchases": [
            {
                "id": 1,
                "user_email": "neddyseagoon@goons.com",
                "user_name": "Neddy Seagoon",
                "order_id": "1760613",
                "product_sku": "5546",
                "product_name": "Gadget",
                "product_url": "http:// www.gkshops.com/Gadget.html",
                "order_date": "2014-04-29T00:00:00.000Z",
                "product_description": null,
                "created_at": "2014-10-26T10:20:33.432Z"
            },
            {
                "id": 2,
                "user_email": "efbc0b337ffacec6a469@staging.yotpo.com",
                "user_name": "Stephen Noh",
                "order_id": "4368501R1",
                "product_sku": "11245",
                "product_name": "Doohickey",
                "product_url": "http://www.gkshops.com/Doohickey.html",
                "order_date": "2014-04-29T00:00:00.000Z",
                "product_description": null,
                "created_at": "2014-10-26T10:20:33.657Z"
            }
            }
        ],
        "total_purchases": 18321
    }
}

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

count
string

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

since_date
date

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

 

Note:

This call will return a total of ten orders by default. To retrieve more than ten orders, utilize the 'count' query parameter to return the desired quantity of orders.

Note:

Yotpo recommends querying 200 orders per request.

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

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

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 the 'Create Answer' call.

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

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 HERE ###",
    "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 the 'Retrieve all Questions' endpoint.

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 the 'Retrieve all Questions' endpoint.

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_tag": "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.

 
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_tag": "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.

 

Note:

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

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

Create Reviews
This call will create reviews only as anonymous and will send out review verification emails to all the customers you imported reviews for.

Create 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": "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 imported reviews for.

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

Trusted Vendors

Trusted Vendors allows you to create verified buyers and verified reviewers. To enable this feature, please contact your Yotpo Customer Success Manager.

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"
}
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

The Trusted Vendors feature allows you to create verified buyers and verified reviewers.
The reviewer_type parameter refers to a verified_buyer or verified_reviewer and requires a signature.

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
GET: https://api.yotpo.com/v1/widget/{YOUR_APP_KEY}/products/{product_id}/reviews.json?page=1&per_page=1
GET: https://api.yotpo.com/v1/widget/{YOUR_APP_KEY}/products/{412790437}/reviews.json?star=5&sort[]=date&sort[]=votes_up
A binary file was returned

You couldn't be authenticated

{
    "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": "Size",
                        "form_id": 7144,
                        "value": 5,
                        "field_type": "Rating"
                    },
                    "--6691": {
                        "title": "Value for money",
                        "form_id": 7144,
                        "value": 4,
                        "field_type": "Rating"
                    },
                    "--6692": {
                        "title": "Quality",
                        "form_id": 7144,
                        "value": 5,
                        "field_type": "Rating"
                    },
                    "--6693": {
                        "title": "Fabric",
                        "form_id": 7144,
                        "value": 4,
                        "field_type": "Rating"
                    },
                    "--6694": {
                        "title": "Leather",
                        "form_id": 7144,
                        "value": 5,
                        "field_type": "Rating"
                    }
                },
                "product_id": 25066514,
                "user": {
                    "user_id": 14229046,
                    "display_name": "Fred P.",
                    "social_image": null,
                    "user_type": "User",
                    "is_social_connected": 0
                }
            }
        ]
    }
}
{  
  "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
        }
     ]
  }
}

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
array of strings

Options for sorting the results (date, votes_up, votes_down, time, rating, reviewer_type)

direction
string

Sort order (Ascending or Descending)

 

Note:

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

Suggest Edits

Retrieve Reviews for a User Using External User Reference ID

 
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"

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": {
            "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

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

user_reference
string

External User ID for which to return the reviews.

 
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?utoken=your_utoken&count=5&page=5
curl --request GET \
  --url 'https://api.yotpo.com/v1/apps/app_key/bottom_lines?count=5&page=5&utoken=your_utoken'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.yotpo.com/v1/apps/app_key/bottom_lines',
  qs: { count: '5', page: '5', utoken: 'your_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/v1/apps/app_key/bottom_lines?count=5&page=5&utoken=your_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/v1/apps/app_key/bottom_lines?count=5&page=5&utoken=your_utoken");

xhr.send(data);
import requests

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

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

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_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

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_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

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

Introduction to Users

 

What are Users?

A Yotpo user is an e-commerce store owner who has opened a Yotpo B2B 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

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 my.yotpo.com

 
gethttps://api.yotpo.com/users/b2blogin.json?app_key=app_key&secret=secret
GET https://api.yotpo.com/users/b2blogin.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://my.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

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

Recent 5-Star Reviews

Retrieve the most recent 5-star reviews for a specific account.
This endpoint will return the three most recent 5-star reviews (including unpublished reviews) 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

 

Note:

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

Note:

In order to use this request, the Recent 5-Star Reviews feature must be enabled.

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 products to a product group (update)

 
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

Get All Images

Use this endpoint to retrieve all images generated from product reviews and/or Instagram.

 
gethttps://api.yotpo.com/v1/widget/app_key/images/all.json?source=instagram&per_page=1&offset[instagram]=3
curl --request GET \
  --url 'https://api.yotpo.com/v1/widget/app_key/images/all.json?offset%5Binstagram%5D=3&per_page=1&source=instagram'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.yotpo.com/v1/widget/app_key/images/all.json',
  qs: { 'offset[instagram]': '3', per_page: '1', source: 'instagram' } };

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/images/all.json?offset%5Binstagram%5D=3&per_page=1&source=instagram")

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/images/all.json?offset%5Binstagram%5D=3&per_page=1&source=instagram");

xhr.send(data);
import requests

url = "https://api.yotpo.com/v1/widget/app_key/images/all.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": 1,
            "per_page": 1,
            "total": 0
        },
        "images": [
            {
                "source": "instagram",
                "image_id": "58d24150ea0f98f594334eb1",
                "low_resolution_image_url": "//scontent.cdninstagram.com/t51.2885-15/s320x320/e35/17332418_615002144320209_904132967386024512_n.jpg",
                "original_image_url": "//scontent.cdninstagram.com/t51.2885-15/s640x640/sh0.08/e35/17332418_615232014420009_932967386041024512_n.jpg",
                "image_url": "//scontent.cdninstagram.com/t51.2885-15/s150x150/e35/32173418_615201443220009_932967386041024512_n.jpg",
                "external_media_id": "1474497626392408531_609901681",
                "tagged_products": [
                    {
                        "id": 14119552,
                        "name": "125W Light bulb 16\" Dimmable LED - 16,000 Lumens - 5000K - Black",
                        "domain_key": "39513",
                        "product_link": "https://yotpo.com/go/iZTTF3so",
                        "product_url": "https://www.yourstore.com/yourstore-16-led-bulb-125w.html",
                        "image_url": "https://ddcfq0gxiontw.cloudfront.net/Product/17242296/10475026/square.jpg?1490911065",
                        "score": null,
                        "reviews_count": null
                    }
                ],
                "post": {
                    "profile_picture": "https://scontent.cdninstagram.com/t51.2885-19/s150x150/12656800_214919370562197_1274340786_a.jpg",
                    "username": "yourusername",
                    "location_name": "",
                    "created_time": "2017-03-22T17:39:33.000+00:00",
                    "hashtags": [
                        "electricians",
                        "electrician",
                        "energyefficiency",
                        "electriciansofinstagram",
                        "industriallighting",
                        "contractors",
                        "contractor",
                        "energyefficient",
                        "contractorsofinstagram",
                        "ledlighting",
                        "ledhighbay",
                        "warehouselighting",
                        "contractorlife",
                        "ledupgrade",
                        "electricianlife",
                        "commerciallighting"
                    ],
                    "content": "Wow! This lightbulb is amazing!",
                    "votes_up": 1,
                    "votes_down": 0
                }
            }
        ]
    }
}

Path Params

app_key
string
required

Your Yotpo account API key

Query Params

source
string

The source of your images. Can be either source=instagram or source=yotpo_reviews.

offset[review]
string

The number of images to skip before counting the per_page param. Similar to passing a page number

offset[instagram]
string

The number of images to skip before counting the per_page param. Similar to passing a page number

per_page
int32

The number of images to return per page.

 

Note:

The offset parameter refers to how many images to pass over before counting the per_page parameter, similar to passing a page number.

Suggest Edits

Get Product Images

Use this endpoint to retrieve images for specific products by product ID.

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

var options = { method: 'GET',
  url: 'https://api.yotpo.comhttp//api.yotpo.com/v1/widget/app_key/products/product_id/images.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.comhttp//api.yotpo.com/v1/widget/app_key/products/product_id/images.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.comhttp//api.yotpo.com/v1/widget/app_key/products/product_id/images.json");

xhr.send(data);
import requests

url = "https://api.yotpo.comhttp//api.yotpo.com/v1/widget/app_key/products/product_id/images.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": 1,
            "per_page": 10,
            "total": 0
        },
        "images": [
            {
                "source": "instagram",
                "image_id": "59a52791932a379351e9b5d1",
                "low_resolution_image_url": "//scontent.cdninstagram.com/t51.2885-15/e35/p320x320/21041179_7177531325734998_3359271025178050560_n.jpg",
                "original_image_url": "//scontent.cdninstagram.com/t51.2885-15/sh0.08/e35/p640x640/21041179_1325737534971798_3359271025178050560_n.jpg",
                "image_url": "//scontent.cdninstagram.com/t51.8258-15/s150x150/e35/c0.135.1080.1080/21041179_1325717753734998_3359271025178050560_n.jpg",
                "external_media_id": "1583407879358538587_4811622590",
                "tagged_products": [
                    {
                        "id": 11,
                        "name": "Product Name",
                        "domain_key": "6354389315",
                        "product_link": "https://yotpo.com/go/vcGXGQcG",
                        "image_url": "//s3.amazonaws.com/yotpo-images-test/Product/11/9/square.jpg?4051503812",
                        "score": null,
                        "reviews_count": null
                    }
                ],
                "post": {
                    "profile_picture": "https://scontent.cdninstagram.com/t51.2885-19/s150x150/19733233_1289851844944438_8279179302814089216_a.jpg",
                    "username": "MyUsername2017",
                    "location_name": "",
                    "created_time": "2017-08-24T15:20:40.000+00:00",
                    "hashtags": [],
                    "content": "The review content",
                    "votes_up": 0,
                    "votes_down": 0
                },
                "product": {
                    "id": 11,
                    "domain_key": "5489363315",
                    "name": "Product Name",
                    "product_link": "https://yotpo.com/go/vcGXGQcG",
                    "image_url": "//s3.amazonaws.com/yotpo-images-test/Product/11/9/square.jpg?1503518402",
                    "social_links": {
                        "facebook": "https://yotpo.com/go/4tav498I",
                        "twitter": "https://yotpo.com/go/qR8yXywN",
                        "linkedin": "https://yotpo.com/go/e7uhiffc",
                        "google_oauth2": "https://yotpo.com/go/kxdf2JxG"
                    }
                }
            },
            {
                "source": "review",
                "image_id": 122,
                "review_id": 189,
                "low_resolution_image_url": "//s3.amazonaws.com/yotpo-images-test/Review/189/122/medium_square.jpg?1471435913",
                "image_url": "//s3.amazonaws.com/yotpo-images-test/Review/189/122/square.jpg?5911473143",
                "original_image_url": "//s3.amazonaws.com/yotpo-images-test/Review/189/122/original.jpg?1144735913",
                "review": {
                    "id": 189,
                    "title": "The review title",
                    "content": "The review content",
                    "score": 4,
                    "created_at": "2016-09-11T10:52:24Z",
                    "verified_buyer": 0,
                    "votes_up": 0,
                    "votes_down": 0,
                    "product_id": 97,
                    "user": {
                        "display_name": "aa29",
                        "user_type": "AnonymousUser",
                        "social_image": "//ddcfqxio0gntw.cloudfront.net/images/anonymous_user.png",
                        "is_social_connected": false
                    }
                },
                "product": {
                    "id": 97,
                    "domain_key": "8404555971",
                    "name": "Product name#$@&quot;@#%$yes",
                    "product_link": "https://yotpo.com/go/rsrSqVrr",
                    "image_url": "//s3.amazonaws.com/yotpo-images-test/Product/97/124/square.jpg?1500493842",
                    "social_links": {
                        "facebook": "https://yotpo.com/go/yEh7Oivk",
                        "twitter": "https://yotpo.com/go/3JIjyCh8",
                        "linkedin": "https://yotpo.com/go/cWnF29Su",
                        "google_oauth2": "https://yotpo.com/go/3By4JSJT"
                    }
                }
            },
}
{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response": {
        "pagination": {
            "page": 1,
            "per_page": 1,
            "total": 0
        },
        "images": [
            {
                "source": "instagram",
                "image_id": "57c3bc75d73d1603e44598e2",
                "low_resolution_image_url": "//scontent.cdninstagram.com/t51.2885-15/s320x320/e35/13099014_1714998308772566_909367957_n.jpg",
                "original_image_url": "//scontent.cdninstagram.com/t51.2885-15/s640x640/sh0.08/e35/13099014_1714998308772566_909367957_n.jpg",
                "image_url": "//scontent.cdninstagram.com/t51.2885-15/s150x150/e35/13099014_1714998308772566_909367957_n.jpg",
                "external_media_id": "1240060964243464549_231350983",
                "tagged_products": [
                    {
                        "id": 7509493,
                        "name": "Spin for Perfect Skin - Complete Face & Body Cleansing System",
                        "domain_key": "1246317892",
                        "product_link": "https://yotpo.com/go/vmwyTVC2",
                        "image_url": "https://ddcfq0gxiontw.cloudfront.net/Product/7606933/7264825/square.jpg?1510979613",
                        "score": null,
                        "reviews_count": null
                    }
                ],
                "post": {
                    "profile_picture": "https://scontent.cdninstagram.com/t51.2885-19/s150x150/19986175_134336503818264_2220652015069954048_a.jpg",
                    "username": "caseyleighwiegand",
                    "location_name": "",
                    "created_time": "2016-04-30T20:06:48.000+00:00",
                    "hashtags": [
                        "subjectlight",
                        "vsco",
                        "vanityplanetstore",
                        "vscocam",
                        "theeverydayproject",
                        "everydaymoments"
                    ],
                    "content": "Awhile back I shared some of my skincare routines and my love for The Spin for Perfect Skin :)! Im here to share again just in time for Mother's Day because it would be an amazing gift for someone you love or for yourself!!! A total steal at $30!! It comes with 4 different attachments and it comes in 6 colors! It will cleanse, exfoliate and eliminate dirt and oil trapped in your pores from your head to your toes. I also love that you can use whatever your favorite face wash soap is with it.\n\nNow that it has been months of me using it I love it more than ever- between good face wash, essential oils and this incredible brush....my face feels better than ever,  it truly has a glow to it!\n\nI have the coupon code link from @vanityplanetstore live on my blog! Link in profile ❤️❤️❤️",
                    "votes_up": 0,
                    "votes_down": 0
                },
                "product": {
                    "id": 7509493,
                    "domain_key": "1246317892",
                    "name": "Spin for Perfect Skin - Complete Face &amp; Body Cleansing System",
                    "product_link": "https://yotpo.com/go/u5o1SKU4",
                    "image_url": null,
                    "social_links": {
                        "facebook": "https://yotpo.com/go/b1ctCIF2",
                        "twitter": "https://yotpo.com/go/qoPZGiy9",
                        "linkedin": "https://yotpo.com/go/AuhECwov",
                        "google_oauth2": "https://yotpo.com/go/q8QT4tTl"
                    }
                }
            }
        ],
        "grouping_data": {}
    }
}

Path Params

app_key
string
required

Your Yotpo account API key

product_id
string
required

The unique identifier of the product. The product ID can be found using the Get All Images endpoint.

Query Params

per_page
string

The number of images to return per page.

offset[reviews]
string

The number of images to skip before counting the per_page param. Similar to passing a page number

offset[instagram]
string

The number of images to skip before counting the per_page param. Similar to passing a page number

 

Note:

The offset parameter refers to how many images to pass over before counting the per_page parameter, similar to passing a page number.