App Market

The App Market Developer Hub

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

Suggest Edits

Getting Started

 

Yotpo Core API

If you're looking for Yotpo's core API for existing Yotpo features and actions, you can find them here:
Yotpo Core API Reference

Welcome to Yotpo's App Market API Reference :wave+:

Here you'll find all the endpoints you need to build apps on the Yotpo platform.
Before you get started, be sure to visit the Developer Portal and register your app.

Once approved, we'll send you all the credentials you need to start building.
To learn more about app registration and creation click here.

Table of Contents

Endpoints are conveniently organized by sections for Products, Reviews, and Webhook requests.

Section
Description

Use Orders to retrieve all available Yotpo orders per account. This call will return order metrics such as order id, user_name, user_email, product_url, external_product_id, and more.

Products endpoints help you retrieve data on products including product star-ratings, promoted products, product reviews, and more.

Reviews endpoints help you retrieve reviews data including top reviews, reviews by review ID, and more.

Webhooks endpoints allow you to create, update, and manage webhooks for newly created reviews and products.

Please also take a few minutes to familiarize yourself with the guidelines and conventions listed below.

Protocol Support

The Yotpo API supports both HTTP and HTTPS requests.

UTF-8 Support

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

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 - The number of pages to return
count - The number of results to return per page

Parameters

Email and URL parameters you send in the calls must be in the correct format.

Parameter
Format

email

user@domain.com

date

YYYY-MM-DD

Status Codes

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

Response Code
Status

200

Successful Response

401

Unauthorized Request

500

Internal Server Error e.g. Timeout

App Market API docs are laid out as follows:

Endpoints

Endpoints are listed by name and request-type according to their respective category.

API Base URL and Path

The API base URL and path are provided just below the endpoint title and description.

Each endpoint lists the API request-type, base URL, and path in the center of the page including tabbed examples in cURL, Node, Ruby, JavaScript, and Python.

Path and Query Parameters

You'll find path and query parameters listed below the code examples pane.
Each parameter includes a short description of the possible parameter values.

Required Parameters

  • Path parameters are a part of the endpoint URL and thus always required.
  • Query parameters are optional unless denoted as Required

Responses

You'll find sample responses in the right-hand side of the page. Note that some responses may include more than one sample which can be viewed by clicking on the relevant tab.

Suggest Edits

Generate Access Token

