Skip to main content

Reviews

Storefront REST API endpoints related to Okendo 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 codes in the list below (e.g. locale=es):

Using the locale param requires translation settings to be configured in Okendo Admin.

Review Translations are currently ONLY supported for reviews whose languages were automatically detected at the time of creation/import.

See our translations help article for configuration before use. The translations settings for your review widgets should be configured to "On Load" in your Okendo settings.

Locale codes
bg (Bulgarian)
cs (Czech)
da (Danish)
el (Greek)
es (Spanish)
fi (Finnish)
fr (French)
hi (Hindi)
hr (Croatian)
hu (Hungarian)
id (Indonesian)
it (Italian)
ja (Japanese)
ko (Korean)
lt (Lithuanian)
ms (Malay)
nb (Norwegian, Bokmål)
nl (Dutch)
pl (Polish)
pt-br (Portuguese, Brazil)
pt-pt (Portuguese, Portugal)
ro (Romanian)
ru (Russian)
sk (Slovak)
sl (Slovenian)
sr (Serbian)
sv (Swedish)
th (Thai)
tr (Turkish)
uk (Ukrainian)
vi (Vietnamese)
zh-cn (Chinese, simplified)
zh-tw (Chinese, traditional)

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.

If you're rendering in Liquid, this data may already be available without an API call. Product-level aggregates via Product Metafields and shop-level aggregates via Shop Metafields.

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.

If you're rendering in Liquid, a pre-rendered HTML version of this summary is already available without an API call via the ai_text_summary_snippet product metafield.

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):

{
    "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.

If you're rendering in Liquid, a pre-rendered HTML version of these keywords is already available without an API call via the ai_keyword_filters product metafield.

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:

{
    "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.