Table of Contents

    API

    Mock Server

    Use this URL to access a mockup of the API server. Your traffic will be recorded and compared to the documentation. You'll find your traffic analysis in the inspector or directly here in the documentation, right next to each resource.

Yotpo API

Yotpo Social Reviews - RESTful API documentation.

contact: omri@yotpo.com

Some Guidelines:

  1. In Yotpo we have Users and Accounts. Each user, usually, has one account but can have more.
  2. Each such account, is described using an app_key. You will need this app_key, for most actions in the API.
  3. Most of the Yotpo API calls are restriced to authenticated users only, and require a utoken (user token).

User Resources

Resources related to users

POST

/users

Create new user email in the system. Confirmation email will be sent from Yotpo to the provided email address.

Required

email - the email of the user
display_name - the name of the user
password - the password of the user
url - main url to the shop

Note: Make sure to save the response of this call, hence the secret and the app_key cannot be obtained otherwise.

Response

200 (OK)
Content-Type: application/json
{
  "status" : {
    "code" : 200,
    "message" : "OK"
  },
  "response" : {
    "user_id" : 11,
    "token" : "NkLHMUYXnkIRrb3UUVpCtI0EIHconaoFEMzgpYXt",
    "app_key" : "a3lmMnC3u4SNmz0ZcHf3lODeIYM9LEQwtTWXRdDP",
    "secret" : "NumuadvlCGOTwnCCvY5BRAhGib1LTCFptYxfvebm"
  }
}

POST

/oauth/token

Create an access token for an existing user (AKA utoken)

Required

client_id - the app_key that was recieved on the user signup 
client_secret - the secret that was recieved on the user signup
grant_type - allowed values: client_credentials

Note: the response contains the access_token, later related to as utoken

Response

200 (OK)
Content-Type: application/json
{
  "access_token" : "DUGKea0thVDL2muWzMAd7mYlkni46cJWhiX9tGTF",
  "token_type" : "bearer"
}

POST

/apps/{app_key}/account_platform

Create account_platform for your newly created account

Required

account_platform
    shop_domain - domain of the shop, starts with http (important)
    platform_type_id - allowed values: 
        1 - shopify
        2 - Other
        3 - bigcommerce
        4 - 3dcart
        5 - magento
        6 - volusion
        7 - shoppingcartelite
        8 - prestashop
        9 - cscart
        10 - opencart
        11 - ebay
        12 - woocommerce
        13 - storenvy
        17 - tictail
        19 - symphony
        20 - commerce_guys
        21 - go_daddy_commerce
        22 - seoshop
        23 - zepo
utoken - authentication token for the user    

Response

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

GET

/users/b2blogin.json?app_key={app_key}&secret={secret}

Get sign in URL for www.yotpo.com - in order to sign in user to his Yotpo admin console, we must generate the user a link.

Required

app_key - 
secret - 

Note: if you remove the .json from the URI, then you will be redirect directly instead of getting the url. to the signin_url you can add the partner parameter in order to get partner specific layout.

Response

200 (OK)
Content-Type: application/json
{
  "status" : {
    "code" : 200,
    "message" : "OK"
  },
  "response" : {
    "code" : "pStQjjzuiUfRGX0EMhqi",
    "signin_url" : "https://www.yotpo.com/callbacks/login?code=pStQjjzuiUfRGX0EMhqi"
  }
}

Mini Site and SEO Resources

GET

/apps/{app_key}/subomain_check/{subdomain}?utoken={utoken}

Find if the xxxx.yotpo.me domain is valid

Response

200 (OK)
Content-Type: application/json
{
  "status" : {
    "code" : 200,
    "message" : "OK"
  },
  "response" : {
    "subdomain" : {
      "available" : "true",
      "subdomain" : "shalom1"
    }
  }
}

PUT

/apps/{app_key}

Update account with SEO and minisite parameters (this is a specific use of a more general call)

Response