Use this endpoint to generate an access_token using your OAuth 2.0 code.

 
posthttps://developers.yotpo.com/v2/oauth2/token
{
	"grant_type": "authorization_code",
	"client_id": "ad75ashh833b123a844660454acd63a3",
	"client_secret": "5892d858jh8d2221as59b5k50981fcdc",
	"redirect_uri": "https://www.yotpo.com/myapp",
	"code": "035h12g8mnve9934804jk17428k8b63b"
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

No response examples available

Body Params

grant_type
string
required

The grant_type for this request is authorization_code

client_id
string
required

The identifier of your newly created app

client_secret
string
required

The secret key of your newly created app

redirect_uri
string
required

The redirect/callback URI provided upon app creation. Your token will be sent there

code
string
required

The OAuth 2.0 code granted via the installation link

 

Tip:

Need help generating your access token? Click here for instructions.

Suggest Edits

Orders

Use this endpoint to retrieve all available Yotpo orders per account. This call will return order metrics such as order id, user_name, user_email, product_url, external_product_id, and more. For a detailed breakdown, click here.

 
gethttps://developers.yotpo.com/v2/account_id/orders?access_token=access_token
curl --request GET \
  --url 'https://developers.yotpo.com/v2/account_id/orders?access_token=access_token'
var request = require("request");

var options = { method: 'GET',
  url: 'https://developers.yotpo.com/v2/account_id/orders',
  qs: { access_token: 'access_token' } };

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

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

url = URI("https://developers.yotpo.com/v2/account_id/orders?access_token=access_token")

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://developers.yotpo.com/v2/account_id/orders?access_token=access_token");

xhr.send(data);
import requests

url = "https://developers.yotpo.com/v2/account_id/orders"

querystring = {"access_token":"access_token"}

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

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{  
   "status":{  
      "code":200,
      "message":"OK"
   },
   "orders":{  
      "purchases":[  
         {  
            "id":123,
            "user_email":"john@yotpo.com",
            "user_name":"john doe",
            "order_id":"1",
            "external_product_id":"",
            "product_url":"http://yourstore.com/products/oc2101/index.php?route=product/product\u0026product_id=40",
            "order_date":"2016-12-08T12:34:25.000Z",
            "product_description":"this is a description of your product",
            "created_at":"2017-01-15T12:14:48.000Z"
         },  
         {  
            "id":1234,
            "user_email":"john@yotpo.com",
            "user_name":"john yotpo",
            "order_id":"001",
            "external_product_id":"",
            "product_url":"http://osworx.net/demos/oc2101/index.php?route=product/product\u0026product_id=40",
            "order_date":"2015-12-08T12:34:25.000Z",
            "product_description":"iPhone is a revolutionary new mobile phone that allows you to make a call by simply tapping a name or number in your address book, a favorites list, or a call log. It also automatically syncs all your contacts from a PC, Mac, or Internet service. And it lets you select and listen to voicemail messages in whatever order you want just like email.",
            "created_at":"2016-01-15T12:14:48.000Z"
         }     ]
   }
}

Path Params

account_id
string
required

Your account's API app key

Query Params

access_token
string
required

Your Yotpo access token. Click here to learn how to generate one

page
int32

Page number

count
int32

The number of orders you want to retrieve

 

Orders Data - Response Attributes

Attributes
Description

id

Order ID

user_email

The customer's email address

user_name

The customer's name

order_id

The external order ID

external_product_id

The external product ID

product_url

The URL of the product page

order_date

The timestamp generated upon order placement

product_description

A description of the product

created_at

The timestamp generated upon the object creation in Yotpo

Suggest Edits

Introduction to Products

 

Use Products endpoints to retrieve data on products including product star-ratings, promoted products, product reviews, and more.

Here are just a few things you can do with Products endpoints:

:star+: Get the total_reviews written about a product.
:star+: Get the average_score (average star-rating) of a product.
:star+: Retrieve a list of Promoted Products
:star+: Get custom review form fields and data.

Building apps with Products

Check out the API Toolkits to see what you can build with Products endpoints.

Product ID

Note that in some parts of the API, product_id may be referred to as external_product_id

Suggest Edits

All Products

Retrieve paginated product data for your entire product catalog by account_id. This call will return product metrics such as product id, external_product_id, average_score, total_reviews, product images and more. For response attributes, click here.

 
gethttps://developers.yotpo.com/v2/account_id/products?access_token=access_token
curl --request GET \
  --url 'https://developers.yotpo.com/v2/account_id/products?access_token=access_token'
var request = require("request");

var options = { method: 'GET',
  url: 'https://developers.yotpo.com/v2/account_id/products',
  qs: { access_token: 'access_token' } };

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

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

url = URI("https://developers.yotpo.com/v2/account_id/products?access_token=access_token")

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://developers.yotpo.com/v2/account_id/products?access_token=access_token");

xhr.send(data);
import requests

url = "https://developers.yotpo.com/v2/account_id/products"

querystring = {"access_token":"access_token"}

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

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
    "status": {
        "code": 200,
        "message": "ok"
    },
    "pagination": {
        "page": 1,
        "count": 10,
        "total": 13
    },
    "products": {
        "products": [
            {
                "id": 819,
                "external_product_id": "1",
                "name": "vlad frog",
                "url": "https://yotpo.com/go/f1XKPqNY",
                "created_at": "2012-08-21T10:16:08.000Z",
                "updated_at": "2017-11-01T07:03:49.000Z",
                "average_score": 5,
                "total_reviews": 1,
                "category": {
                    "id": 1,
                    "name": "Electronics"
                },
                "description": "",
                "specs": [],
                "images": []
            },
            {
                "id": 1798,
                "external_product_id": "Id of the product",
                "name": "Product Title",
                "url": "https://yotpo.com/go/sWF9tNN8",
                "created_at": "2012-11-29T12:49:19.000Z",
                "updated_at": "2016-10-19T05:00:12.000Z",
                "average_score": 4.67,
                "total_reviews": 3,
                "category": {
                    "id": 1,
                    "name": "Electronics"
                },
                "description": "product description",
                "specs": [],
                "images": []
            },
            {
                "id": 288569,
                "external_product_id": "145503817",
                "name": "Ipad",
                "url": "https://yotpo.com/go/cuMDNwkt",
                "created_at": "2013-06-30T12:27:11.000Z",
                "updated_at": "2014-11-07T07:07:22.000Z",
                "average_score": 0,
                "total_reviews": 0,
                "category": {
                    "id": 1,
                    "name": "Electronics"
                },
                "description": "Its an iPad",
                "specs": [],
                "images": [
                    {
                        "original": "https://ddcfq0gxiontw.cloudfront.net/Product/288638/250429/original.gif?1455154589",
                        "square": "https://ddcfq0gxiontw.cloudfront.net/Product/288638/250429/square.gif?1455154589",
                        "facebook": "https://ddcfq0gxiontw.cloudfront.net/Product/288638/250429/facebook.gif?1455154589",
                        "facebook_square": "https://ddcfq0gxiontw.cloudfront.net/Product/288638/250429/facebook_square.gif?1455154589"
                    }
                ]
            },
            {
                "id": 11305270,
                "external_product_id": "40",
                "name": "iPhone",
                "url": "https://yotpo.com/go/vBnOpHeK",
                "created_at": "2016-01-14T16:29:14.000Z",
                "updated_at": "2016-04-05T10:14:03.000Z",
                "average_score": 5,
                "total_reviews": 2,
                "category": {
                    "id": 1,
                    "name": "Electronics"
                },
                "description": "iPhone is a revolutionary new mobile phone that allows you to make a call by simply tapping a name or number in your address book, a favorites list, or a call log. It also automatically syncs all your contacts from a PC, Mac, or Internet service. And it lets you select and listen to voicemail messages in whatever order you want just like email.",
                "specs": [],
                "images": [
                    {
                        "original": "https://ddcfq0gxiontw.cloudfront.net/Product/11408720/8627709/original.jpg?1455285285",
                        "square": "https://ddcfq0gxiontw.cloudfront.net/Product/11408720/8627709/square.jpg?1455285285",
                        "facebook": "https://ddcfq0gxiontw.cloudfront.net/Product/11408720/8627709/facebook.jpg?1455285285",
                        "facebook_square": "https://ddcfq0gxiontw.cloudfront.net/Product/11408720/8627709/facebook_square.jpg?1455285285"
                    }
                ]
            }
        ]
    }
}

Path Params

account_id
string
required

Your account's API app key

Query Params

access_token
string
required

Your Yotpo access token. Click here to learn how to generate one

page
string

The page number of a paginated response

count
string

The number of products to return per page

 

Product ID

Note that in some parts of the API, product_id may be referred to as external_product_id

All Products - Response Attributes

Attribute
Description

id

Order ID

external_product_id

The external product id of the product reviewed

name

The customer's name

url

The product page URL

created_at

The timestamp generated upon product creation

updated_at

The timestamp generated when the product was last updated

average_score

The average star-rating of the product

total_reviews

The total review count of the product

category

The product category

description

The product description

spec

Product specs

images

The product image URL

Suggest Edits

Product Data

Retrieve product data by product_id. This call returns product data such as product identifiers, average score, total review count, and more. For a detailed breakdown, click here.

 
gethttps://developers.yotpo.com/v2/account_id/products/product_id?access_token=access_token
curl --request GET \
  --url 'https://developers.yotpo.com/v2/account_id/products/product_id?access_token=access_token'
var request = require("request");

var options = { method: 'GET',
  url: 'https://developers.yotpo.com/v2/account_id/products/product_id',
  qs: { access_token: 'access_token' } };

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

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

url = URI("https://developers.yotpo.com/v2/account_id/products/product_id?access_token=access_token")

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://developers.yotpo.com/v2/account_id/products/product_id?access_token=access_token");

xhr.send(data);
import requests

url = "https://developers.yotpo.com/v2/account_id/products/product_id"

querystring = {"access_token":"access_token"}

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

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
	status: {
		code: 200,
		message: "ok"
	},
	product: {
		id: 1234,
		external_product_id: "prod_1234",
		name: "Yotpo product",
		url: "https://yotpo.com/go/vYxFfr8O",
		created_at: "2012-11-19T11:05:36.000Z",
		updated_at: "2014-11-04T07:00:42.000Z",
		average_score: 3.67,
		total_reviews: 3,
		category: {
			id: 1,
			name: "Electronics"
		},
		description: "This is a product,
		specs: [ ],
		images: [
			{
				original: "https://ddcfq0gxiontw.cloudfront.net/Product/1/1358/original.png?1453893581",
				square: "https://ddcfq0gxiontw.cloudfront.net/Product/1/1358/square.png?1453893581",
				facebook: "https://ddcfq0gxiontw.cloudfront.net/Product/1/1358/facebook.png?1453893581",
				facebook_square: "https://ddcfq0gxiontw.cloudfront.net/Product/1/1358/facebook_square.png?1453893581"
			}
		]
	}
}

