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 HERE ###/account_platform
-------------------------------------------------------------------------

{
    "account_platform": {
        "shop_domain": "http://omricohen.me",
        "platform_type_id": "4"
            },
    "utoken": "w8W3EdIzysj643fWxUlONFqWoR783IG2Uj21mb9J"
} 
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://omricohen.me",
      "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 for instructions on generating a 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": "DUGKea0thVDL2muWzMAd7mYlkni46cJWhiX9tGTF",
  "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

 
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 HERE ###/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

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=utoken
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 for instructions on generating a utoken.

 
Suggest Edits

Retrieve Dynamic Coupon Code Statistics

 
gethttps://api.yotpo.com/apps/app_key/coupons/unique/stats?utoken=utoken
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 for instructions on generating a 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 HERE ###/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 for instructions on generating a 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

 
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 ###&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

 

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

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=:utoken
POST https://api.yotpo.com/apps/### YOUR APP_KEY HERE ###/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 HERE ###/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:33Z",
            "order_id":"346522189",
            "purchase_date":"2014-10-23T07:34:37Z",
            "mail_delivery_date":null
         },
         {  
            "id":2,
            "product_name":"Product12",
            "product_sku":"293116261",
            "user_email":"efef@efef.com",
            "user_display_name":"Gregory",
            "missed_product_date":"2015-07-02T07:48:49Z",
            "order_id":"346522189",
            "purchase_date":"2014-10-23T07:34:37Z",
            "mail_delivery_date":"2015-07-06T07:14:33Z"
         },
         {  
            "id":5,
            "product_name":"Product8",
            "product_sku":"293068145",
            "user_email":"zxc@asc.com",
            "user_display_name":"Omri",
            "missed_product_date":"2015-07-04T07:49:24Z",
            "order_id":"346522145",
            "purchase_date":"2014-10-23T07:33:38Z",
            "mail_delivery_date":"2015-07-06T07:14:37Z"
         },
         {  
            "id":6,
            "product_name":"Product2",
            "product_sku":"289724065",
            "user_email":"cas@acccs.com",
            "user_display_name":"Tomer",
            "missed_product_date":"2015-06-12T07:49:33Z",
            "order_id":"346521461",
            "purchase_date":"2014-10-23T07:19:21Z",
            "mail_delivery_date":null
         }
      ]
   }
}

Path Params

app_key
string
required

Your Yotpo account API key

Query Params

start
int32

Result offset

size
int32

Result size

utoken
string
required

Your Yotpo account access token

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": "IvvWEwGNnw7HV43aCuUBNvcbKXtujVJo7w9irI2H",
       "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": "IvvWEwGNnw7HV43aCuUBNvcbKXtujVJo7w9irI2H",
       "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

Retrieves a list of all of your store's products.

 
gethttps://api.yotpo.com/v1/apps/app_key/products
GET  https://api.yotpo.com/v1/apps/### YOUR APP_KEY HERE ###/products?utoken=### YOUR UTOKEN HERE ###
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:49Z",
updated_at: "2017-05-22T08:13:43Z",
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 for instructions on generating a utoken.

 

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 HERE ###/products/mass_create
------------------------------------------------------------------------------

{
  "utoken": "### YOUR UTOKEN HERE ###",
  "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 for instructions on generating a 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 for the product you use in custom forms. Can be a single string, multiple strings or an array of strings.

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 HERE ###/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_tags": "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 for instructions on generating a 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 for the product you use in custom forms. Can be a single string, multiple strings or an array of strings.

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.
If you enter a blank description, it will erase the 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 HERE ###/purchases

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

You couldn't be authenticated

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

Body Params

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 for the product you use in custom forms.

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.

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication for instructions on generating a utoken.

 

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"

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_tags parameter can be:

  • A single string,
  • Multiple strings, or
  • An array of strings

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 HERE ###/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-ab57-467d-a555-a60a7c2d8a73"
}

Body Params

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
required

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

The price of the product

