Get rating and sentiment metrics for product collections in your store to compare review feedback across collections.

📘

Authentication and request format

Authenticate with Authorization: Bearer YOUR_ACCESS_TOKEN. The Insights API does not accept the X-Yotpo-Token header.

Send filters inside the filter object, pagination inside paging and sorting inside sorting. Fields sent at the top level of the body are ignored.

Send a request

1. Set Authorization: Bearer YOUR_ACCESS_TOKEN and Content-Type: application/json.
2. Add your store ID to filter.app_key and topic names to filter.topics.
3. Add collection names to filter.product_collections to scope the analysis to those collections.
4. Send the request to https://api.yotpo.com/insights/v1/topics/products.

The following example uses the collection, topic, and date range supplied in the endpoint specification. Replace the token, store ID, and collection name with your own values.

curl --request POST \
  --url 'https://api.yotpo.com/insights/v1/topics/products' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "filter": {
      "app_key": "YOUR_STORE_ID",
      "topics": ["quality"],
      "product_collections": ["Cool Watches"],
      "date_range": {
        "start_date": "2018-01-11T00:00:00.000Z",
        "end_date": "2018-11-12T00:00:00.000Z"
      },
      "minimum_score": 4,
      "exclude_unpublished": false
    },
    "paging": {
      "page": 0,
      "per_page": 10
    },
    "sorting": {
      "sorting_field": "yotpo_default_sorting"
    }
  }' \
  --include \
  --fail-with-body

Expect HTTP 200 with the JSON structure shown under Response example. With --fail-with-body, curl returns a nonzero exit status for HTTP errors while retaining the response body. Check the status before processing the body; a 401 body is plain text, not JSON.

Request body

Only filter is required at the top level. Within it, app_key and topics are required. Other fields are optional. Unless stated below, the specification does not define a default, length limit, or array-size limit.

Required filter fields

The specification requires topics but does not define whether an empty array is accepted. Supply the topic names you want to analyze.

Optional: Filter reviews

Optional: Paginate and sort

Responses

These are the status codes defined in the endpoint specification. It does not define additional error codes or error-body formats.

Response fields

The response schema does not mark fields as required. Check that a field is present before reading it, and treat a nonempty sentiment_change.error as information to inspect rather than assuming the change value is usable.

Response example

{
  "product_collections": [
    {
      "product_collections": "Cool Watches",
      "average_star_rating": 4.882443928847641,
      "sentiment_score": 85.60082,
      "sentiment_change": {
        "value": 0.29634076789936614,
        "error": ""
      },
      "positive_reviews": 3418,
      "negative_reviews": 77,
      "neutral_reviews": 406,
      "reviews_count": 3903,
      "products_in_collection": [
        { "product_id": "1850285" },
        { "product_id": "10228864" },
        { "product_id": "24857299" },
        { "product_id": "24857295" },
        { "product_id": "35392356" },
        { "product_id": "35787751" }
      ],
      "products_count": 6
    }
  ],
  "paging": {
    "page": 0,
    "page_count": 6,
    "per_page": 1,
    "total": 6
  }
}

Error examples

HTTP 400:

{}

HTTP 401:

unauthorized

Rate limits and troubleshooting

The specification defines these headers for 200 and 400 responses, but does not specify fixed quota values or a rate-limit error response. Monitor the returned values instead of hard-coding a quota. When ratelimit-remaining reaches 0, pause requests for the number of seconds in ratelimit-reset; also pace requests to avoid exhausting the per-minute allowance.

• Filters appear to have no effect: Move filter fields under filter. Keep pagination under paging and sorting under sorting; flat fields are ignored.
• The API returns 400: Include filter.app_key and filter.topics. Check ISO 8601 dates, minimum_score from 1 to 5, paging.page of at least 0, and paging.per_page of at least 1.
• The API returns 401: Send the token in Authorization: Bearer YOUR_ACCESS_TOKEN. Follow Yotpo Authentication to obtain a valid token.
• Sort direction has no effect: sorting_direction does not apply to yotpo_default_sorting. For other sorting fields, use uppercase ASC or DESC.
• No collections are returned: Handle the empty result without indexing into it, then check your catalog collection names and review filters.