Path Params

account_id
string
required

Your account's API app key

product_id
string
required

The external_product_id of the product. Can be retrieved using All Products

Query Params

access_token
string
required

Your Yotpo access token. Click here to learn how to generate one

 

Product ID

Note that in some parts of the API, product_id may be referred to as external_product_id

Product Data - Response Attributes

Attribute
Description

id

The product ID

external_product_id

The external product ID

name

The product name

url

The product page URL

created_at

The timestamp generated upon product creation

updated_at

The timestamp generated when the product was last updated

average_score

The average star-rating of the product

total_reviews

The total review count of the product

category

The product category

description

The product description

spec

Product specs

images

The product image URL

Suggest Edits

Product Reviews

Retrieve product reviews for a specific product using the external_product_id.

 
gethttps://developers.yotpo.com/v2/account_id/products/external_product_id/reviews?access_token=access_token
curl --request GET \
  --url 'https://developers.yotpo.com/v2/account_id/products/external_product_id/reviews?access_token=access_token'
var request = require("request");

var options = { method: 'GET',
  url: 'https://developers.yotpo.com/v2/account_id/products/external_product_id/reviews',
  qs: { access_token: 'access_token' } };

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

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

url = URI("https://developers.yotpo.com/v2/account_id/products/external_product_id/reviews?access_token=access_token")

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://developers.yotpo.com/v2/account_id/products/external_product_id/reviews?access_token=access_token");

xhr.send(data);
import requests

url = "https://developers.yotpo.com/v2/account_id/products/external_product_id/reviews"

querystring = {"access_token":"access_token"}

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

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "pagination": {
        "page": 1,
        "count": 2,
        "total": 239
    },
    "reviews": {
        "reviews": [
            {
                "id": "59353719",
                "score": 5,
                "votes_up": 0,
                "votes_down": 0,
                "content": "Received this pillow with the purchase of our king-size bed. Wish the offer had been available when we purchased a queen size bed for our guest room months earlier.. yes, we love the beds too!",
                "title": "Great pillow!",
                "created_at": "2018-02-06T02:57:29.000Z",
                "verified_buyer": true,
                "source_review_id": 0,
                "custom_fields": {
                    "--9728": {
                        "title": "Age",
                        "form_id": 207,
                        "value": "55 or older",
                        "field_type": "SingleChoice"
                    },
                    "--9729": {
                        "title": "Sleep position",
                        "form_id": 207,
                        "value": "On my side",
                        "field_type": "SingleChoice"
                    },
                    "--9730": {
                        "title": "Hours of Sleep",
                        "form_id": 207,
                        "value": "7 to 9 hours",
                        "field_type": "SingleChoice"
                    }
                },
                "images_data": [],
                "user": {
                    "id": 16101346,
                    "display_name": "Florence K.",
                    "social_image": "https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png",
                    "email": "Flora@email.com"
                },
                "product": null,
                "user_id": 16101364,
                "product_id": 35421767,
                "comment": null,
                "external_product_id": "51594874628"
            },
            {
                "id": "53959148",
                "score": 5,
                "votes_up": 0,
                "votes_down": 0,
                "content": "I was hesitant on buying my matress over the internet but now I can say it was a good decision to do so. The matress is very confortble, especially for me who sleeps on the side. Please get the foundation too.",
                "title": "Excellent mattress!",
                "created_at": "2018-02-06T03:58:42.000Z",
                "verified_buyer": true,
                "source_review_id": 0,
                "custom_fields": {
                    "--9728": {
                        "title": "Age",
                        "form_id": 207,
                        "value": "35 to 44",
                        "field_type": "SingleChoice"
                    },
                    "--9729": {
                        "title": "Sleep position",
                        "form_id": 207,
                        "value": "On my side",
                        "field_type": "SingleChoice"
                    },
                    "--9730": {
                        "title": "Hours of Sleep",
                        "form_id": 207,
                        "value": "7 to 9 hours",
                        "field_type": "SingleChoice"
                    }
                },
                "images_data": [],
                "user": {
                    "id": 16028168,
                    "display_name": "Juan G.",
                    "social_image": "https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png",
                    "email": "jguzman@email.com"
                },
                "product": null,
                "user_id": 16028186,
                "product_id": 35421767,
                "comment": null,
                "external_product_id": "51594874628"
            }
        ]
    }
}
{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "pagination": {
        "page": 1,
        "count": 5,
        "total": 2
    },
    "reviews": {
        "reviews": [
            {
                "id": "24783037",
                "score": 5,
                "votes_up": 0,
                "votes_down": 0,
                "content": "test review",
                "title": "test review",
                "created_at": "2016-02-14T18:24:02.000Z",
                "verified_buyer": false,
                "source_review_id": 0,
                "custom_fields": {},
                "images_data": [],
                "user": null,
                "product": null,
                "user_id": 5819377,
                "product_id": 11408720,
                "comment": null
            },
            {
                "id": "24783015",
                "score": 5,
                "votes_up": 0,
                "votes_down": 0,
                "content": "test review",
                "title": "Test review",
                "created_at": "2016-02-14T18:21:08.000Z",
                "verified_buyer": false,
                "source_review_id": 0,
                "custom_fields": {},
                "images_data": [],
                "user": null,
                "product": null,
                "user_id": 5819375,
                "product_id": 11408720,
                "comment": null
            }
        ]
    }
}

Path Params

account_id
string
required

Your account's API app key

external_product_id
string
required

The external_product_id value. Can be retrieved using All Reviews

Query Params

access_token
string
required

Your Yotpo access token. Click here to learn how to generate one

page
int32

The page number of the paginated response

count
int32

The number of reviews you want to retrieve

star
int32

Filter by star rating score

 

Product ID

Note that in some parts of the API, product_id may be referred to as external_product_id

Product Reviews - Response Attributes

Attribute
Description

id

The review ID

score

The star-rating score where 5 is a 5-star rating :star+::star+::star+::star+::star+:

votes_up

The number of shoppers who voted up for this review :+1+:

votes_down

The number of shoppers who voted down for this review :-1+:

content

The textual review content

title

The title of the review

created_at

The timestamp generated upon review creation

verified_buyer

The status of the reviewer. Verified buyers are buyers who created their review via Mail After Purchase

