Endpoints

Common endpoints for accessing data through the Storefront REST API

Introduction

All endpoints are relative to our base URL:

https://api.okendo.io/v1/stores/{okendo_user_id}

Substitutions Reference

Throughout this article you will see substitutions enclosed in {} for example {okendo_user_id}. Replace these (including the curly brackets) with the corresponding value:

okendo_user_id: Your Okendo User ID. You can get this information from the Okendo section in the integration settings of the Okendo app.

product_id: A Shopify Product ID.

group_id: An Okendo Group ID or a Shopify Collection ID.

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

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: https://support.okendo.io/en/articles/9684374-enabling-review-translation-for-multiple-languages

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

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

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

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