---
updatedAt: 2026-10-29T08:22:22.000Z
agentTools:
  projectIndex: https://docs.yotpo.com/llms.txt
---

# Search product reviews

Search or filter storefront reviews for a specific product.

> 👍 How to use this endpoint
>
> * No access token is needed. This is a public endpoint served from Yotpo's CDN (`api-cdn.yotpo.com`).
> * Data is returned with a delay of up to 3 hours, so new or updated reviews can take up to 3 hours to appear.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Reviews storefront API V3",
    "version": "3.0",
    "description": "CDN-backed endpoints for storefront display. Base URL https://api-cdn.yotpo.com"
  },
  "servers": [
    {
      "url": "https://api-cdn.yotpo.com",
      "description": "CDN-backed API server for storefront access"
    }
  ],
  "security": [],
  "paths": {
    "/v3/storefront/store/{storeId}/product/{productId}/reviews": {
      "post": {
        "summary": "Search product reviews",
        "description": "Search or filter storefront reviews for a specific product.",
        "operationId": "storefront-product-reviews-search",
        "parameters": [
          {
            "name": "storeId",
            "in": "path",
            "required": true,
            "description": "Store identifier",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "productId",
            "in": "path",
            "required": true,
            "description": "Product identifier",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            },
            "description": "Page number, starting from 1. Default: 1."
          },
          {
            "name": "perPage",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 150,
              "default": 5
            },
            "description": "Number of results per page. Default: 5. Values above 150 are capped at 150."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "smart",
                "date",
                "badge",
                "images",
                "rating"
              ]
            },
            "description": "Sort order for reviews. Unrecognized values are ignored. `smart` applies Yotpo's AI-powered Smart Sorting, which puts the most important reviews first. Smart Sorting is part of the Pro and Premium plans."
          },
          {
            "name": "direction",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ]
            },
            "description": "Sort direction: `asc` or `desc`. Unrecognized values are ignored."
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Language code (for example `fr`) to return translated review content. Unsupported codes return the original text.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "examples": {
                "Filter by rating and topic": {
                  "value": {
                    "scores": [
                      5
                    ],
                    "topicNames": [
                      "quality"
                    ]
                  }
                },
                "Search text, newest first": {
                  "value": {
                    "freeTextSearch": "comfortable",
                    "sortings": [
                      {
                        "sortBy": "date",
                        "ascending": false
                      }
                    ]
                  }
                }
              },
              "schema": {
                "type": "object",
                "required": [],
                "description": "Filters to apply. All fields are optional; an empty body returns all reviews.",
                "properties": {
                  "ids": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    },
                    "description": "Review IDs to return."
                  },
                  "scores": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": 1,
                      "maximum": 5
                    },
                    "description": "Star ratings to include, for example `[4, 5]`."
                  },
                  "topicNames": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Topics mentioned in the review. Get available topics from Retrieve product data with `include=topics`."
                  },
                  "freeTextSearch": {
                    "type": "string",
                    "description": "Free-text search across review content."
                  },
                  "pictured": {
                    "type": "boolean",
                    "description": "Set to `true` to return only reviews with images or videos."
                  },
                  "picturesPerReview": {
                    "type": "integer",
                    "description": "Maximum number of images returned per review. Does not filter reviews."
                  },
                  "country": {
                    "type": "string",
                    "description": "Two-letter reviewer country code, for example `US`. Get available countries from Retrieve product data with `include=countries`."
                  },
                  "sortings": {
                    "type": "array",
                    "description": "Sort order. An unsupported `sortBy` value returns no results.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "sortBy": {
                          "type": "string",
                          "description": "Field to sort by, for example `date`."
                        },
                        "ascending": {
                          "type": "boolean",
                          "description": "`true` for ascending order."
                        }
                      }
                    }
                  },
                  "crfs": {
                    "type": "array",
                    "description": "Custom question (custom review form) answers to filter by.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "questionId": {
                          "type": "integer",
                          "description": "Custom question ID."
                        },
                        "answers": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Answer values to match."
                        },
                        "displayAnswers": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Answer labels as displayed."
                        }
                      }
                    }
                  },
                  "orders": {
                    "type": "array",
                    "description": "Order metadata filters.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "questionId": {
                          "type": "string",
                          "description": "Order question ID."
                        },
                        "subType": {
                          "type": "string",
                          "description": "Question subtype."
                        },
                        "question": {
                          "type": "string",
                          "description": "Question text."
                        },
                        "answers": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Answer values to match."
                        }
                      }
                    }
                  },
                  "metadata": {
                    "type": "array",
                    "description": "Review metadata filters.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "fieldType": {
                          "type": "string",
                          "description": "Metadata field type."
                        },
                        "question": {
                          "type": "string",
                          "description": "Metadata field name."
                        },
                        "answers": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Values to match."
                        }
                      }
                    }
                  },
                  "productVariants": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    },
                    "description": "Variant attributes to filter by, as name/value pairs."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "foundFilteredReviews": {
                      "type": [
                        "boolean",
                        "null"
                      ],
                      "description": "`true` when the filters matched reviews; `null` when no filter was applied or nothing matched."
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "page": {
                          "type": "integer",
                          "description": "Current page number."
                        },
                        "perPage": {
                          "type": "integer",
                          "description": "Results per page."
                        },
                        "total": {
                          "type": "integer",
                          "description": "Total number of reviews across all pages."
                        }
                      },
                      "description": "Pagination details."
                    },
                    "reviews": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer",
                            "description": "Review ID."
                          },
                          "score": {
                            "type": "integer",
                            "description": "Star rating, 1 to 5."
                          },
                          "votesUp": {
                            "type": "integer",
                            "description": "Number of helpful votes."
                          },
                          "votesDown": {
                            "type": "integer",
                            "description": "Number of unhelpful votes."
                          },
                          "content": {
                            "type": "string",
                            "description": "Review text."
                          },
                          "title": {
                            "type": "string",
                            "description": "Review title."
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time",
                            "description": "When the review was created (ISO 8601)."
                          },
                          "verifiedBuyer": {
                            "type": "boolean",
                            "description": "`true` when the reviewer is a verified buyer."
                          },
                          "sentiment": {
                            "type": "number",
                            "description": "Sentiment score of the review text, from 0 (negative) to 1 (positive)."
                          },
                          "isIncentivized": {
                            "type": "boolean",
                            "description": "`true` when the reviewer received an incentive for writing the review."
                          },
                          "incentiveType": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Type of incentive: `free_product`, `coupon`, `loyalty_points`, `paid_promotion`, `employee_review`, or `other`. `null` when the review is not incentivized."
                          },
                          "isShop": {
                            "type": "boolean"
                          },
                          "topics": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "additionalProperties": {
                              "type": "object",
                              "description": "A topic mention.",
                              "properties": {
                                "name": {
                                  "type": "string",
                                  "description": "Topic name."
                                },
                                "sentence": {
                                  "type": "string",
                                  "description": "The sentence from the review that mentions the topic."
                                }
                              }
                            },
                            "description": "Topics mentioned in this review, keyed by topic, or `null`."
                          },
                          "fieldsHighlights": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "description": "When you search with `freeTextSearch`, the matched search terms per review field, for example `{\"review_content\": [\"leather\"]}`. Otherwise `null`.",
                            "properties": {
                              "review_content": {
                                "type": "array",
                                "description": "Search terms found in the review text.",
                                "items": {
                                  "type": "string",
                                  "description": "A matched search term."
                                }
                              }
                            }
                          },
                          "customFields": {
                            "description": "Answers to custom questions, keyed by question ID (for example `--6688`), or `null`. Each answer has `title`, `form_id`, `value`, and `field_type`."
                          },
                          "metadata": {
                            "type": "array",
                            "items": {},
                            "description": "Metadata attached to the review (for example order, customer, and product details)."
                          },
                          "videosData": {
                            "description": "Videos uploaded with the review, or `null`."
                          },
                          "imagesData": {
                            "description": "Images uploaded with the review, or `null`."
                          },
                          "comment": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "description": "The store's public reply to the review, or `null`.",
                            "properties": {
                              "commentsAvatar": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Avatar image URL shown on the reply, or `null`."
                              },
                              "content": {
                                "type": "string",
                                "description": "Reply text."
                              },
                              "createdAt": {
                                "type": "string",
                                "description": "When the reply was posted."
                              },
                              "displayName": {
                                "type": "string",
                                "description": "Name shown on the reply (your store name)."
                              },
                              "id": {
                                "type": "integer",
                                "description": "Reply ID."
                              }
                            }
                          },
                          "user": {
                            "type": "object",
                            "properties": {
                              "userId": {
                                "type": "integer",
                                "description": "Reviewer's Yotpo user ID."
                              },
                              "socialImage": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Reviewer's profile image URL, or `null`."
                              },
                              "userType": {
                                "type": "string",
                                "description": "Reviewer account type: `User` or `AnonymousUser`."
                              },
                              "isSocialConnected": {
                                "type": "integer",
                                "description": "`1` when the reviewer connected a social account, otherwise `0`."
                              },
                              "displayName": {
                                "type": "string",
                                "description": "Reviewer's display name. Can be empty for anonymous reviewers."
                              }
                            },
                            "description": "The reviewer."
                          },
                          "sourceReviewId": {
                            "description": "ID of the original review when this review was syndicated from another store; otherwise `null`."
                          },
                          "syndicationData": {},
                          "groupingData": {},
                          "bundledProductData": {},
                          "country": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "code": {
                                "type": "string",
                                "description": "Two-letter country code, for example `US`."
                              },
                              "label": {
                                "type": "string",
                                "description": "Display label."
                              }
                            },
                            "description": "Reviewer's country, or `null`."
                          },
                          "productVariants": {
                            "description": "Product variant the review was written for, or `null`."
                          },
                          "language": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Language code of the returned review content, for example `en`. When you set `lang` and the review was translated, this is the requested language."
                          },
                          "translatedLanguage": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "When `lang` is set and the review was translated, the language the review was originally written in. Otherwise `null`."
                          }
                        },
                        "description": "A review."
                      },
                      "description": "Reviews on this page."
                    },
                    "products": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer",
                            "description": "Yotpo's internal product ID. Reviews reference it in `product_id`."
                          },
                          "domainKey": {
                            "type": "string",
                            "description": "Your product ID, as sent to Yotpo (the product ID in the request)."
                          },
                          "name": {
                            "type": "string",
                            "description": "Product name."
                          },
                          "socialLinks": {
                            "type": "object",
                            "properties": {
                              "linkedin": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Share link for LinkedIn, or `null`."
                              },
                              "facebook": {
                                "type": "string",
                                "description": "Share link for Facebook."
                              },
                              "twitter": {
                                "type": "string",
                                "description": "Share link for X (Twitter)."
                              },
                              "googleOauth2": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Share link for Google, or `null`."
                              }
                            },
                            "description": "Yotpo short links for sharing the product, keyed by social network. A network is `null` when sharing to it is not set up."
                          },
                          "embeddedWidgetLink": {
                            "type": "string",
                            "description": "Yotpo short link (`yotpo.com/go/...`) to the product's embedded reviews widget."
                          },
                          "testimonialsProductLink": {
                            "type": "string",
                            "description": "Yotpo short link (`yotpo.com/go/...`) to the product's testimonials page."
                          },
                          "productLink": {
                            "type": "string",
                            "description": "Yotpo short link (`yotpo.com/go/...`) to the product page."
                          },
                          "imageUrl": {
                            "type": "string",
                            "description": "Product image URL, or `null`."
                          },
                          "productTags": {
                            "description": "Tags assigned to the product in Yotpo, or `null`."
                          }
                        },
                        "description": "A product."
                      },
                      "description": "Products that the returned reviews belong to."
                    },
                    "groupingData": {
                      "description": "Review grouping (syndication) data for the product. Empty object when the product is not part of a group."
                    },
                    "syndicationData": {
                      "description": "Data about reviews syndicated from other stores. Empty object when no reviews are syndicated."
                    },
                    "productTags": {
                      "description": "Tags assigned to the product in Yotpo, or `null`."
                    }
                  }
                },
                "examples": {
                  "Result": {
                    "value": {
                      "foundFilteredReviews": true,
                      "pagination": {
                        "page": 1,
                        "perPage": 2,
                        "total": 152
                      },
                      "reviews": [
                        {
                          "id": 85989153,
                          "score": 5,
                          "votesUp": 0,
                          "votesDown": 0,
                          "content": "Great quality, easy to use and slim.",
                          "title": "Great wallet",
                          "createdAt": "2019-04-01T00:00:00",
                          "verifiedBuyer": true,
                          "sentiment": 0.986707,
                          "isIncentivized": false,
                          "incentiveType": null,
                          "isShop": false,
                          "topics": {
                            "wallet": {
                              "name": "wallet",
                              "sentence": "Great wallet"
                            },
                            "quality": {
                              "name": "quality",
                              "sentence": "Great quality, easy to use and slim."
                            }
                          },
                          "fieldsHighlights": null,
                          "customFields": null,
                          "metadata": [],
                          "videosData": null,
                          "imagesData": null,
                          "comment": null,
                          "user": {
                            "userId": 29236491,
                            "socialImage": null,
                            "userType": "AnonymousUser",
                            "isSocialConnected": 0,
                            "displayName": ""
                          },
                          "sourceReviewId": null,
                          "syndicationData": null,
                          "groupingData": null,
                          "bundledProductData": null,
                          "country": {
                            "code": "US",
                            "label": "🇺🇸 United States"
                          },
                          "productVariants": null,
                          "language": null,
                          "translatedLanguage": null
                        },
                        {
                          "id": 85989147,
                          "score": 5,
                          "votesUp": 0,
                          "votesDown": 0,
                          "content": "Very happy with my purchase. Made to last a lifetime of daily use. Quality is outstanding and delivery was timely. You obviously care about what you produce.",
                          "title": "Quality product",
                          "createdAt": "2019-03-27T00:00:00",
                          "verifiedBuyer": true,
                          "sentiment": 0.982011,
                          "isIncentivized": false,
                          "incentiveType": null,
                          "isShop": false,
                          "topics": {
                            "shipping": {
                              "name": "shipping",
                              "sentence": "Quality is outstanding and delivery was timely."
                            },
                            "purchase": {
                              "name": "purchase",
                              "sentence": "Very happy with my purchase."
                            },
                            "quality": {
                              "name": "quality",
                              "sentence": "Quality is outstanding and delivery was timely."
                            }
                          },
                          "fieldsHighlights": null,
                          "customFields": null,
                          "metadata": [],
                          "videosData": null,
                          "imagesData": null,
                          "comment": null,
                          "user": {
                            "userId": 29236487,
                            "socialImage": null,
                            "userType": "AnonymousUser",
                            "isSocialConnected": 0,
                            "displayName": ""
                          },
                          "sourceReviewId": null,
                          "syndicationData": null,
                          "groupingData": null,
                          "bundledProductData": null,
                          "country": {
                            "code": "US",
                            "label": "🇺🇸 United States"
                          },
                          "productVariants": null,
                          "language": null,
                          "translatedLanguage": null
                        }
                      ],
                      "products": [
                        {
                          "id": 94562870,
                          "domainKey": "2063374417974",
                          "name": "Thin Front Pocket Leather Backpack",
                          "socialLinks": {
                            "linkedin": null,
                            "facebook": "https://yotpo.com/go/4TwQq2ge",
                            "twitter": "https://yotpo.com/go/26lMcIfq",
                            "googleOauth2": null
                          },
                          "embeddedWidgetLink": "https://yotpo.com/go/tcv7EwI2",
                          "testimonialsProductLink": "https://yotpo.com/go/piOlYPFW",
                          "productLink": "https://yotpo.com/go/kAOFmyB2",
                          "imageUrl": "https://cdn-yotpo-images-production.yotpo.com/Product/96642481/79355834/square.jpg?1734339347",
                          "productTags": null
                        }
                      ],
                      "groupingData": null,
                      "syndicationData": null,
                      "productTags": null
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Unknown store ID. The body is the plain string `Account not found`. An unknown product ID returns `200` with no data instead.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "examples": {
                  "Unknown store": {
                    "value": "Account not found"
                  }
                }
              }
            }
          }
        },
        "x-internal": false
      }
    }
  },
  "x-readme": {
    "headers": [
      {
        "key": "Content-Type",
        "value": "application/json"
      }
    ],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```

# Sibling pages

* [Retrieve product reviews](https://docs.yotpo.com/reference/storefront-product-reviews.md)
* [Retrieve product filters](https://docs.yotpo.com/reference/storefront-product-filters.md)
* [Retrieve product data](https://docs.yotpo.com/reference/storefront-product-data.md)
* [Retrieve reviews media](https://docs.yotpo.com/reference/storefront-reviews-media.md)
* [Retrieve top product reviews](https://docs.yotpo.com/reference/storefront-top-reviews.md)
* [Retrieve top store reviews](https://docs.yotpo.com/reference/storefront-store-top-reviews.md)
* [Retrieve store reviews](https://docs.yotpo.com/reference/storefront-store-reviews.md)
* [Search store reviews](https://docs.yotpo.com/reference/storefront-store-reviews-search.md)
* [Retrieve bottomline scores](https://docs.yotpo.com/reference/storefront-all-bottomlines.md)
* [Retrieve product rating bottomline](https://docs.yotpo.com/reference/storefront-product-ratings.md)
* [Retrieve promoted products for a store](https://docs.yotpo.com/reference/storefront-store-promoted-products.md)
* [Retrieve promoted products for a product page](https://docs.yotpo.com/reference/storefront-product-promoted-products.md)
* [Retrieve gallery media](https://docs.yotpo.com/reference/storefront-gallery-media.md)
* [Retrieve a gallery media item](https://docs.yotpo.com/reference/storefront-gallery-media-item.md)
* [Retrieve AI review summary](https://docs.yotpo.com/reference/reviews-ai-summary.md)
* [List Syndicated Retailers](https://docs.yotpo.com/reference/list-syndicated-retailers.md)