200 (OK)
Content-Type: application/json
{
  "status" : {
    "code" : 200,
    "message" : "OK"
  },
  "response" : {
    "app" : {
      "app_key" : "1sYGo0GzHi8vG7JYja14tpgMQw4CWbcyg9xEjlVX",
      "domain" : "http://omricohen.me",
      "minisite_subdomain" : "shalom1",
      "minisite_cname" : "reviews.mydomain.com",
      "minisite_website" : "http://www.mydomain.com",
      "minisite_website_name" : "My Domain Awesome Shop!",
      "referal" : "",
      "active" : true,
      "auto_publish" : true,
      "minisite_subdomain_active" : false,
      "account_type" : {
        "id" : 1,
        "name" : "small",
        "description" : "dummy description",
        "price" : 14.9
      },
      "account_socials" : [ ],
      "account_platform" : {
        "id" : 7,
        "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
      },
      "bills" : [ ],
      "users" : [ {
        "id" : 15,
        "display_name" : "Omri Cohen",
        "slug" : "omri-cohen--9"
      } ],
      "reminders" : [ ],
      "custom_design" : false,
      "created_at" : "2012-12-11T10:54:31Z",
      "updated_at" : "2012-12-11T11:21:25Z",
      "auto_login_popup" : false
    }
  }
}

Mail After Purchase

POST

/apps/{app_key}/purchases

Ping on an ordered that took place

Mandatory elements:

email, customer_name, product_sku, order_id, product_name, product_url, app_key, utoken, platform

Response

200 (OK)
Content-Type: application/json
{
  "code" : 200,
  "message" : "OK"
}

POST

/apps/{app_key}/purchases/mass_create

Push a list of orders

Mandatory elements:

email, customer_name, product_sku, order_id, product_name, product_url, app_key, utoken, platform

Response

200 (OK)
Content-Type: application/json
{
  "code" : 200,
  "message" : "OK"
}

GET

/apps/{app_key}/purchases?utoken={utoken}&since_id={since_id}&since_date={since_date}&page={page}&count={count}

Get a list of all orders in the system for a certain account

Mandatory params:

utoken - authentication token

Optional params:

callback - jsonp call back function 
page - page number 
count - orders per page
since_date - date in the format of YYYY-MM-DD to get all orders that ware created from that date and on.
since_id - the id from which to start getting the elements

Response

200 (OK)
Content-Type: application/json
{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response": {
        "purchases": [
            {
                "id": 80,
                "user_email": "test@use.com",
                "user_name": "lamba",
                "product_sku": "123",
                "order_id": "100",
                "product_name": "ttt",
                "product_url": "http://www.google.com",
                "order_date": "2013-05-06T16:45:40Z",
                "product_description": "lalalala",
                "product_image": "http://www.google.com/images/srpr/logo4w.png",
                "delivery_date": "2013-05-19T21:00:00Z",
                "created_at": "2013-05-20T16:45:40Z"
            },
            {
                "id": 980,
                "user_email": "test1@use.com",
                "user_name": "John Doe",
                "product_sku": "123",
                "order_id": "1000",
                "product_name": "ttt",
                "product_url": "http://www.google.com",
                "order_date": "2013-05-06T16:46:04Z",
                "product_description": "lalalala",
                "product_image": "http://www.google.com/images/srpr/logo4w.png",
                "delivery_date": "2013-05-19T21:00:00Z",
                "created_at": "2013-05-20T16:46:04Z"
            }
        ],
        "total_purchases": 1001
    }
}

POST

/apps/{app_key}/reminders/send_test_email

Test Mail After Purchase This requests sends the email template with all the placeholders and not real data just the things that will be common in all emails that will be sent

Params:

utoken (required) - the users utoken
app_key (required) - the app key of the account
email (optional) - the email to which the test should be sent

Response

200 (OK)
Content-Type: application/json; charset=utf-8
Server: nginx/1.2.6
Date: Sun, 10 Feb 2013 15:31:40 GMT
Transfer-Encoding: chunked
Connection: keep-alive
Status: 200 OK
X-UA-Compatible: IE=Edge,chrome=1
ETag: "a873ac57132fed9ae7f368e3c8c85724"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 3cd56ba57b66db1b48e0a030314df1cc
X-Runtime: 0.019957
X-Rack-Cache: invalidate, pass
Strict-Transport-Security: max-age=2592000; includeSubdomains
{
  "status" : {
    "code" : 200,
    "message" : "OK"
  }
}

Bottom Line for all products

GET

/apps/{app_key}/bottom_lines?utoken={utoken}&since_date={since_date}&since_id={since_id}

Get a list of all products and their bottom line

Required params:

app_key - the app key of the account
utoken - the token of a shop owner 

Optional params:

since_date - date in the format of YYYY-MM-DD to get all reviews that ware created from that date and on.
since_id - the id from which to get the data
callback - jsonp call back function 