source_review_id

The review id by source

custom_fields

Custom review form fields. Nested parameters include the form title,form_id,value, and field type

images_data

user

User data. Nested parameters include the user id, display _name, social_image, and email

product

user_id

The unique identifier of the reviewer who submitted the review

product_id

The unique product identifier of the product reviewed

comment

The comment left on the review

Suggest Edits

Product Star Rating

Retrieve the average star-rating and review count for a specific product by external_product_id.

 
gethttps://developers.yotpo.com/v2/account_id/star_rating/products/external_product_id?access_token=access_token
curl --request GET \
  --url 'https://developers.yotpo.com/v2/account_id/star_rating/products/external_product_id?access_token=access_token'
var request = require("request");

var options = { method: 'GET',
  url: 'https://developers.yotpo.com/v2/account_id/star_rating/products/external_product_id',
  qs: { access_token: 'access_token' } };

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

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

url = URI("https://developers.yotpo.com/v2/account_id/star_rating/products/external_product_id?access_token=access_token")

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://developers.yotpo.com/v2/account_id/star_rating/products/external_product_id?access_token=access_token");

xhr.send(data);
import requests

url = "https://developers.yotpo.com/v2/account_id/star_rating/products/external_product_id"

querystring = {"access_token":"access_token"}

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

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "pagination": null,
    "product_star_rating": {
        "external_product_id": "376700306",
        "average_score": 4.5,
        "total_reviews": 15527
    }
}

Path Params

account_id
string
required

Your account's API app key

external_product_id
string
required

The external_product_id value. Can be retrieved using All Reviews

Query Params

access_token
string
required

Your Yotpo access token. Click here to learn how to generate one

 

Product Star Rating - Response Attributes

Attribute
Description

external_product_id

The external product ID

average_score

The average star-rating of the product

total_reviews

The total number of reviews about the product

Suggest Edits

Promoted Products

Yotpo's smart algorithm automatically promotes your most popular products by purchase date, star rating, number of reviews, and manually selected products. Promoted Products are a great way to showcase your most popular or complementary products for better exposure.

 
gethttps://developers.yotpo.com/v2/account_id/promoted_products?access_token=access_token
curl --request GET \
  --url 'https://developers.yotpo.com/v2/account_id/promoted_products?access_token=access_token'
var request = require("request");

var options = { method: 'GET',
  url: 'https://developers.yotpo.com/v2/account_id/promoted_products',
  qs: { access_token: 'access_token' } };

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

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

url = URI("https://developers.yotpo.com/v2/account_id/promoted_products?access_token=access_token")

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://developers.yotpo.com/v2/account_id/promoted_products?access_token=access_token");

xhr.send(data);
import requests

url = "https://developers.yotpo.com/v2/account_id/promoted_products"

querystring = {"access_token":"access_token"}

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

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "pagination": null,
    "promoted_products": {
        "products": [
            {
                "external_product_id": "377700207",
                "type": "MostBought",
                "position": 1
            },
            {
                "external_product_id": "11558138316",
                "type": "MostBought",
                "position": 2
            },
            {
                "external_product_id": "11558122956",
                "type": "MostBought",
                "position": 3
            },
            {
                "external_product_id": "11558028940",
                "type": "MostBought",
                "position": 4
            },
            {
                "external_product_id": "11558145036",
                "type": "MostBought",
                "position": 5
            },
            {
                "external_product_id": "6097670982",
                "type": "MostBought",
                "position": 6
            },
            {
                "external_product_id": "92671377420",
                "type": "MostBought",
                "position": 7
            },
            {
                "external_product_id": "92676915212",
                "type": "MostBought",
                "position": 8
            }
        ]
    }
}

Path Params

account_id
string
required

Your account's API app key

Query Params

access_token
string
required

Your Yotpo access token. Click here to learn how to generate one

 

Promoted Products Logic

Promoted Products are a great way of automatically publicizing your most popular products based on Yotpo's smart algorithm. Products promoted by Yotpo's algorithm must have been purchased at least once within the last 14 days. Learn more about Promoted Products in the Yotpo Reviews Widget here

Promoted Products - Response Attributes

Attribute
Description

external_product_id

The external product ID

type

The product promotion logic

position

The product ranking

Suggest Edits

Introduction to Reviews

 

Use Reviews endpoints to retrieve reviews data including top reviews, reviews by review ID, and more.

Reviews endpoints allow you to get:

:star+: The top three site reviews or top three product reviews by external_product_id
:star+: The review content and star-rating (score) of a product or site review.
:star+: Custom review form fields and data.
:star+: The best reviews you've received according to star-rating and sentiment.
:star+: The best sentences from your Yotpo reviews according to star-rating and sentiment.

Suggest Edits

All Reviews

Retrieve reviews data per account as a paginated response. This call will return reviews metrics such as review id, star-ratings score, votes_up or votes_down, review content, product identifiers and more. For a detailed breakdown, click here.

 
gethttps://developers.yotpo.com/v2/account_id/reviews?access_token=access_token
curl --request GET \
  --url 'https://developers.yotpo.com/v2/account_id/reviews?access_token=access_token'
var request = require("request");

var options = { method: 'GET',
  url: 'https://developers.yotpo.com/v2/account_id/reviews',
  qs: { access_token: 'access_token' } };

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

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

url = URI("https://developers.yotpo.com/v2/account_id/reviews?access_token=access_token")

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://developers.yotpo.com/v2/account_id/reviews?access_token=access_token");

xhr.send(data);
import requests

url = "https://developers.yotpo.com/v2/account_id/reviews"

