---
updatedAt: 2025-06-09T20:01:02.000Z
agentTools:
  projectIndex: https://develop.yotpo.com/llms.txt
---

# Product Reviews

Retrieve product reviews for a specific product using the `external_product_id`.

> 📘 Product ID
>
> Note that in some parts of the API, `product_id` may be referred to as `external_product_id`

## Product Reviews - Response Attributes

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Attribute
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `id`
      </td>

      <td>
        The review ID
      </td>
    </tr>

    <tr>
      <td>
        `score`
      </td>

      <td>
        The star-rating score where 5 is a 5-star rating :star::star::star::star::star:
      </td>
    </tr>

    <tr>
      <td>
        `votes_up`
      </td>

      <td>
        The number of shoppers who voted up for this review :+1:
      </td>
    </tr>

    <tr>
      <td>
        `votes_down`
      </td>

      <td>
        The number of shoppers who voted down for this review :-1:
      </td>
    </tr>

    <tr>
      <td>
        `content`
      </td>

      <td>
        The textual review content
      </td>
    </tr>

    <tr>
      <td>
        `title`
      </td>

      <td>
        The title of the review
      </td>
    </tr>

    <tr>
      <td>
        `created_at`
      </td>

      <td>
        The timestamp generated upon review creation
      </td>
    </tr>

    <tr>
      <td>
        `verified_buyer`
      </td>

      <td>
        The status of the reviewer. <a href="https://www.yotpo.com/blog/what-do-verified-buyer-verified-user-and-anonymous-mean" target="_blank">Verified buyers</a> are buyers who created their review via Mail After Purchase
      </td>
    </tr>

    <tr>
      <td>
        `source_review_id`
      </td>

      <td>
        The review id by source
      </td>
    </tr>

    <tr>
      <td>
        `custom_fields`
      </td>

      <td>
        <a href="https://www.yotpo.com/blog/new-yotpo-feature-custom-review-forms" target="_blank">Custom review form</a> fields. Nested parameters include the form `title`,`form_id`,`value`, and `field type`
      </td>
    </tr>

    <tr>
      <td>
        `images_data`
      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        `user`
      </td>

      <td>
        User data. Nested parameters include the user `id`, `display _name`, `social_image`, and `email`
      </td>
    </tr>

    <tr>
      <td>
        `product`
      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        `user_id`
      </td>

      <td>
        The unique identifier of the reviewer who submitted the review
      </td>
    </tr>

    <tr>
      <td>
        `product_id`
      </td>

      <td>
        The unique product identifier of the product reviewed
      </td>
    </tr>

    <tr>
      <td>
        `comment`
      </td>

      <td>
        The comment left on the review
      </td>
    </tr>

    <tr>
      <td>
        `external_product_id`
      </td>

      <td>
        The external product id of the product reviewed
      </td>
    </tr>

    <tr>
      <td>
        `published`
      </td>

      <td>
        The published or unpublished state of the review as defined by the include\_unpublished\_reviews param.
      </td>
    </tr>
  </tbody>
