> For the complete documentation index, see [llms.txt](https://docs.okendo.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.okendo.io/on-site/storefront-rest-api/endpoints/reviews.md). # Reviews ## List Reviews Retrieve a list of published reviews relating to a specific resource. #### By Product ``` GET /products/shopify-{product_id}/reviews ``` #### By Store ``` GET /reviews ``` #### By Group ``` GET /collections/{group_id}/reviews ``` #### Query Params `limit`: Integer between 1 and 25. Default 25. `orderBy`: One of: `date desc`, `date asc`, `rating desc`, `rating asc`, `helpful desc`, `helpful asc`, `has_media desc`. Default: `date desc`. `locale`: One of the **locale query param** values below (e.g. `locale=es`): {% hint style="info" %} **Using the locale param requires translation settings to be configured in Okendo Admin.** Review Translations are currently ONLY supported for reviews who's languages were automatically detected and the time of creation/import. See: for configuration before use. The translations settings for your review widgets should be configured to "On Load" in your Okendo settings. {% endhint %} | locale query param | Language | | ------------------ | --------------------- | | `zh-TW` | Chinese (Traditional) | | `da` | Danish | | `nl` | Dutch | | `en` | English | | `fr` | French | | `de-formal` | German - Formal | | `de-informal` | German - Informal | | `id` | Indonesian | | `it` | Italian | | `ja` | Japanese | | `ko` | Korean | | `pl` | Polish | | `pt-PT` | Portuguese | | `ru` | Russian | | `es` | Spanish | | `sv` | Swedish | | `th` | Thai | | `vi` | Vietnamese | #### Example List the most recent 10 reviews the store has received: ``` GET https://api.okendo.io/v1/stores/{okendo_user_id}/reviews?limit=10&orderBy=date%20desc ``` ## Get Review Aggregate Get an aggregate of all the data related to published reviews for a specific resource. #### By Product ``` GET /products/shopify-{product_id}/review_aggregate ``` #### By Store ``` GET /review_aggregate ``` #### By Group ``` GET /collections/{group_id}/review_aggregate ``` ## List Review Media Retrieve a list of published media attached to reviews relating to a specific resource. Ordered by most recent first. #### By Product ``` GET /products/shopify-{product_id}/review_media ``` #### By Store ``` GET /review_media ``` #### By Group ``` GET /collections/{group_id}/review_media ``` #### Query Params `limit`: Integer between 1 and 25. Default 25. ### Get Reviews Summary Retrieve the AI-generated reviews summary for a specific product. If the product is part of a review group and configured to use a group summary, the summary for the group will be returned. **By Product** ``` GET /products/shopify-{product_id}/reviews_summary ``` **Example** Retrieve the reviews summary for a specific product: ``` GET https://api.okendo.io/v1/stores/{okendo_user_id}/products/shopify-{product_id}/reviews_summary ``` **Response Body Considerations** The response typically includes a `reviewsSummary` object with the following fields if a summary is available: * `body`: (string) The AI-generated text content of the reviews summary. * `contributingReviewCount`: (number) The number of reviews that contributed to this summary. * `dateGenerated`: (string, ISO 8601) The UTC date and time when the summary content was generated. * `datePublished`: (string, ISO 8601) The UTC date and time when this summary version was published. Example JSON Response (Success with data): ```json { "reviewsSummary": { "body": "Customers generally find this product to be well-made and comfortable. Many highlight its stylish design and ease of use. While a few reviewers mention the sizing can be tricky, the overall sentiment is positive, with users appreciating the value and quality offered.", "contributingReviewCount": 88, "dateGenerated": "2024-03-15T10:30:00.123Z", "datePublished": "2024-03-16T11:00:00.456Z" } } ``` **Important Notes:** * A product/group generally needs a sufficient number of reviews (e.g., around 30 or more) for a summary to be eligible to be generated. * Summaries need to be published (either by manual approval or by the auto-publish setting being toggled on) in order to be available. * The API returns either a product-specific summary or a group-level summary based on the product's configuration in Okendo (i.e., whether it's set to display its own product reviews or shared group reviews for its summary). * If no summary is available (e.g., insufficient reviews, not yet published/approved), the JSON response will be an empty object `{}`. ### Get Reviews Keywords Retrieve the AI-generated keywords and topics for a specific product. If the product is part of a review group and configured to use group-level keywords, the keywords for the group will be returned. **By Product** ``` GET /products/shopify-{product_id}/reviews_keywords ``` **Example** Retrieve the reviews keywords for a specific product: ``` GET https://api.okendo.io/v1/stores/{okendo_user_id}/products/shopify-{product_id}/reviews_keywords ``` **Response Body Considerations** The response includes a `reviewsKeywords` object, which contains a `keywordTopics` array if keywords are available. \ Each object within the `keywordTopics` array represents a broader theme and has the following structure: * `topic`: (string) The name of the general theme (e.g., "Fit", "Comfort", "Quality"). * `keywords`: (array of objects) A list of specific keywords related to this topic. \ Each keyword object has: * `name`: (string) The specific keyword phrase (e.g., "sizing", "durability", "material quality"). * `occurrences`: (number) The number of times this specific keyword was identified. Example structure for the `reviewsKeywords` object: ```json { "reviewsKeywords": { "keywordTopics": [ { "topic": "Fit", "keywords": [ { "name": "fit", "occurrences": 295 }, { "name": "sizing", "occurrences": 138 }, { "name": "size chart", "occurrences": 5 } ] }, { "topic": "Comfort", "keywords": [ { "name": "comfort", "occurrences": 79 }, { "name": "stays put", "occurrences": 5 } ] } // ... other topics ] } } ``` **Important Notes:** * A product/group generally needs a sufficient number of reviews for keywords to be generated and available. * The API returns either a product-specific keywords or a group-level keywords based on the product's configuration in Okendo (i.e., whether it's set to display its own product reviews or shared group reviews for its keywords). * If no keywords are available (e.g., insufficient reviews, not yet processed), the JSON response will be an empty object `{}`. ## List Questions & Answers Retrieve a list of published questions (and corresponding answers) relating to a specific resource. Ordered by most recent first. #### By Product ``` GET /products/shopify-{product_id}/questions ``` #### By Group ``` GET /collections/{group_id}/questions ``` #### Query Params `limit`: Integer between 1 and 25. Default 25.