Yotpo Headless Integration Guide (API-Based)
This guide is for developers integrating Yotpo Reviews and Star Ratings via API, instead of using the default Yotpo widgets.
Ideal for custom headless storefronts (e.g., React, Vue, Hydrogen).
👉 For detailed API reference, see the UGC API Docs.
⭐ Get Star Rating (Bottom Line)
For retrieving your star rating via the API, you will want to make a GET request to the following bottomline endpoint. You can find parameters and response formats in our UGC API here.
Endpoint:
GET https://api-cdn.yotpo.com/products/{app_key}/{product_id}/bottomlinecurl --request GET \
--url https://api-cdn.yotpo.com/products/{app_key}/{product_id}/bottomline\
--header 'Content-Type: application/json' \
--header 'accept: application/json'Sample Response:
{
"status": {
"code": 200,
"message": "OK"
},
"response": {
"bottomline": {
"average_score": 4.52,
"total_reviews": 23
}
}
}React Example:
import { useEffect, useState } from 'react';
const useYotpoStarRating = (appKey: string, productId: string) => {
const [bottomline, setBottomline] = useState<{ average_score: number; total_reviews: number }>();
useEffect(() => {
fetch(`https://api-cdn.yotpo.com/products/${appKey}/${productId}/bottomline`)
.then((res) => res.json())
.then((data) => setBottomline(data.response.bottomline))
.catch(console.error);
}, [productId]);
return bottomline;
};Usage:
- Display the star rating per product.
- Show total review count: e.g.,
4.9 stars (756 reviews).
📝 Get Reviews for a Product
For retrieving the full reviews content via the API, you will want to make a GET request to the following reviews endpoint. Parameters and response formats are in our UGC API here.
Endpoint:
GET https://api-cdn.yotpo.com/v1/widget/{app_key}/products/{product_id}/reviews.jsoncurl --request GET \
--url https://api-cdn.yotpo.com/v1/widget/app_key/products/product_id/reviews.json \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'Sample Response:
{
"status": {
"code": 200,
"message": "OK"
},
"response": {
"pagination": {
"page": 2,
"per_page": 5,
"total": 9
},
"bottomline": {
"total_review": 11,
"average_score": 4.81818,
"star_distribution": {
"1": 0,
"2": 0,
"3": 0,
"4": 2,
"5": 9
},
"custom_fields_bottomline": null
},
"products": [
{
"id": 13,
"domain_key": "412790437",
"name": "Yotpo Mug",
"social_links": {
"facebook": "https://yotpo.com/go/r1wYoVa9",
"twitter": "https://yotpo.com/go/pg4zelyR",
"linkedin": "https://yotpo.com/go/6PvD9jsG",
"google_oauth2": "https://yotpo.com/go/srIsHCrr"
},
"embedded_widget_link": "https://yotpo.com/go/mjbdNtvQ",
"testimonials_product_link": "https://yotpo.com/go/45Vp7nuj",
"product_link": "https://yotpo.com/go/lnhRGFr0"
}
],
"product_tag": [],
"reviews": [
{
"id": 110,
"score": 5,
"votes_up": 1,
"votes_down": 0,
"content": "Great mug",
"title": "Perfect",
"sentiment": 0.852,
"created_at": "2016-06-16T12:16:05.354Z",
"verified_buyer": true,
"source_review_id": null,
"custom_fields": null,
"product_id": 13,
"is_incentivized": true,
"incentive_type": "free_product",
"images_data": [
{
"id": 13,
"thumb_url": "http://s3.amazonaws.com/yotpo-images-test/Review/29/13/square.jpeg?1457513657",
"original_url": "http://s3.amazonaws.com/yotpo-images-test/Review/29/13/original.jpeg?1457513657"
},
{
"id": 14,
"thumb_url": "http://s3.amazonaws.com/yotpo-images-test/Review/29/14/square.jpeg?1457513714",
"original_url": "http://s3.amazonaws.com/yotpo-images-test/Review/29/14/original.jpeg?1457513714"
}
],
"user": {
"user_id": 18,
"display_name": "John Doe",
"social_image": "https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png",
"user_type": "User",
"is_social_connected": 0
},
"comment": {
"id": 1336007,
"content": "Thanks for your review",
"created_at": "2017-05-03T07:19:25.734Z",
"comments_avatar": null
}
}
]
}
}{
"status": {
"code": 200,
"message": "OK"
},
"response": {
"pagination": {
"page": 1,
"per_page": 1,
"total": 82
},
"bottomline": {
"total_review": 82,
"average_score": 4.90244,
"total_organic_reviews": 0,
"organic_average_score": 0,
"star_distribution": {
"1": 1,
"2": 0,
"3": 0,
"4": 4,
"5": 77
},
"custom_fields_bottomline": null
},
"syndication_data": {},
"grouping_data": {},
"products": [
{
"id": 25066514,
"domain_key": "domain key",
"name": "White Sneakers",
"social_links": {
"facebook": "https://yotpo.com/go/3WyJHb1w",
"twitter": "https://yotpo.com/go/ssniEAg4",
"linkedin": "https://yotpo.com/go/rhstgPxO",
"google_oauth2": "https://yotpo.com/go/Sm9zyBzc"
},
"embedded_widget_link": "https://yotpo.com/go/0cS3riZz",
"testimonials_product_link": "https://yotpo.com/go/cFDmjHmG",
"product_link": "https://yotpo.com/go/ZgpCJJ3t",
"image_url": "https://dxogntwdcfq0i.cloudfront.net/Product/25066514/18972967/square.jpg?1507141113"
}
],
"product_tags": [],
"reviews": [
{
"id": 47405454,
"score": 5,
"votes_up": 0,
"votes_down": 0,
"content": "I like everything about the sneakers",
"title": "I love my new kicks",
"created_at": "2017-11-08T01:23:18.000Z",
"verified_buyer": true,
"source_review_id": null,
"sentiment": 0.526509,
"custom_fields": {
"--6688": {
"title": "Recommended",
"form_id": 7144,
"value": "Yes",
"field_type": "SingleChoice"
},
"--6689": {
"title": "Comfort",
"form_id": 7144,
"value": 5,
"field_type": "Rating"
},
"--6690": {
"title": "How was the delivery service?",
"form_id": 7144,
"field_type": "CustomerFreeText",
"value": "The package arrived intact and on time"
},
"--6691": {
"title": "What is your favorite thing about the shoes?",
"form_id": 7144,
"field_type": "ProductFreeText",
"value": "I love the fact that they are lightweight and comfy"
}
},
"product_id": 25066514,
"user": {
"user_id": 14229046,
"display_name": "Fred P.",
"social_image": null,
"user_type": "User",
"is_social_connected": 0
}
}
]
}
}React Example:
import { useEffect, useState } from 'react';
const useYotpoReviews = (
appKey: string,
productId: string,
perPage: number = 10,
page: number = 1
) => {
const [reviews, setReviews] = useState([]);
const [total, setTotal] = useState(0);
useEffect(() => {
fetch(`https://api-cdn.yotpo.com/v1/widget/${appKey}/products/${productId}/reviews.json?per_page=${perPage}&page=${page}`)
.then((res) => res.json())
.then((data) => {
setReviews(data.response.reviews);
setTotal(data.response.pagination.total);
})
.catch(console.error);
}, [productId, perPage, page]);
return { reviews, total };
};Usage:
- Show a list of reviews per product.
- Support pagination with
per_pageandpage. - Optional: use
star_distributionfor a rating histogram.
🌍 Get Site-wide Review Summary
To retrieve your star rating via the API, you will want to make a GET request to the following yotpo-site-reviews/bottomline endpoint. Parameters and response formats are in our UGC API here.
Endpoint:
GET https://api-cdn.yotpo.com/v1/widget/:app_key/products/yotpo_site_reviews/reviews.jsoncurl --request GET \
--url "https://api-cdn.yotpo.com/v1/widget/YOUR_APP_KEY/products/yotpo_site_reviews/reviews.json?per_page={per_page}&page={page}" \
--header 'Content-Type: application/json' \
--header 'accept: application/json'Sample Response:
{
"status": {
"code": 200,
"message": "OK"
},
"response": {
"pagination": {
"page": 1,
"per_page": 3,
"total": 226
},
"bottomline": {
"total_review": 0,
"average_score": 0,
"star_distribution": {
"1": 0,
"2": 0,
"3": 0,
"4": 11,
"5": 215
}
},
"products": [
{
"id": 13701,
"domain_key": "yotpo_site_reviews",
"name": "http://www.yotpo.com",
"social_links": {
"facebook": "https://staging.yotpo.com/go/osCcXZ59",
"twitter": "https://staging.yotpo.com/go/wfmwZq1n",
"linkedin": "https://staging.yotpo.com/go/suxQA3tX",
"google_oauth2": "https://staging.yotpo.com/go/eryV9Etw"
},
"embedded_widget_link": "http://www.yotpo.com",
"testimonials_product_link": "https://staging.yotpo.com/go/94DY1dA7"
}
],
"reviews": [
{
"id": 28101,
"score": 5,
"votes_up": 7,
"votes_down": 1,
"content": "I Love everything about Yotpo!! Phenomenal customer service plus the product selection is enormous... Anything you could imagine...wait...AND MORE!!",
"title": "Best Store Hands Down",
"sentiment": 0.989,
"created_at": "2013-03-06T23:08:21.634Z",
"verified_buyer": false,
"product_id": 13701,
"user": {
"user_id": 19541,
"display_name": "Peter K.",
"social_image": "https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png",
"user_type": "User",
"is_social_connected": 0
}
},
{
"id": 28102,
"score": 5,
"votes_up": 7,
"votes_down": 1,
"content": "This is my first time online shopping at Yotpo, but i did shop in store several times and i found this store price is way cheaper than any other Ny gift store in Manhattan. My purchase is quite a lot, with assorted, but Yotpo could handle and shipped it very quick, with neat package. I already recommend this store to all of my friends. If i could make a suggestion, maybe Yotpo could update the online product for more, because i couldn't find some of the product i bought in store, on line. Thank you",
"title": "Great Selection, Great Prices",
"created_at": "2013-03-06T23:09:24.472Z",
"verified_buyer": false,
"product_id": 13701,
"user": {
"user_id": 19567,
"display_name": "Ria A.",
"social_image": "https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png",
"user_type": "User",
"is_social_connected": 0
}
},
{
"id": 29879,
"score": 5,
"votes_up": 4,
"votes_down": 0,
"content": "Good price, good product and very fast delivery. would buy again",
"title": "Triple Crown",
"sentiment": 0.758,
"created_at": "2013-03-11T18:45:44.635Z",
"verified_buyer": false,
"product_id": 13701,
"user": {
"user_id": 20852,
"display_name": "Steve E.",
"social_image": "https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png",
"user_type": "User",
"is_social_connected": 0
}
}
]
}
}React Example:
import { useEffect, useState } from 'react';
const useYotpoSiteReviews = (appKey: string) => {
const [bottomline, setBottomline] = useState<{ average_score: number; total_reviews: number } | null>(null);
useEffect(() => {
fetch(`https://api.yotpo.com/products/${appKey}/yotpo_site_reviews/bottomline`)
.then((res) => res.json())
.then((data) => setBottomline(data.response.bottomline))
.catch(console.error);
}, []);
return bottomline;
};🛠 Developer Notes
- All API responses are CDN-accelerated and cached for performance.
user.display_namemay be empty if the user is anonymous.- Use
images_datato show user-uploaded photos. verified_buyerhelps identify real customers.- Consider lazy-loading additional pages for better UX.
If you're using any of the following frameworks, it's best to call these APIs from your backend:
- Next.js
- Shopify Hydrogen
- Vue Storefront
- Gatsby
Updated 17 days ago