AI Summary

Overview

This feature creates AI-powered summaries of product reviews for specific markets, optimizing API usage and token consumption by only processing incremental review changes instead of re-evaluating all reviews repeatedly.

Data Hierarchy

Market
└── Product
└── Reviews

Workflow

High level workflow

The system generates AI-based summaries of product reviews at the market level, where each market contains multiple products and each product has multiple reviews. A scheduled cron job runs every three days and processes only those markets where the AI summary feature is enabled. For each product, the system fetches all approved reviews and generates a summary while maintaining a state of which reviews have already been processed. In subsequent runs, instead of reprocessing all reviews, the system identifies only new or previously unprocessed reviews and generates incremental summaries for them. These new summaries are then merged with the existing summary, ensuring that only delta changes are handled. This approach significantly reduces API calls, token usage, and overall billing cost while keeping the summaries up to date efficiently.

Cron Trigger
   ↓
Fetch Enabled Markets
   ↓
For Each Market
   ↓
Fetch Products
   ↓
For Each Product
   ↓
Fetch Incremental Reviews
   ↓
Generate AI Summary (Partial)
   ↓
Merge with Existing Summary
   ↓
Update State of Review

Sample Summary

{
  "overall_sentiment": "neutral",
  "summary": "The washing machine has received mixed feedback from customers. Many appreciate its quiet operation, ease of use, effective wash cycles, and range of features. However, concerns about durability, reliability, lengthy cycle times, and minor design issues have also been noted.",
  "top_positives": [
    "Quiet operation",
    "Easy to use with a variety of programs",
    "Effective wash cycles",
    "Good build quality with useful features",
    "Eco-friendly settings"
  ],
  "top_negatives": [
    "Durability issues",
    "Mechanical failures reported",
    "Long cycle times",
    "Problems with washing wool garments",
    "Installation issues leading to water leakage"
  ]
}

AI Summary API #

The AI Summary API is a lightweight external API designed to programmatically retrieve pre-generated AI Review Summaries for products. It allows partners, retailers, and clients to consume AI-generated review insights without retrieving the full review payload from the Display Reviews API.

Capabilities:

AI Review Summary Retrieval:
The API provides access to pre-generated AI Review Summaries for products using the product external identifier and market display code.

Overall Sentiment:
Returns the overall customer sentiment derived from approved product reviews.

AI Generated Summary:
Provides a concise AI-generated summary based on customer review content.

Top Positives & Negatives:
Returns the most commonly mentioned positive and negative aspects from customer reviews.

Market Specific Summaries:
Summaries are returned based on the requested market and language using the displayCode parameter.

Lightweight Response Structure:
The API returns only AI Summary related information, making it suitable for external integrations and partner consumption.

Read-Only API:
The API serves only pre-generated summaries stored in the database. No real-time or on-demand AI generation is triggered during API requests.

---

Limitations:

Passkey Validation:
The API requires a valid passKey for authentication. Requests with missing, invalid, or expired passkeys are rejected.

Distribution Control:
If AI Summary distribution is disabled for the requested market, the API returns an acknowledgement message in the response: “AI Summaries distribution is not enabled for this market.”

Pre-Generated Data Only:
The API does not generate summaries dynamically. Products without generated summaries return empty or null summary fields.

---

Base URL

<base_url>/api/ai-summary/v1/external

Environment	URL
Test	https://test.one2five.digital
Production	https://app.one2five.digital

---

API Details #

Property	Value
Title	AI Summary API
Overview	Consume this API to retrieve pre-generated AI Review Summaries for a product using productExternalId and displayCode.
URL	/api/ai-summary/v1/external
Host	<base_url>
Method	HTTP GET
Response-Type	json

---

Success Response

{
  "aiSummary": {
    "productExternalId": "WM12345",
    "displayCode": "aeg-en_gb",
    "overall_sentiment": "positive",
    "summary": "Customers are highly satisfied with the vacuum cleaner's battery life, suction performance, and ease of use.",
    "top_positives": [
      "Strong suction performance",
      "Long battery life",
      "Easy to use"
    ],
    "top_negatives": [
      "Small dust container",
      "Charging time could be improved"
    ]
  },
  "hasErrors": false,
  "errors": []
}

---

Empty Summary Response

{
  "aiSummary": {
    "productExternalId": "WM12345",
    "displayCode": "aeg-en_gb",
    "overall_sentiment": null,
    "summary": null,
    "top_positives": [],
    "top_negatives": []
  },
  "hasErrors": false,
  "errors": []
}

---

Error Response

{
  "hasErrors": true,
  "errors": [
    {
      "Code": "ERROR_PARAM_INVALID_API_KEY",
      "Message": "The passKey provided is invalid."
    }
  ]
}

---

Request Parameters

Parameter Name	Description	Additional Info	Example
productExternalId	External product identifier	Mandatory	WM12345
passKey	API key provided to consuming client/market	Mandatory	aa60c6d8-148f-4ca0-93d6-0eee26f78942
displayCode	Market display code representing company, language, and country	Mandatory	aeg-en_gb

---

Response Parameters

Parameter Name	Description
hasErrors	‘true’ if response contains errors, otherwise ‘false’
errors	Contains error code and message if present
aiSummary	Contains AI generated review summary data
productExternalId	External product identifier
displayCode	Requested market display code
overall_sentiment	Overall sentiment derived from customer reviews
summary	AI generated review summary
top_positives	Array of commonly mentioned positive aspects
top_negatives	Array of commonly mentioned negative aspects