Response

200 (OK)
Content-Type: application/json
{
  "status" : {
    "code" : 200,
    "message" : "OK"
  },
  "response" : {
    "bottomlines" : [ {
      "domain_key" : "62050632",
      "product_score" : "3.45",
      "total_reviews" : 11
    }, {
      "domain_key" : "62050052",
      "product_score" : "3.0",
      "total_reviews" : 3
    }, {
      "domain_key" : "62050122",
      "product_score" : "4.64",
      "total_reviews" : 11
    }, {
      "domain_key" : "73503772",
      "product_score" : "4.76",
      "total_reviews" : 17
    }, {
      "domain_key" : "92431514",
      "product_score" : "4.52",
      "total_reviews" : 25
    }]
  }
}

Post a review to Yotpo

GET

/reviews/dynamic_create.json?appkey={app_key}&sku={product_id}&domain={shop_domain}&product_title={product_title}&product_description={product_description}&product_url={product_url}&product_image_url={full_product_image_url}&display_name={user_display_name}&email={user_email}&review_content={review_body}&review_title={review_title}&review_score={review_score}&callback={js_callback_name}

Create new review and its product, if it is not existed already

Required params:

appkey - the app key of the account
sku - id of the product in the website, should be consistent with the product_id that is used in the product page
domain - domain of the website
product_title - title of the product
product_description - short description of the product (up to 500 characters)
product_url - full url (including domain) of the product
product_image_url - full product image url (including domain) of the product
display_name - display name of the user
email - email of the user
review_content - the body of the review itself
review_title - the title of the review
review_score - the score of the review (integer between 1-5)
callback - jsonp call back function 

Response

200 (OK)
Content-Type: application/json
{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "response": {
    "reviews": [
      {
        "id": 57707,
        "content": "Another trial",
        "title": "Trial Review",
        "score": 4,
        "user": {
          "id": 24489,
          "display_name": "Omi",
          "slug": null,
          "social_image": "https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png",
          "bio": null,
          "score": null,
          "badges": null
        },
        "user_type": "AnonymousUser",
        "users": [],
        "products": [
          {
            "Location_idx": [
              0,
              0
            ],
            "Product": {
              "product_url": "http://shop.yotpo.com/products/amazing-yotpo-poster",
              "id": 239,
              "name": "Amazing Yotpo poster",
              "slug": "amazing-yotpo-poster",
              "shorten_url": "https://yotpo.com/go/3urd",
              "images": [
                {
                  "id": 200,
                  "image_url": "http://ddcfq0gxiontw.cloudfront.net/Product/239/200/square.png_3F848?1336834622"
                }
              ],
              "social_network_links": {
                "facebook": "https://yotpo.com/go/hxp2",
                "twitter": "https://yotpo.com/go/hxp3",
                "linkedin": "https://yotpo.com/go/hxp4",
                "google_oauth2": "https://yotpo.com/go/hxp5"
              }
            }
          }
        ],
        "votes_up": 0,
        "votes_down": 0,
        "user_vote": 0,
        "created_at": "2013-04-17T14:33:04Z",
        "deleted": false,
        "new": true,
        "distance": 999,
        "verified_buyer": false,
        "archived": false,
        "social_pushed": false
      }
    ]
  }
}

Get Reviews for a specific product

GET

/products/{app_key}/{sku}/reviews?callback={pjson_callback}&page={page}&count={count}&since_date={since_date}

Given product_sku (unique identifier of the product within your domain), and a app_key, the call returns all the reviews of this product.

Required params:

appkey - the app key of the account
sku - id of the product in the website, should be consistent with the product_id that is used in the product page.

Optional params:

callback - jsonp call back function 
page - page number 
count - reviews per page
since_date - date in the format of YYYY-MM-DD to get all reviews that ware created from that date and on.
since_id - the id from which to start getting the elements

Response

