# 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.okendo.io/on-site/storefront-rest-api/endpoints/reviews.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.