querystring = {"access_token":"access_token"}

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

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "pagination": {
        "page": 1,
        "count": 2,
        "total": 11890
    },
    "reviews": {
        "reviews": [
            {
                "id": "53697686",
                "score": 5,
                "votes_up": 0,
                "votes_down": 0,
                "content": "This is the best pillow I have ever used. I am used to a very firm foam pillow, but upon receiving this one with my mattress I am very pleased. It is not as firm but I find that I like it much better.",
                "title": "The Best",
                "created_at": "2018-02-06T12:25:49.000Z",
                "verified_buyer": true,
                "source_review_id": 0,
                "custom_fields": {
                    "--9728": {
                        "title": "Age",
                        "form_id": 207,
                        "value": "25 to 34",
                        "field_type": "SingleChoice"
                    },
                    "--9729": {
                        "title": "Sleep position",
                        "form_id": 207,
                        "value": "On my stomach",
                        "field_type": "SingleChoice"
                    },
                    "--9730": {
                        "title": "Hours of Sleep",
                        "form_id": 207,
                        "value": "7 to 9 hours",
                        "field_type": "SingleChoice"
                    }
                },
                "images_data": [],
                "user": {
                    "id": 16014677,
                    "display_name": "George M.",
                    "social_image": "https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png",
                    "email": "curiousgeorge@email.com"
                },
                "product": null,
                "user_id": 16014677,
                "product_id": 35421776,
                "comment": null,
                "external_product_id": "59154867428"
            },
            {
                "id": "59352441",
                "score": 5,
                "votes_up": 0,
                "votes_down": 0,
                "content": "The first few nights the smell from the mattress was really unbearable, but once it dissipates, it's like sleeping on cloud 9!",
                "title": "It's Great",
                "created_at": "2018-02-06T01:58:52.000Z",
                "verified_buyer": true,
                "source_review_id": 0,
                "custom_fields": {
                    "--9728": {
                        "title": "Age",
                        "form_id": 207,
                        "value": "25 to 34",
                        "field_type": "SingleChoice"
                    },
                    "--9729": {
                        "title": "Sleep position",
                        "form_id": 207,
                        "value": "On my back",
                        "field_type": "SingleChoice"
                    },
                    "--9730": {
                        "title": "Hours of Sleep",
                        "form_id": 207,
                        "value": "10 to 12 hours",
                        "field_type": "SingleChoice"
                    }
                },
                "images_data": [],
                "user": {
                    "id": 16099362,
                    "display_name": "Laurie H.",
                    "social_image": "https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png",
                    "email": "Laurie@email.com"
                },
                "product": null,
                "user_id": 16909632,
                "product_id": 3247878,
                "comment": null,
                "external_product_id": "377712307"
            }
        ]
    }
}

Path Params

account_id
string
required

Your account's API app key

Query Params

access_token
string
required

Your Yotpo access token. Click here to learn how to generate one

include_nested
boolean

Retrieve nested data. e.g. user data

include_site_reviews
boolean

Include site reviews in addition to product reviews

count
int32

The number of reviews you want to retrieve

page
int32

Page number

sort
string

Sort values: date, votes_up, votes_down, time, rating, reviewer_type

direction
string

Descending (default) or Ascending: asc, desc

star
int32

Filter by star rating score

 

Reviews Data - Response Attributes

Attribute
Description

id

The review ID

score

The star-rating score where 5 is a 5-star rating

votes_up :+1+:

The number of shoppers who voted up for this review

votes_down :-1+:

The number of shoppers who voted down for this review

content

The textual review content

title

The title of the review

created_at

The timestamp generated upon review creation

verified_buyer

The status of the reviewer. Verified buyers are buyers who created their review via Mail After Purchase

source_review_id

The review id by source

custom_fields

Custom review form fields. Nested parameters include the form title,form_id,value, and field type

images_data

user

User data. Nested parameters include the user id, display _name, social_image, and email

product

user_id

The unique identifier of the reviewer who submitted the review

product_id

The unique product identifier of the product reviewed

comment

The comment left on the review

external_product_id

The external product id of the product reviewed

Product ID

Note that in some parts of the API, product_id may be referred to as external_product_id

Suggest Edits

Review by Review ID

Retrieve a specific review by review_id.

 
gethttps://developers.yotpo.com/v2/account_id/reviews/review_id?access_token=access_token
curl --request GET \
  --url 'https://developers.yotpo.com/v2/account_id/reviews/review_id?access_token=access_token'
var request = require("request");

var options = { method: 'GET',
  url: 'https://developers.yotpo.com/v2/account_id/reviews/review_id',
  qs: { access_token: 'access_token' } };

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

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

url = URI("https://developers.yotpo.com/v2/account_id/reviews/review_id?access_token=access_token")

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://developers.yotpo.com/v2/account_id/reviews/review_id?access_token=access_token");

xhr.send(data);
import requests

url = "https://developers.yotpo.com/v2/account_id/reviews/review_id"

querystring = {"access_token":"access_token"}

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

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "pagination": null,
    "review": {
        "review": {
            "id": "3021",
            "score": 5,
            "votes_up": 1,
            "votes_down": 0,
            "content": "Best sandal ever!",
            "title": "Best sandal ever!",
            "created_at": "2012-11-29T12:49:19.000Z",
            "verified_buyer": false,
            "source_review_id": 0,
            "custom_fields": {},
            "images_data": [],
            "user": null,
            "product": null,
            "user_id": 2245,
            "product_id": 1802,
            "comment": null
        }
    }
}
{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "pagination": null,
    "review": {
        "review": {
            "id": "1396",
            "score": 5,
            "votes_up": 3,
            "votes_down": 1,
            "content": "such a great review",
            "title": "the best review ever",
            "created_at": "2012-08-21T10:16:08.000Z",
            "verified_buyer": false,
            "source_review_id": 0,
            "custom_fields": {},
            "images_data": [],
            "user": {
                "id": 2245,
                "display_name": "billy",
                "social_image": "https://graph.facebook.com/905160246/picture?type=large",
                "email": "billytheking@email.com"
            },
            "product": null,
            "user_id": 2245,
            "product_id": 823,
            "comment": null,
            "external_product_id": "1"
        }
    }
}

Path Params

account_id
string
required

Your account's API app key

review_id
string
required

The review_id. Can be found using All Reviews

Query Params

access_token
string
required

Your Yotpo access token. Click here to learn how to generate one

included_nested
boolean

include_nested data to return nested user data

include_site_reviews
boolean

Include site reviews in addition to product reviews

 

Review by Review ID - Response Atrributes

Attribute
Description

id

The review_id. Can be found using All Reviews

score

The star-rating review score

votes_up :+1+:

The number of votes_up

votes_down :-1+:

The number of votes_down

content

The textual review content

title

The textual title of the review

created_at

The date at which the review was created
e.g. 2012-11-29T12:49:19.000Z

verified_buyer

The type of reviewer. Averified_buyer is a buyer who created the review through the Mail After Purchase review request email

source_review_id

custom_fields

Custom review form questions and answers

images_data

user

product

user_id

The unique ID of the user who created the review

product_id

The unique ID of the reviewed product

comment

A comment on a review left by the store owner

Suggest Edits

Top Reviews

July 1, 2018: The Top Reviews endpoint will be deprecated within the coming months in favor of a more robust Best Reviews endpoint. To maintain app functionality and stability, we advise against building new apps using this API call.

 
gethttps://developers.yotpo.com/v2/account_id/top_reviews?access_token=access_token
curl --request GET \
  --url 'https://developers.yotpo.com/v2/account_id/top_reviews?access_token=access_token'
