{"id":4097,"date":"2026-04-08T15:22:30","date_gmt":"2026-04-08T15:22:30","guid":{"rendered":"https:\/\/developers-test.one2five.digital\/?post_type=docs&p=4097"},"modified":"2026-05-12T09:14:55","modified_gmt":"2026-05-12T09:14:55","slug":"ai-summary","status":"publish","type":"docs","link":"https:\/\/developers-test.one2five.digital\/?docs=ai-summary","title":{"rendered":"AI Summary"},"content":{"rendered":"\n

Overview<\/mark><\/h4>\n\n\n\n

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

Data Hierarchy<\/mark><\/h4>\n\n\n\n

Market
\u2514\u2500\u2500 Product
\u2514\u2500\u2500 Reviews<\/p>\n\n\n\n

\n
\n
Property name<\/td>Description<\/td>Default Value<\/td><\/tr>
AI Summaries Generation<\/td>Toggle to enable or disable summary generation for the market<\/td>false<\/td><\/tr>
AI Summaries Distribution<\/td>Toggle to enable or disable the inclusion of summaries in the standard client feed XML file for the specified market<\/td>false<\/td><\/tr>
active.ai.model<\/td>Active ai model in use<\/td>GPT (can be set to ‘COHERE’, ‘MISTRAL’, ‘DEEPSEEK’)<\/td><\/tr>
product.review.size<\/td>The number of least reviews required for the product to generate a summary for<\/td>8<\/td><\/tr>
ai.summary.cron<\/td>cron expression<\/td>0 0 13 *\/3 * ?<\/td><\/tr><\/tbody><\/table><\/figure>\n<\/div>\n<\/div>\n\n\n\n

Workflow<\/mark><\/h4>\n\n\n\n

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.<\/p>\n\n\n\n

Cron Trigger\n   \u2193\nFetch Enabled Markets\n   \u2193\nFor Each Market\n   \u2193\nFetch Products\n   \u2193\nFor Each Product\n   \u2193\nFetch Incremental Reviews\n   \u2193\nGenerate AI Summary (Partial)\n   \u2193\nMerge with Existing Summary\n   \u2193\nUpdate State of Review<\/code><\/pre>\n\n\n\n
Sample Summary<\/mark><\/h4>\n\n\n\n
{\n  \"overall_sentiment\": \"neutral\",\n  \"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.\",\n  \"top_positives\": [\n    \"Quiet operation\",\n    \"Easy to use with a variety of programs\",\n    \"Effective wash cycles\",\n    \"Good build quality with useful features\",\n    \"Eco-friendly settings\"\n  ],\n  \"top_negatives\": [\n    \"Durability issues\",\n    \"Mechanical failures reported\",\n    \"Long cycle times\",\n    \"Problems with washing wool garments\",\n    \"Installation issues leading to water leakage\"\n  ]\n}<\/code><\/pre>\n\n\n\n
AI Summary API<\/h3>\n\n\n\n
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.<\/p>\n\n\n\n
Capabilities:<\/mark><\/h4>\n\n\n\n
AI Review Summary Retrieval:<\/strong>
The API provides access to pre-generated AI Review Summaries for products using the product external identifier and market display code.<\/p>\n\n\n\n
Overall Sentiment:<\/strong>
Returns the overall customer sentiment derived from approved product reviews.<\/p>\n\n\n\n
AI Generated Summary:<\/strong>
Provides a concise AI-generated summary based on customer review content.<\/p>\n\n\n\n
Top Positives & Negatives:<\/strong>
Returns the most commonly mentioned positive and negative aspects from customer reviews.<\/p>\n\n\n\n
Market Specific Summaries:<\/strong>
Summaries are returned based on the requested market and language using the displayCode parameter.<\/p>\n\n\n\n
Lightweight Response Structure:<\/strong>
The API returns only AI Summary related information, making it suitable for external integrations and partner consumption.<\/p>\n\n\n\n
Read-Only API:<\/strong>
The API serves only pre-generated summaries stored in the database. No real-time or on-demand AI generation is triggered during API requests.<\/p>\n\n\n\n
\n\n\n\n
Limitations:<\/mark><\/h4>\n\n\n\n
Passkey Validation:<\/strong>
The API requires a valid passKey for authentication. Requests with missing, invalid, or expired passkeys are rejected.<\/p>\n\n\n\n
Distribution Control:<\/strong>
If AI Summary distribution is disabled for the requested market, the API returns an acknowledgement message in the response: \u201cAI Summaries distribution is not enabled for this market.\u201d<\/p>\n\n\n\n
Pre-Generated Data Only:<\/strong>
The API does not generate summaries dynamically. Products without generated summaries return empty or null summary fields.<\/p>\n\n\n\n
\n\n\n\n
Base URL<\/mark><\/h4>\n\n\n\n
<base_url>\/api\/ai-summary\/v1\/external<\/code><\/p>\n\n\n\n
Environment<\/th>URL<\/th><\/tr><\/thead>
Test<\/td>https:\/\/test.one2five.digital<\/a><\/td><\/tr>
Production<\/td>https:\/\/app.one2five.digital<\/a><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
\n\n\n\n
API Details<\/mark><\/h3>\n\n\n\n
Property<\/th>Value<\/th><\/tr><\/thead>
Title<\/td>AI Summary API<\/td><\/tr>
Overview<\/td>Consume this API to retrieve pre-generated AI Review Summaries for a product using productExternalId and displayCode.<\/td><\/tr>
URL<\/td>\/api\/ai-summary\/v1\/external<\/a><\/td><\/tr>
Host<\/td><base_url><\/code><\/td><\/tr>
Method<\/td>HTTP GET<\/td><\/tr>
Response-Type<\/td>json<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
\n\n\n\n
Success Response<\/mark><\/h4>\n\n\n\n
{\n  \"aiSummary\": {\n    \"productExternalId\": \"WM12345\",\n    \"displayCode\": \"aeg-en_gb\",\n    \"overall_sentiment\": \"positive\",\n    \"summary\": \"Customers are highly satisfied with the vacuum cleaner's battery life, suction performance, and ease of use.\",\n    \"top_positives\": [\n      \"Strong suction performance\",\n      \"Long battery life\",\n      \"Easy to use\"\n    ],\n    \"top_negatives\": [\n      \"Small dust container\",\n      \"Charging time could be improved\"\n    ]\n  },\n  \"hasErrors\": false,\n  \"errors\": []\n}<\/code><\/pre>\n\n\n\n
\n\n\n\n
Empty Summary Response<\/mark><\/h4>\n\n\n\n
{\n  \"aiSummary\": {\n    \"productExternalId\": \"WM12345\",\n    \"displayCode\": \"aeg-en_gb\",\n    \"overall_sentiment\": null,\n    \"summary\": null,\n    \"top_positives\": [],\n    \"top_negatives\": []\n  },\n  \"hasErrors\": false,\n  \"errors\": []\n}<\/code><\/pre>\n\n\n\n
\n\n\n\n
Error Response<\/mark><\/h4>\n\n\n\n
{
  \"hasErrors\": true,
  \"errors\": [
    {
      \"Code\": \"ERROR_PARAM_INVALID_API_KEY\",
      \"Message\": \"The passKey provided is invalid.\"
    }
  ]
}<\/code><\/pre>\n\n\n\n
\n\n\n\n
Request Parameters<\/mark><\/h4>\n\n\n\n
Parameter Name<\/th>Description<\/th>Additional Info<\/th>Example<\/th><\/tr><\/thead>
productExternalId<\/td>External product identifier<\/td>Mandatory<\/td>WM12345<\/td><\/tr>
passKey<\/td>API key provided to consuming client\/market<\/td>Mandatory<\/td>aa60c6d8-148f-4ca0-93d6-0eee26f78942<\/td><\/tr>
displayCode<\/td>Market display code representing company, language, and country<\/td>Mandatory<\/td>aeg-en_gb<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
\n\n\n\n
Response Parameters<\/mark><\/h4>\n\n\n\n
Parameter Name<\/th>Description<\/th><\/tr><\/thead>
hasErrors<\/td>‘true’ if response contains errors, otherwise ‘false’<\/td><\/tr>
errors<\/td>Contains error code and message if present<\/td><\/tr>
aiSummary<\/td>Contains AI generated review summary data<\/td><\/tr>
productExternalId<\/td>External product identifier<\/td><\/tr>
displayCode<\/td>Requested market display code<\/td><\/tr>
overall_sentiment<\/td>Overall sentiment derived from customer reviews<\/td><\/tr>
summary<\/td>AI generated review summary<\/td><\/tr>
top_positives<\/td>Array of commonly mentioned positive aspects<\/td><\/tr>
top_negatives<\/td>Array of commonly mentioned negative aspects<\/td><\/tr><\/tbody><\/table><\/figure>\n","protected":false},"excerpt":{"rendered":"
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\u2514\u2500\u2500 Product \u2514\u2500\u2500 Reviews Property name Description Default Value AI Summaries Generation Toggle to enable or disable summary generation for the market false … Read more<\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"closed","template":"","meta":{"_eb_attr":"","inline_featured_image":false,"footnotes":""},"doc_category":[11],"doc_tag":[],"class_list":["post-4097","docs","type-docs","status-publish","hentry","doc_category-knowledge-hub"],"jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/developers-test.one2five.digital\/index.php?rest_route=\/wp\/v2\/docs\/4097","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/developers-test.one2five.digital\/index.php?rest_route=\/wp\/v2\/docs"}],"about":[{"href":"https:\/\/developers-test.one2five.digital\/index.php?rest_route=\/wp\/v2\/types\/docs"}],"author":[{"embeddable":true,"href":"https:\/\/developers-test.one2five.digital\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/developers-test.one2five.digital\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=4097"}],"version-history":[{"count":19,"href":"https:\/\/developers-test.one2five.digital\/index.php?rest_route=\/wp\/v2\/docs\/4097\/revisions"}],"predecessor-version":[{"id":4176,"href":"https:\/\/developers-test.one2five.digital\/index.php?rest_route=\/wp\/v2\/docs\/4097\/revisions\/4176"}],"wp:attachment":[{"href":"https:\/\/developers-test.one2five.digital\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=4097"}],"wp:term":[{"taxonomy":"doc_category","embeddable":true,"href":"https:\/\/developers-test.one2five.digital\/index.php?rest_route=%2Fwp%2Fv2%2Fdoc_category&post=4097"},{"taxonomy":"doc_tag","embeddable":true,"href":"https:\/\/developers-test.one2five.digital\/index.php?rest_route=%2Fwp%2Fv2%2Fdoc_tag&post=4097"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}