products.orders.product_id.product_tags
string

The tag for the product you use in custom forms.

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.

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication for instructions on generating a utoken.

 

product id

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.

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.

SPACES are prohibited

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_tags parameter can be:

  • A single string,
  • Multiple strings, or
  • An array of strings
Suggest Edits

Retrieve Orders from the Yotpo System

 
gethttps://api.yotpo.com/apps/app_key/purchases?utoken=utoken
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:00Z",
                "product_description": null,
                "created_at": "2014-10-26T10:20:33Z"
            },
            {
                "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:00Z",
                "product_description": null,
                "created_at": "2014-10-26T10:20:33Z"
            }
            }
        ],
        "total_purchases": 18321
    }
}

Path Params

app_key
string
required

Your Yotpo account API key

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication for instructions on generating a utoken.

Query Params

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 HERE ###/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 for instructions on generating a utoken.

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 HERE ###/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:01Z",
                "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:58Z"
                    }
                ]
            }
        ]
    }
}
{
    "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.

 
gethttps://api.yotpo.com/apps/:app-key/questions.json
https://api.yotpo.com/apps/### YOUR APP KEY HERE ###/questions.json?utoken=### YOUR UTOKEN HERE ###
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:14Z",
            "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: 7,
new_questions: 0,
questions: [
{
id: 659964,
content: "Do you ship internationally?",
asker: {
id: 11208349,
display_name: "John Doe",
slug: "John-Doe--9114768587237501804",
social_image: "https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png",
is_social_connected: false,
bio: null,
score: 0,
badges: [ ]
},
user_type: "User",
created_at: "2017-05-14T09:08:51Z",
archived: false,
published: true,
allow_send: true,
answers: [
{
id: 1357888,
approved: true,
public: true,
content: "Yes! We support international shipping",
store_owner_comment: true,
answerer: {
id: 11208349,
display_name: null,
slug: "John-Doe--9114768587237501804",
social_image: "http://ddcfq0gxiontw.cloudfront.net/App/211430/17491234/thumb.?1498661027",
is_social_connected: false,
bio: null,
score: 0,
badges: [ ]
},
votes_up: 0,
votes_down: 0,
created_at: "2017-05-14T09:09:46Z"
}
],
products_app: {
product: {
name: "http://myonlinestore.myshopify.com",
images: [ ]
},
product_url: "http://myonlinestore.myshopify.com"
}
},

Path Params

app_key
string
required

Your Yotpo account API key

Query Params

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication for instructions on generating a utoken.

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.

 

Note

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.

Suggest Edits

Create an Answer to a Question

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

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

{
   "utoken": "### YOUR UTOKEN ###",
    "answer": {
        "content": "This is my public answer to your 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 my public answer to your 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 for instructions on generating a utoken.

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_tags": "t-shirts"
} 
A binary file was returned

You couldn't be authenticated

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

Path Params

questions
string
required

Query Params

utoken
string
required

Your Yotpo account access token

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 for the product you use in custom forms.

 
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=##utoken here##
-----------------------------------------------------------


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

You couldn't be authenticated

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

Body Params

review_content
string
required

The question.the customer asks

display_name
string
required

The customer's name.

email
string
required

The customer's email

appkey
string
required

Your Yotpo account API key

sku
string
required

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

product_title
string
required

The name of the product

product_url
string
required

The URL of the product

product_description
string

The description of the product

product_image_url
string

The URL of the image of the product

prevent_duplicate_review
boolean

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

product_tags
string

The tag for the product you use in custom forms.

 

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 ###",
 "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
}
A binary file was returned

You couldn't be authenticated

{
    "code": 200,
    "message": "ok",
    "image_upload_token": "0812733ce40436bfeee222987e5b26d725feffe8"
}
{
    "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)

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

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

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:

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

Note:

If you use the signature parameter, time_stamp and reviewer_type are mandatory.

Note:

To create a site review, use "yotpo_site_reviews" for the sku.

Note:

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

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 ###",
  "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":"F93GJPbthaNLVImLB0zbSk9PoAT6hZForCnkIWiE",
  "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'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

Retrieve Reviews for a User Using External User Reference ID

 
gethttps://api.yotpo.com/products/app_key/yotpo_global_reviews/reviews.json
GET https://api.yotpo.com/products/### YOUR APP_KEY ###/yotpo_global_reviews/reviews?user_reference=1234
A binary file was returned

You couldn't be authenticated

{  
   "status":{  
      "code":200,
      "message":"OK"
   },
   "response":{  
      "reviews":[  
         {  
            "id":16,
            "content":"Really recommend it for anyone who looks for comfort and quality! ",
            "title":"Super comfortable!",
            "score":4,
            "user":{  
               "id":52,
               "display_name":"Tomer Tagrin",
               "slug":"tomer-tagrin",
               "social_image":"https://graph.facebook.com/123456789/picture?type=large",
               "is_social_connected":true,
               "bio":"",
               "score":106,
               "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"
                  },
                  {  
                     "id":8,
                     "name":"Networked",
                     "description":"It's the Hoffman-Dorsey-Crowley-Zuckerberg of badges. Having this badge proves you have many friends and the potential to be super-influencer.",
                     "image_100":"http://s3.amazonaws.com/yotpo-static-images/badges/100/8.png",
                     "image_300":"http://s3.amazonaws.com/yotpo-static-images/badges/300/8.png"
                  }                 
               ]
            },
            "user_type":"User",
            "users":[  

            ],
            "products":[  
               {  
                  "Location_idx":[  
                     0,
                     0
                  ],
                  "Product":{  
                     "product_url":"http://www.gkshops.com/products/Tardis",
                     "id":5,
                     "name":"Tardis 
                            "slug":"Tardis",
                     "shorten_url":"https://yotpo.com/go/7hdMxEry",
                     "images":[  
                        {  
                           "id":4,
                           "image_url":"http://d2zookpajyck3d.cloudfront.net/Product/5/4/square.jpg%253F100088?1327592746"
                        }
                     ],
                     "social_network_links":{  
                        "facebook":"https://yotpo.com/go/1NQF4zQe",
                        "twitter":"https://yotpo.com/go/wxVm9Ksg",
                        "google_oauth2":"https://yotpo.com/go/uAcc3LNI"
                     },
                     "facebook_testemonials_page_product_url":"https://yotpo.com/go/cUmIrGdf"
                  }
               }
            ],
            "votes_up":1,
            "votes_down":0,
            "user_vote":0,
            "created_at":"2011-11-22T00:00:00Z",
            "deleted":false,
            "new":false,
            "verified_buyer":false,
            "archived":false,
            "social_pushed":false,
            "facebook_pushed":0,
            "twitter_pushed":0,
            "account":{  
               "id":38,
               "domain":"http://www.gkshops.com",
               "comments_display_name":null
            },
            "products_apps":[  
               {  
                  "id":4,
                  "product_url":"http://www.gkshops.com/products/Tardis",
                  "domain_key":"2365402",
                  "product":{  
                     "id":5,
                     "name":"Tardis"
                  }
               }
            ]
         }
      ],
      "total_reviews":1
   }
}

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 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
GET https://api.yotpo.com/apps/### YOUR APP_KEY ###/bottom_lines?utoken=### YOUR UTOKEN ###&callback={pjson_callback}
A binary file was returned

You couldn't be authenticated

{
    "response": {
        "bottomlines": [
            {
                "domain_key": "4321",
                "product_score": "4.88",
                "total_reviews": 8
            },
            {
                "domain_key": "12346",
                "product_score": "5.0",
                "total_reviews": 2
            },
            {
                "domain_key": "12347",
                "product_score": "5.0",
                "total_reviews": 2
            }
        ],
        "page": "1",
        "per_page": "3"
    },
    "status": {
        "code": 200,
        "message": "OK"
    }
}

Path Params

app_key
string
required

Your Yotpo account API key

Query Params

count
int32
required

The amount of bottomlines to retrive, limited to 100

page
int32
required

page number

callback
string

jsonp call back function

since_date
string

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

since_id
string

Minimum ID of the returned reviews

 
Suggest Edits

Retrieve All Reviews

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

You couldn't be authenticated

{
    "reviews": [
        {
            "id": 4362064,
            "title": "Good",
            "content": "Very easy to use",
            "score": 4,
            "votes_up": 2,
            "votes_down": 1,
            "created_at": "2008-03-07T00:00:00Z",
            "sku": "197053",
            "name": "Gregory K",
            "email": "GREGORY@YOTPO.COM",
            "reviewer_type": "verified_buyer",
            "deleted": false
            "user_reference": null
        },
        {
            "id": 4362065,
            "title": "Brother LC61BK black ink cartridges",
            "content": "Been using Brother product for 10 years. Long lasting. Very happy and when you have a coupon it helps off set the cost. They're not cheap.",
            "score": 5,
            "votes_up": 0,
            "votes_down": 0,
            "created_at": "2015-01-22T00:00:00Z",
            "sku": "739213",
            "name": "Alex",
            "email": "AlexBrown@yotpo.net",
            "reviewer_type": "verified_buyer",
            "deleted": false
            "user_reference":"358646412"
        },
        {
            "id": 4362066,
            "title": "Good Product",
            "content": "Good product",
            "score": 4,
            "votes_up": 0,
            "votes_down": 0,
            "created_at": "2013-06-07T00:00:00Z",
            "sku": "959063",
            "name": "Technical Writer",
            "email": "tech_write@yotpo.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 for instructions on generating a utoken.

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 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 ###/1012/bottomline?callback={pjson_callback}
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

callback
string
required

jsonp call back function

 
Suggest Edits

Retrieve Reviews for a Product

 
gethttps://api.yotpo.com/v1/widget/app_key/products/product_id/reviews.json
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":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_tags":[  

     ],
     "reviews":[  
        {  
           "id":110,
           "score":5,
           "votes_up":1,
           "votes_down":0,
           "content":"Great mug",
           "title":"Perfect",
           "created_at":"2016-06-16T12:16:05Z",
           "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:25Z",
          "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 (ASC or DESC)

 

Should put comment inside review, not same level as current

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

     ],
     "reviews":[  
        {  
           "id":110,
           "score":5,
           "votes_up":1,
           "votes_down":0,
           "content":"Great mug",
           "title":"Perfect",
           "created_at":"2016-06-16T12:16:05Z",
           "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:25Z",
                "comments_avatar": null
             }
        }
     ]
  }
}

Note:

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

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",
                "created_at": "2013-03-06T23:08:21Z",
                "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'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:24Z",
                "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",
                "created_at": "2013-03-11T18:45:44Z",
                "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

Vote on Reviews

 
gethttps://api.yotpo.com/reviews/review_id/vote/vote_type
GET 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

of 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 a Review by Review ID

 
gethttps://api.yotpo.com/reviews/review_id
GET http://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,
         created_at:"2014-03-18T09:27:45Z",
         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

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 HERE ###/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.

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication for instructions on generating a utoken.

 

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 HERE ###/unsubscribers/mass_create
-----------------------------------------------------------------------------------

{
  "utoken": "### YOUR UTOKEN ###",
  "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 for instructions on generating a utoken.

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 HERE ###/unsubscribers/mass_delete
-----------------------------------------------------------------------------------

{
  "utoken": "### YOUR UTOKEN ###",
  "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

our Yotpo account access token. See Yotpo Authentication for instructions on generating a utoken.

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

utoken
string
required

Your Yotpo account access token. See Yotpo Authentication for instructions on generating a utoken.

Query Params

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": "Omri Cohen",
            "score": 0,
            "display_name": "Omri Cohen ",
            "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 HERE ###&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= a3lmMnC3u4SNmz0ZcHf3lODeIYM9LEQwtTWXRdDP”
  }
}

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": "omri@company.com",
        "display_name": "Omri Cohen",
        "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" : "NkLHMUYXnkIRrb3UUVpCtI0EIHconaoFEMzgpYXt",
    "app_key" :"a3lmMnC3u4SNmz0ZcHf3lODeIYM9LEQwtTWXRdDP",
    "secret" :"NumuadvlCGOTwnCCvY5BRAhGib1LTCFptYxfvebm"
  }
}
}

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