var request = require("request");

var options = { method: 'GET',
  url: 'https://developers.yotpo.com/v2/account_id/top_reviews',
  qs: { access_token: 'access_token' } };

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

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

url = URI("https://developers.yotpo.com/v2/account_id/top_reviews?access_token=access_token")

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://developers.yotpo.com/v2/account_id/top_reviews?access_token=access_token");

xhr.send(data);
import requests

url = "https://developers.yotpo.com/v2/account_id/top_reviews"

querystring = {"access_token":"access_token"}

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

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
    "status": {
        "code": 200,
        "message": "ok"
    },
    "pagination": null,
    "top_reviews": {
        "reviews": [
            {
                "image_url": "",
                "score": 5,
                "title": "J'adore",
                "content": "Belle et confortable. On peut pas faire mieux.",
                "product_url": "https://yotpo.com/go/1usvvgxJ",
                "created_at": "2012-12-12T16:08:57.000Z"
            },
            {
                "image_url": "",
                "score": 5,
                "title": "Best sandal ever!",
                "content": "Best sandal ever!",
                "product_url": "https://yotpo.com/go/1usvvgxJ",
                "created_at": "2012-11-29T12:49:19.000Z"
            },
            {
                "image_url": "",
                "score": 5,
                "title": "site Rev",
                "content": "site Rev",
                "product_url": "https://yotpo.com/go/ofE6Xan0",
                "created_at": "2013-10-27T08:42:09.000Z"
            }
        ]
    }
}

Path Params

account_id
string
required

Your account's API app key

Query Params

access_token
string
required

Your Yotpo access token. Click here to learn how to generate one

external_product_id
string

The product ID you want to retrieve data for. Unless you indicate a product reviews this endpoint would fetch site reviews

 

IMPORTANT

July 1, 2018: The Top Reviews endpoint will be deprecated within the coming months in favor of a more robust Best Reviews endpoint. To maintain app functionality and stability, we advise against building new apps using this API call.

Top Reviews - Response Attributes

Atrributes
Description

image_url

The product image URL

score

The star-rating review score

title

The textual title of the review

content

The textual review content

product_url

The URL of the product page

created_at

The date at which the review was created
e.g. 2012-11-29T12:49:19.000Z

Suggest Edits

Best Reviews

This endpoint automatically retrieves the very best reviews from your Yotpo reviews based on star-rating and sentiment. You define the star-rating score, topics, sentence length, and more.

 
posthttps://developers.yotpo.com/v2/account_id/best_reviews?access_token=access_token
{
	"minimum_review_length": 150,
	"maximum_review_length": 500,
	"minimum_title_length": 20,
	"maximum_title_length": 100,
	"start_date": "2017-01-13T00:00:00.000Z",
	"end_date": "2018-05-13T00:00:00.000Z",
	"external_product_ids": [],
	"topics": [],
	"exclude_topics": [],
	"max_reviews": 10,
	"minimum_score": 4,
	"exclude_unpublished": true,
	"exclude_syndicated": false,
	"exclude_negative_opinions": true,
	"exclude_grouped_reviews": false
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "pagination": null,
    "best_review": {
        "best_reviews": [
            {
                "review_id": "46388102",
                "external_product_id": "54588",
                "topics": [
                    "adore",
                    "corset",
                    "curves",
                    "fit",
                    "hugs",
                    "jaw",
                    "lace",
                    "looks",
                    "man",
                    "set",
                    "thong"
                ]
            },
            {
                "review_id": "43395515",
                "external_product_id": "57923",
                "topics": [
                    "bottoms",
                    "construction",
                    "coverage",
                    "fabric",
                    "fit",
                    "point",
                    "quality",
                    "suit",
                    "swimsuit"
                ]
            },
            {
                "review_id": "35982283",
                "external_product_id": "33725",
                "topics": [
                    "bra",
                    "color",
                    "conceals",
                    "fit",
                    "panties",
                    "set",
                    "size",
                    "underwire"
                ]
            },
            {
                "review_id": "49687565",
                "external_product_id": "43830",
                "topics": [
                    "amount",
                    "bra",
                    "contour",
                    "lift",
                    "line",
                    "material",
                    "pattern",
                    "results"
                ]
            },
            {
                "review_id": "40894146",
                "external_product_id": "37296",
                "topics": [
                    "choice",
                    "color",
                    "find",
                    "gals",
                    "selection",
                    "set",
                    "support",
                    "underwear"
                ]
            },
            {
                "review_id": "43155242",
                "external_product_id": "67809",
                "topics": [
                    "color",
                    "comfort",
                    "customer service",
                    "fit",
                    "lone",
                    "set",
                    "shipping",
                    "style"
                ]
            },
            {
                "review_id": "42034777",
                "external_product_id": "46086",
                "topics": [
                    "bra",
                    "breasts",
                    "company",
                    "feel",
                    "fit",
                    "looks",
                    "panties",
                    "product"
                ]
            },
            {
                "review_id": "48913371",
                "external_product_id": "72214",
                "topics": [
                    "38-b",
                    "attitudes",
                    "details",
                    "fabric",
                    "feel",
                    "looks",
                    "stretch"
                ]
            },
            {
                "review_id": "54276377",
                "external_product_id": "77211",
                "topics": [
                    "back",
                    "inserts",
                    "neck",
                    "piece",
                    "range",
                    "size",
                    "straps"
                ]
            },
            {
                "review_id": "57942222",
                "external_product_id": "63561",
                "topics": [
                    "amount",
                    "cleavage",
                    "coverage",
                    "curves",
                    "piece",
                    "snug",
                    "swimsuit"
                ]
            }
        ]
    }
}

Path Params

account_id
string
required

Your account's API app key.

Query Params

access_token
string
required

Your Yotpo access_token. Click here to learn how to generate one

Body Params

minimum_review_length
int32

The minimum length of reviews to return. Must be less than maximum_review_length. Default: 150 characters

maximum_review_length
int32

The maximum length of reviews to return. Must be greater than minimum_review_length Default: 500 characters

minimum_title_length
int32

The minimum review title length to return. Default: 20 characters

maximum_title_length
int32

The maximum review title length to return. Default: 100 characters

start_date
date

Start date of your request (Default: 12 Months) YYYY-MM-DDT00:00:00.000Z

end_date
date

End date of your request (Default: 12 Months). YYYY-MM-DDT00:00:00.000Z

