Loads a page of approved reviews for 1 product, with the product's rating breakdown and average.
Description#
This is a runtime function intended to be called client side to load product reviews. Because this is a runtime (public) function no API key is required.
It loads a page of approved reviews for 1 product, with the product’s rating breakdown and average. It applies the same sort, rating filter, offset and count rules as the Load_Product_Reviews template function, so the mmx-rating-reviews component can load, sort, filter and page through reviews without reloading the page.
This function is provided by the Product Reviews module, so it’s called through Function: Module with Module_Code: tgreviews, not as a top-level Function. See Example Request.
Note
Calling this function with "Function": "Runtime_Load_Product_Reviews", or without Session_Type, returns HTTP 200 with an empty response body rather than a JSON error. An empty body means the request never reached the function.
Request Parameters#
| Parameter | Type | Required | Description |
|---|---|---|---|
Function |
String | Yes | Must be Module. |
Module_Code |
String | Yes | Must be tgreviews. |
Module_Function |
String | Yes | Must be Runtime_Load_Product_Reviews. |
Session_Type |
String | Yes | Must be runtime. Any other value returns no output. |
TGR_Product_Code |
String | Yes | The code of the product to load reviews for. Returns MOD-SYS-TGR-00183 when the product can’t be loaded. Product_Code is not accepted as an alias. |
TGR_Show_Rating |
Number | No | Returns only reviews with this rating. Applied only when the value is 1 to 5. Defaults to 0, all ratings. Values outside 1 to 5 return all ratings. |
TGR_Offset |
Number | No | Starting offset. Applied when the value is 0 or more; negative values are treated as 0. Defaults to 0. |
TGR_Count |
Number | No | Page size. Applied when the value is more than 0. Otherwise the module’s configured reviews per page is used. A count of 0 doesn’t return all reviews. |
TGR_Sort |
String | No | Sort order. See Sort values. Any other value uses the module’s configured sort. |
Sort values#
| Value | Order |
|---|---|
-id |
Newest review ID first |
-created |
Newest first |
created |
Oldest first |
-rating |
Highest rating first |
rating |
Lowest rating first |
Ascending id isn’t supported and uses the configured sort.
Response Parameters#
The response uses the standard List_Load_Query format, with the rating breakdown and average added. Only approved reviews are returned.
| Parameter | Type | Description |
|---|---|---|
total_count |
Number | Number of approved reviews that match the request. TGR_Show_Rating changes this count. |
start_offset |
Number | The offset used. An offset past the end of the result set is echoed back as sent, with an empty data array. |
data |
Array | The page of reviews. |
breakdown |
Array | One entry per rating, ratings 1 through 5 in ascending order, each with rating and count. Covers every approved review on the product. TGR_Show_Rating doesn’t change it, so a filtered list can still show the full breakdown. |
average |
Object | The average rating for every approved review on the product, with rating and count. TGR_Show_Rating doesn’t change it. |
Review fields#
Each entry in data contains the following. The review’s email and notify values are stored but are not returned by this function.
| Parameter | Type | Description |
|---|---|---|
id |
Number | Review ID |
created |
Number | Unix timestamp for when the review was submitted |
product_id |
Number | ID of the reviewed product |
approved |
Boolean | Always true; unapproved reviews aren’t returned |
rating |
Number | Rating, 1 to 5 |
name |
String | Reviewer name |
location |
String | Reviewer location. Empty when the field is hidden or wasn’t supplied. |
title |
String | Review title |
summary |
String | Review body |
store_rply |
String | The store’s public reply to the review. Empty when there’s no reply. |
verified |
Boolean | Whether the review is a verified purchase |
AdditionalFields |
Object | The review’s additional field values, keyed by additional field code. Every configured additional field is present; a field the review has no value for is an empty string. An empty object when the store has no additional fields configured. |
Example Request#
{
"Store_Code": "{{Store_Code}}",
"Function": "Module",
"Module_Code": "tgreviews",
"Module_Function": "Runtime_Load_Product_Reviews",
"Session_Type": "runtime",
"TGR_Product_Code": "{{Product_Code}}",
"TGR_Show_Rating": 0,
"TGR_Offset": 0,
"TGR_Count": 2,
"TGR_Sort": "-created"
}
Example Response#
{
"success": 1,
"data": {
"total_count": 8,
"start_offset": 0,
"breakdown": [
{ "rating": 1, "count": 1 },
{ "rating": 2, "count": 1 },
{ "rating": 3, "count": 1 },
{ "rating": 4, "count": 2 },
{ "rating": 5, "count": 3 }
],
"average": {
"rating": 3.63,
"count": 8
},
"data": [
{
"id": 9,
"created": 1793000008,
"product_id": 21,
"approved": true,
"rating": 5,
"name": "Dana R.",
"location": "San Diego, CA",
"title": "Exactly what I needed",
"summary": "Showed up quickly and the finish is flawless.",
"store_rply": "",
"verified": true,
"AdditionalFields": {
"fit": "Runs small"
}
},
{
"id": 8,
"created": 1793000007,
"product_id": 21,
"approved": true,
"rating": 4,
"name": "Nick",
"location": "",
"title": "Good, with one nit",
"summary": "Solid build. Instructions could be clearer.",
"store_rply": "Thanks for the feedback, we've updated the instructions.",
"verified": false,
"AdditionalFields": {
"fit": ""
}
}
]
}
}
Error Responses#
| Error Code | Error Message | Error Description |
|---|---|---|
| MER-JSN-00023 | One or more parameters are invalid | TGR_Product_Code was not supplied. The response includes error_field and error_fields. |
| MOD-SYS-TGR-00183 | Product not found | No product matches TGR_Product_Code. |
| MOD-SYS-TGR-00175 | (database error text) | The review list query failed. |
| invalid_module | Invalid module | The Product Reviews module isn’t installed, or Module_Code isn’t tgreviews. |