</Table>

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "app-developer-api",
    "version": "2"
  },
  "servers": [
    {
      "url": "https://developers.yotpo.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "http",
        "scheme": "bearer",
        "description": "Send your access token in the Authorization header of every request: `Authorization: Bearer YOUR_ACCESS_TOKEN`. This is the recommended method. The token is also accepted as an `access_token` query parameter, but header authentication keeps tokens out of URLs and server logs. To get a token, see [Generate Access Token](https://develop.yotpo.com/reference/generate-a-token)."
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/v2/{account_id}/products/{external_product_id}/reviews": {
      "get": {
        "summary": "Product Reviews",
        "description": "Retrieve product reviews for a specific product using the `external_product_id`.",
        "operationId": "product-review",
        "parameters": [
          {
            "name": "account_id",
            "in": "path",
            "description": "Your account's API app key",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "name": "access_token",
            "in": "query",
            "description": "Your Yotpo access token. Click [here](https://develop.yotpo.com/reference/generate-a-token) to learn how to generate one",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "external_product_id",
            "in": "path",
            "description": "The `external_product_id` value. Can be retrieved using [All Reviews](https://app-market.readme.io/v2/reference/all-reviews)",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "name": "page",
            "in": "query",
            "description": "The page number of the paginated response",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "count",
            "in": "query",
            "description": "The number of reviews you want to retrieve",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "star",
            "in": "query",
            "description": "Filter by star rating score",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "include_unpublished_reviews",
            "in": "query",
            "description": "Pass a value of `true` to get all reviews including unpublished reviews. Pass a value of `false` (default) to get just the published reviews.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "is_incentivized",
            "in": "query",
            "description": "Indicates if the review comes from an incentivized source (for example, a product sampling company)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "incentive_type",
            "in": "query",
            "description": "The type of incentive provided for the review",
            "schema": {
              "type": "string",
              "enum": [
                "free_product",
                "coupon",
                "loyalty_points",
                "paid_ promotion",
                "employee_review",
                "other"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"status\": {\n        \"code\": 200,\n        \"message\": \"OK\"\n    },\n    \"pagination\": {\n        \"page\": 1,\n        \"count\": 5,\n        \"total\": 2\n    },\n    \"reviews\": {\n        \"reviews\": [\n            {\n                \"id\": \"24783037\",\n                \"score\": 5,\n                \"votes_up\": 0,\n                \"votes_down\": 0,\n                \"content\": \"test review\",\n                \"title\": \"test review\",\n                \"created_at\": \"2016-02-14T18:24:02.000Z\",\n                \"verified_buyer\": false,\n                \"source_review_id\": 0,\n                \"custom_fields\": {},\n                \"images_data\": [],\n                \"user\": null,\n                \"product\": null,\n                \"user_id\": 5819377,\n                \"product_id\": 11408720,\n                \"comment\": null\n            },\n            {\n                \"id\": \"24783015\",\n                \"score\": 5,\n                \"votes_up\": 0,\n                \"votes_down\": 0,\n                \"content\": \"test review\",\n                \"title\": \"Test review\",\n                \"created_at\": \"2016-02-14T18:21:08.000Z\",\n                \"verified_buyer\": false,\n                \"source_review_id\": 0,\n                \"custom_fields\": {},\n                \"images_data\": [],\n                \"user\": null,\n                \"product\": null,\n                \"user_id\": 5819375,\n                \"product_id\": 11408720,\n                \"comment\": null\n            }\n        ]\n    }\n}"
                  }
                },
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "object",
                          "properties": {
                            "code": {
                              "type": "integer",
                              "example": 200,
                              "default": 0
                            },
                            "message": {
                              "type": "string",
                              "example": "OK"
                            }
                          }
                        },
                        "pagination": {
                          "type": "object",
                          "properties": {
                            "page": {
                              "type": "integer",
                              "example": 1,
                              "default": 0
                            },
                            "count": {
                              "type": "integer",
                              "example": 2,
                              "default": 0
                            },
                            "total": {
                              "type": "integer",
                              "example": 239,
                              "default": 0
                            }
                          }
                        },
                        "reviews": {
                          "type": "object",
                          "properties": {
                            "reviews": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string",
                                    "example": "59353719"
                                  },
                                  "score": {
                                    "type": "integer",
                                    "example": 5,
                                    "default": 0
                                  },
                                  "votes_up": {
                                    "type": "integer",
                                    "example": 0,
                                    "default": 0
                                  },
                                  "votes_down": {
                                    "type": "integer",
                                    "example": 0,
                                    "default": 0
                                  },
                                  "content": {
                                    "type": "string",
                                    "example": "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": {
                                    "type": "string",
                                    "example": "Great pillow!"
                                  },
                                  "created_at": {
                                    "type": "string",
                                    "example": "2018-02-06T02:57:29.000Z"
                                  },
                                  "verified_buyer": {
                                    "type": "boolean",
                                    "example": true,
                                    "default": true
                                  },
                                  "source_review_id": {
                                    "type": "integer",
                                    "example": 0,
                                    "default": 0
                                  },
                                  "custom_fields": {
                                    "type": "object",
                                    "properties": {
                                      "--9728": {
                                        "type": "object",
                                        "properties": {
                                          "title": {
                                            "type": "string",
                                            "example": "Age"
                                          },
                                          "form_id": {
                                            "type": "integer",
                                            "example": 207,
                                            "default": 0
                                          },
                                          "value": {
                                            "type": "string",
                                            "example": "55 or older"
                                          },
                                          "field_type": {
                                            "type": "string",
                                            "example": "SingleChoice"
                                          }
                                        }
                                      },
                                      "--9729": {
                                        "type": "object",
                                        "properties": {
                                          "title": {
                                            "type": "string",
                                            "example": "Sleep position"
                                          },
                                          "form_id": {
                                            "type": "integer",
                                            "example": 207,
                                            "default": 0
                                          },
                                          "value": {
                                            "type": "string",
                                            "example": "On my side"
                                          },
                                          "field_type": {
                                            "type": "string",
                                            "example": "SingleChoice"
                                          }
                                        }
                                      },
                                      "--9730": {
                                        "type": "object",
                                        "properties": {
                                          "title": {
                                            "type": "string",
                                            "example": "Hours of Sleep"
                                          },
                                          "form_id": {
                                            "type": "integer",
                                            "example": 207,
                                            "default": 0
                                          },
                                          "value": {
                                            "type": "string",
                                            "example": "7 to 9 hours"
                                          },
                                          "field_type": {
                                            "type": "string",
                                            "example": "SingleChoice"
                                          }
                                        }
                                      }
                                    }
                                  },
                                  "images_data": {
                                    "type": "array"
                                  },
                                  "user": {
                                    "type": "object",
                                    "properties": {
                                      "id": {
                                        "type": "integer",
                                        "example": 16101346,
                                        "default": 0
                                      },
                                      "display_name": {
                                        "type": "string",
                                        "example": "Florence K."
                                      },
                                      "social_image": {
                                        "type": "string",
                                        "example": "https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png"
                                      },
                                      "email": {
                                        "type": "string",
                                        "example": "Flora@email.com"
                                      }
                                    }
                                  },
                                  "product": {},
                                  "user_id": {
                                    "type": "integer",
                                    "example": 16101364,
                                    "default": 0
                                  },
                                  "product_id": {
                                    "type": "integer",
                                    "example": 35421767,
                                    "default": 0
                                  },
                                  "comment": {},
                                  "external_product_id": {
                                    "type": "string",
                                    "example": "51594874628"
                                  },
                                  "published": {
                                    "type": "boolean",
                                    "example": true,
                                    "default": true
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "object",
                          "properties": {
                            "code": {
                              "type": "integer",
                              "example": 200,
                              "default": 0
                            },
                            "message": {
                              "type": "string",
                              "example": "OK"
                            }
                          }
                        },
                        "pagination": {
                          "type": "object",
                          "properties": {
                            "page": {
                              "type": "integer",
                              "example": 1,
                              "default": 0
                            },
                            "count": {
                              "type": "integer",
                              "example": 5,
                              "default": 0
                            },
                            "total": {
                              "type": "integer",
                              "example": 2,
                              "default": 0
                            }
                          }
                        },
                        "reviews": {
                          "type": "object",
                          "properties": {
                            "reviews": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string",
                                    "example": "24783037"
                                  },
                                  "score": {
                                    "type": "integer",
                                    "example": 5,
                                    "default": 0
                                  },
                                  "votes_up": {
                                    "type": "integer",
                                    "example": 0,
                                    "default": 0
                                  },
                                  "votes_down": {
                                    "type": "integer",
                                    "example": 0,
                                    "default": 0
                                  },
                                  "content": {
                                    "type": "string",
                                    "example": "test review"
                                  },
                                  "title": {
                                    "type": "string",
                                    "example": "test review"
                                  },
                                  "created_at": {
                                    "type": "string",
                                    "example": "2016-02-14T18:24:02.000Z"
                                  },
                                  "verified_buyer": {
                                    "type": "boolean",
                                    "example": false,
                                    "default": true
                                  },
                                  "source_review_id": {
                                    "type": "integer",
                                    "example": 0,
                                    "default": 0
                                  },
                                  "custom_fields": {
                                    "type": "object",
                                    "properties": {}
                                  },
                                  "images_data": {
                                    "type": "array"
                                  },
                                  "user": {},
                                  "product": {},
                                  "user_id": {
                                    "type": "integer",
                                    "example": 5819377,
                                    "default": 0
                                  },
                                  "product_id": {
                                    "type": "integer",
                                    "example": 11408720,
                                    "default": 0
                                  },
                                  "comment": {}
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": false,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```