external_product_ids
array of strings

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

topics
array of strings

The name of the topic. Supports multiple topics.

exclude_topics
array of strings

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

max_reviews
int32

The maximum number of reviews to return (Default: 10). Limited to 1000 reviews per request.

minimum_score
int32

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

exclude_unpublished
boolean

Passing this param as false will return unpublished reviews. Default: true

exclude_syndicated
boolean

Set as true to exclude syndicated reviews. Default: false

exclude_negative_opinions
boolean

Set as false to include reviews with negative opinions. Default: true

exclude_grouped_reviews
boolean

Set as true to include reviews from grouped products. Default: false

 
Suggest Edits

Best Sentences

This endpoint automatically retrieves the very best sentences from your Yotpo reviews, so you can leverage the social proof of top customer testimonials at key conversion points throughout the buyer journey! You define the star-rating score, sentence length, and more!

 
posthttps://developers.yotpo.com/v2/account_id/best_sentences?access_token=access_token
{
    "minimum_sentence_length": 20,
    "maximum_sentence_length": 100,
    "maximum_number_of_sentences": 3,
    "start_date": "2017-01-13T00:00:00.000Z",
    "end_date": "2018-05-13T00:00:00.000Z",
    "external_product_ids": [],
    "product_groups": [],
    "product_collections": [],
    "minimum_score":4,
    "exclude_unpublished": true
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
    "review_sentences": [
        {
            "review_id": 47084341,
            "sentence": "this web site is a great place to get very cute bracelets, necklaces, or rings!",
            "external_product_id": "5420399557",
            "topics": [
                "necklace",
                "brackets",
                "place",
                "website"
            ]
        },
        {
            "review_id": 43408798,
            "sentence": "quality and value are great as well.",
            "external_product_id": "5420399557",
            "topics": [
                "quality",
                "value"
            ]
        },
        {
            "review_id": 42210491,
            "sentence": "i love your bracelets and the amazing color, designs and awareness.",
            "external_product_id": "5420399557",
            "topics": [
                "awareness",
                "company",
                "design",
                "colors"
            ]
        }
    ]
}

Path Params

account_id
string
required

Your Yotpo App Key

Query Params

access_token
string
required

Your Yotpo access_token. Click here to learn how to generate one

Body Params

minimum_sentence_length
int32

Define the minimum length of best sentences by character count. Must be less than the maximum_sentence_length. Default: 20 chars

maximum_sentence_length
int32

Define the maximum length of best sentences by character count. Must be greater than the minimum_sentence_length. Default: 100 chars

maximum_number_of_sentences
int32

Define the maximum number of sentences to return for this request. Default: 3 sentences

start_date
date

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

end_date
date

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

external_product_ids
array of strings

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

product_groups
string

The name of a product group.

product_collections
string

The name of a product collection

minimum_score
int32

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

exclude_unpublished
boolean

Passing this param as true will only return best sentences from published reviews.

 
Suggest Edits

Introduction to Webhooks

 

What is a webhook?

Webhooks are a useful tool that comes in handy for apps that want to execute code after a specific event occurs. For example, after a reviewer leaves a review or when the merchant creates a new product in their product catalog.

Instead of programming your app to make an API call every few minutes to check if a specific event has occurred, you can register webhooks, which send an HTTP POST request to update your app whenever the event occurs. This method is considerably more efficient than the traditional pooling method as it uses fewer API requests overall. This allows you to build smarter more robust apps which are updated in real-time.

Webhook Events

Yotpo allows you to configure a webhook to execute whenever:

:star2+: A review is created
:star2+: A new product is created

To view the webhook event types and object structure, see Create Webhook

Suggest Edits

Create Webhook

Create a webhook and parameters for a specific URL. Events can be review_create or product_create
Click here to view the object structure for each event

 
posthttps://developers.yotpo.com/v2/account_id/webhooks?access_token=access_token
{
 "url": "http://www.yourwebsite.com",
  "event_name": "review_create"
}
{
 "url": "http://www.yourwebsite.com",
  "event_name": "product_create"
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "pagination": null
}
{
    "error": "Exceptions::TooManyWebhooks",
    "code": 13
}

Path Params

account_id
string
required

Your account's API app key

Query Params

access_token
string
required

Your Yotpo access token. Click here to learn how to generate one

Body Params

url
string

Your site URL

event_name
string

The type of webhook params you can create. This can be review_create or product_create

 

You can only create one of each type of webhook.

Webhook Object Structure

Once you've successfully created a webhook, objects are returned according to the event_name created. Webhook events could be could be review_create and/or product_create and are structured as shown in the examples below:

{
  "event": "review_create",
  "data": {
    "id": "219",
    "source_app_key": "",
    "title": "Review Title",
    "content": "Review Content",
    "user_id": "209",
    "score": "5",
    "deleted": "false",
    "app_key": "StmYvzud6bHLtosn5k5DoGoA7M0kghzjMdH25DST",
    "created_at": "2018-02-20 14:12:13 UTC",
    "updated_at": "2018-02-20 14:12:13 UTC",
    "new": "true",
    "user_type": "AnonymousUser",
    "verified_buyer": "false",
    "archived": "false",
    "shop_owner": "false",
    "twitter_pushed": "0",
    "facebook_pushed": "0",
    "review_source_type_id": "1",
    "votes_up": "0",
    "votes_down": "0",
    "review_type_id": "1",
    "source_review_id": "",
    "sentiment": ""
  }
}
{
  "event": "product_create",
  "data": {
    "id": "109",
    "product_id": "109",
    "app_key": "StmYvzud6bHLtosn5k5DoGoA7M0kghzjMdH25DST",
    "domain_key": "12345619",
    "product_url": "http://www.yourwebsite.com/productpage",
    "created_at": "2018-02-20 14:15:36 UTC",
    "updated_at": "2018-02-20 14:15:36 UTC",
    "bread_crumbs": "",
    "blacklisted": "false",
    "product_price": "",
    "product_currency": "",
    "valid_url": "true",
    "validated_url_at": "",
    "slug": "",
    "reviews_me_enabled": "true",
    "reviews_me_product_name": "sticker",
    "reviews_me_product_price": "",
    "reviews_me_product_description": "",
    "category_id": "",
    "reviews_me_feed_limit_twitter": "",
    "reviews_me_feed_limit_pinterest": "",
    "reviews_me_feed_limit_instagram": "",
    "reviews_me_feed_limit_youtube": "",
    "reviews_me_feed_limit_reviews": "",
    "reviews_me_crawlable": "false",
    "purchases_count": "",
    "system_score": "",
    "last_purchased": ""
  }
}
Suggest Edits