Get the most recent 5-star review for an account. This will return three most recent 5-star reviews.
You can get it in a JOSN 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:01Z",
		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:01Z",
		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:01Z",
		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:

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 HERE ###/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

group_name
string

The name of the product group

utoken
string

Your account utoken

 
Suggest Edits

Retrieve product groups for account

 
gethttps://api.yotpo.com/v1/apps/app_key/products_groups?utoken=### YOUR UTOKEN HERE ###
curl --request GET \
  --url 'https://api.yotpo.com/v1/apps/app_key/products_groups?utoken=###%20YOUR%20UTOKEN%20HERE%20###'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.yotpo.com/v1/apps/app_key/products_groups###%20YOUR%20UTOKEN%20HERE%20###',
  qs: { 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/products_groups?utoken=###%20YOUR%20UTOKEN%20HERE%20###")

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/products_groups?utoken=###%20YOUR%20UTOKEN%20HERE%20###");

xhr.send(data);
import requests

url = "https://api.yotpo.com/v1/apps/app_key/products_groups###%20YOUR%20UTOKEN%20HERE%20###"

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

print(response.text)
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

 
Suggest Edits

Retrieve details for a specific product group

 
gethttps://api.yotpo.com/v1/apps/app_key/products_groups/group_name?utoken=### YOUR UTOKEN HERE ###
curl --request GET \
  --url 'https://api.yotpo.com/v1/apps/app_key/products_groups/group_name?utoken=###%20YOUR%20UTOKEN%20HERE%20###'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.yotpo.com/v1/apps/app_key/products_groups/group_name###%20YOUR%20UTOKEN%20HERE%20###',
  qs: { 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/products_groups/group_name?utoken=###%20YOUR%20UTOKEN%20HERE%20###")

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/products_groups/group_name?utoken=###%20YOUR%20UTOKEN%20HERE%20###");

xhr.send(data);
import requests

url = "https://api.yotpo.com/v1/apps/app_key/products_groups/group_name###%20YOUR%20UTOKEN%20HERE%20###"

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

print(response.text)
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:36Z",
            "updated_at": "2017-01-04T16:20:36Z",
            "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)

 
Suggest Edits

Add products to a product group (update)

 
puthttps://api.yotpo.com/v1/apps/app_key/products_groups/group_name?utoken=### YOUR UTOKEN HERE ###
{
"product_ids_to_remove":[
   "###Product_ID###",
   "###Product_ID###"
], 
 "utoken": "###Your_U-Token###"
}
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

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 ###
curl --request DELETE \
  --url 'https://api.yotpo.com/v1/apps/app_key/products_groups/group_name?utoken=###%20YOUR%20UTOKEN%20HERE%20###'
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api.yotpo.com/v1/apps/app_key/products_groups/group_name###%20YOUR%20UTOKEN%20HERE%20###',
  qs: { 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/products_groups/group_name?utoken=###%20YOUR%20UTOKEN%20HERE%20###")

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

request = Net::HTTP::Delete.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("DELETE", "https://api.yotpo.com/v1/apps/app_key/products_groups/group_name?utoken=###%20YOUR%20UTOKEN%20HERE%20###");

xhr.send(data);
import requests

url = "https://api.yotpo.com/v1/apps/app_key/products_groups/group_name###%20YOUR%20UTOKEN%20HERE%20###"

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

print(response.text)
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.