200 (OK)
Content-Type: application/json
{
   "status":{
      "code":200,
      "message":"OK"
   },
   "response":{
      "total_reviews":10,
      "reviews":[
         {
            "id":72714,
            "content":"I got it for my boyfriend and he loves it! We just wish the lens cap was removable so that he could keep it on all week and use it for work, instead he takes it off during the week and puts it on during the weekend.  But we love the cool/fun pictures it's able to take and the fact that you can just take a regular picture too. ",
            "title":"So fun!",
            "score":5,
            "user":{
               "id":45416,
               "display_name":"Taylor R.",
               "slug":"taylor-r--3",
               "social_image":"https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png",
               "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"
                  }
               ]
            },
            "user_type":"User",
            "users":[],
            "products":[
               {
                  "Location_idx":[
                     0,
                     0
                  ],
                  "Product":{
                     "product_url":"http://shop.example.com/products/holga-iphone-5-lens-filter-case-kit-slft-ip5",
                     "id":1314,
                     "name":"Holga iPhone 5 Lens Filter and Case Kit SLFT-IP5",
                     "slug":"holga-iphone-5-lens-filter-and-case-kit-slft-ip5",
                     "shorten_url":"https://yotpo.com/go/41is",
                     "images":[
                        {
                           "id":1136,
                           "image_url":"http://ddcfq0gxiontw.cloudfront.net/Product/1314/1136/square.jpg_3F1144?1351608907"
                        }
                     ],
                     "social_network_links":{
                        "facebook":"https://yotpo.com/go/j5a8",
                        "twitter":"https://yotpo.com/go/j5a9",
                        "linkedin":"https://yotpo.com/go/j5aa",
                        "google_oauth2":"https://yotpo.com/go/j5ab"
                     },
                     "facebook_testemonials_page_product_url":"https://yotpo.com/go/108w0"
                  }
               }
            ],
            "votes_up":0,
            "votes_down":0,
            "user_vote":0,
            "created_at":"2013-04-28T13:46:42Z",
            "deleted":false,
            "new":true,
            "distance":999,
            "verified_buyer":true,
            "archived":false,
            "facebook_pushed":true,
            "twitter_pushed":false,
            "social_pushed":true,
            "account":{
               "id":1176,
               "domain":"http://shop.example.com"
            }
         },
         {
            "id":57701,
            "content":"A really fun purchase. Would definitely recommend it to others! My only concern is that the lens cap is easily misplaced.",
            "title":"Great fun lenses for my phone",
            "score":4,
            "user":{
               "id":38702,
               "display_name":"Kate F.",
               "slug":"kate-f",
               "social_image":"https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png",
               "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"
                  }
               ]
            },
            "user_type":"User",
            "users":[ ],
            "products":[
               {
                  "Location_idx":[
                     0,
                     0
                  ],
                  "Product":{
                     "product_url":"http://shop.example.com/products/holga-iphone-5-lens-filter-case-kit-slft-ip5",
                     "id":1314,
                     "name":"Holga iPhone 5 Lens Filter and Case Kit SLFT-IP5",
                     "slug":"holga-iphone-5-lens-filter-and-case-kit-slft-ip5",
                     "shorten_url":"https://yotpo.com/go/41is",
                     "images":[
                        {
                           "id":1136,
                           "image_url":"http://ddcfq0gxiontw.cloudfront.net/Product/1314/1136/square.jpg_3F1144?1351608907"
                        }
                     ],
                     "social_network_links":{
                        "facebook":"https://yotpo.com/go/j5a8",
                        "twitter":"https://yotpo.com/go/j5a9",
                        "linkedin":"https://yotpo.com/go/j5aa",
                        "google_oauth2":"https://yotpo.com/go/j5ab"
                     },
                     "facebook_testemonials_page_product_url":"https://yotpo.com/go/108w0"
                  }
               }
            ],
            "votes_up":0,
            "votes_down":0,
            "user_vote":0,
            "created_at":"2013-04-17T14:24:12Z",
            "deleted":false,
            "new":true,
            "distance":999,
            "verified_buyer":true,
            "archived":false,
            "facebook_pushed":false,
            "twitter_pushed":false,
            "social_pushed":false,
            "account":{
               "id":1176,
               "domain":"http://shop.example.com"
            }
         }
      ]
   }
}

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

GET

/products/{app_key}/{sku}/bottomline?callback={pjson_callback}

Given product_sku (unique identifier of the product within your domain), and a app_key, the call returns the total reviews and average score of this product.

Required params:

appkey - the app key of the account
sku - id of the product in the website, should be consistent with the product_id that is used in the product page

Optional params: callback - jsonp call back function

Response

200 (OK)
Content-Type: application/json
{
   "status":{
      "code":200,
      "message":"OK"
   },
   "response":{
      "bottomline":{
         "average_score":4.52,
         "total_reviews":23
      }
   }
}