All Webhooks

Retrieve a list of all webhooks created per account. Webhook events can be review_create or product_create.

 
gethttps://developers.yotpo.com/v2/account_id/webhooks?access_token=access_token
curl --request GET \
  --url 'https://developers.yotpo.com/v2/account_id/webhooks?access_token=access_token'
var request = require("request");

var options = { method: 'GET',
  url: 'https://developers.yotpo.com/v2/account_id/webhooks',
  qs: { access_token: 'access_token' } };

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

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

url = URI("https://developers.yotpo.com/v2/account_id/webhooks?access_token=access_token")

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://developers.yotpo.com/v2/account_id/webhooks?access_token=access_token");

xhr.send(data);
import requests

url = "https://developers.yotpo.com/v2/account_id/webhooks"

querystring = {"access_token":"access_token"}

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

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "pagination": null,
    "webhooks": {
        "webhooks": [
            {
                "id": 333,
                "webhook_event_id": 1,
                "webhook_event_name": "review_create",
                "url": "https://myapp.yotpo.com/users/B9Fnmid4rkwNVa9xCCB5WzbfjpeNWAisV7aTYj5f/yotpo_webhook"
            },
            {
                "id": 331,
                "webhook_event_id": 2,
                "webhook_event_name": "product_create",
                "url": "https://requestb.in/1n403m31"
            }
        ]
    }
}

Path Params

account_id
string
required

Your Yotpo access token. Click here to learn how to generate one

Query Params

access_token
string
required

Your Yotpo access token. Click here to learn how to generate one

 

All Webhooks - Response Attributes

Attribute
Description

id

The webhook id

webhook_event_id

The id of the webhook event

webhook_event_name

The name of the webhook event.
Could be review_create or product_create

url

The webhook URL

Suggest Edits

All Webhook Events

Retrieve data on webhook events including event names and their descriptions. Webhook events can be review_create or product_create.

 
gethttps://developers.yotpo.com/v2/account_id/webhook_events?access_token=access_token
curl --request GET \
  --url 'https://developers.yotpo.com/v2/account_id/webhook_events?access_token=access_token'
var request = require("request");

var options = { method: 'GET',
  url: 'https://developers.yotpo.com/v2/account_id/webhook_events',
  qs: { access_token: 'access_token' } };

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

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

url = URI("https://developers.yotpo.com/v2/account_id/webhook_events?access_token=access_token")

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://developers.yotpo.com/v2/account_id/webhook_events?access_token=access_token");

xhr.send(data);
import requests

url = "https://developers.yotpo.com/v2/account_id/webhook_events"

querystring = {"access_token":"access_token"}

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

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "pagination": null,
    "webhook_events": {
        "webhook_events": [
            {
                "name": "review_create",
                "description": "review created"
            },
            {
                "name": "product_create",
                "description": "product created"
            }
        ]
    }
}

Path Params

account_id
string
required

Your account's API app key

Query Params

access_token
string
required

Your Yotpo access token. Click here to learn how to generate one

 

All Webhook Events - Response Attributes

Attribute
Description

name

The webhook event name. Could be review_create or product_create

description

The webhook event description

Suggest Edits

Webhook By ID

Retrieve webhook URLs ,event names, and event IDs by webhook id.

 
gethttps://developers.yotpo.com/v2/account_id/webhooks/id?access_token=access_token
curl --request GET \
  --url 'https://developers.yotpo.com/v2/account_id/webhooks/id?access_token=access_token'
var request = require("request");

var options = { method: 'GET',
  url: 'https://developers.yotpo.com/v2/account_id/webhooks/id',
  qs: { access_token: 'access_token' } };

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

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

url = URI("https://developers.yotpo.com/v2/account_id/webhooks/id?access_token=access_token")

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://developers.yotpo.com/v2/account_id/webhooks/id?access_token=access_token");

xhr.send(data);
import requests

url = "https://developers.yotpo.com/v2/account_id/webhooks/id"

querystring = {"access_token":"access_token"}

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

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "pagination": null,
    "webhook": {
        "webhook": {
            "id": 0,
            "webhook_event_id": 1,
            "webhook_event_name": "review_create",
            "url": "https://myapp.yotpo.com/users/B9Fnmid4rkwNVa9xCCB5WzbfjpeNWAisV7aTYj5f/yotpo_webhook"
        }
    }
}

Path Params

account_id
string
required

Your account's API app key

id
string
required

The webhook id. Can be found using Retrieve All Webhooks

Query Params

access_token
string
required

Your Yotpo access token. Click here to learn how to generate one

 

Webhook by Webhook ID - Response Attributes

Attribute
Description

id

webhook_event_id

webhook_event_name

url

Suggest Edits

Update Webhook By ID

Update your webhook URL or event_name by webhook id.

 
puthttps://developers.yotpo.com/v2/account_id/webhooks/id?access_token=access_token
{
 "url": "http://www.hello.com",
  "event_name": "product_create"
}
A binary file was returned

Your OAuth2 token is incorrect or has expired

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

Path Params

account_id
string
required

Your account's API app key

id
string
required

The webhook ID. Can be found using Retrieve All Webhooks

Query Params

access_token
string
required

Your Yotpo access token. Click here to learn how to generate one

Body Params

url
string

Your site URL

event_name
string

The type of webhook params you wish to update. This can be review_create or product_create

 
Suggest Edits

Delete Webhook

Delete webhooks by webhook id. The id can be found using All Webhooks

 
deletehttps://developers.yotpo.com/v2/account_id/webhooks/id?access_token=access_token
curl --request DELETE \
  --url 'https://developers.yotpo.com/v2/account_id/webhooks/id?access_token=access_token'
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://developers.yotpo.com/v2/account_id/webhooks/id',
  qs: { access_token: 'access_token' } };

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

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

url = URI("https://developers.yotpo.com/v2/account_id/webhooks/id?access_token=access_token")

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://developers.yotpo.com/v2/account_id/webhooks/id?access_token=access_token");

xhr.send(data);
import requests

url = "https://developers.yotpo.com/v2/account_id/webhooks/id"

querystring = {"access_token":"access_token"}

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

print(response.text)
A binary file was returned

Your OAuth2 token is incorrect or has expired

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

Path Params

account_id
string
required

Your account's API app key

id
string
required

The webhook ID. Can be found using All Webhooks

Query Params

access_token
string
required

Your Yotpo access token. Click here to learn how to generate one