Reviews are used to evaluate Products and Channels.
On the tutorial page you can find some instructions on how to use Reviews to rate Products and Channels.
Representations
Review
id ​String​ | Unique identifier of the Review. |
version ​Int​ | Current version of the Review. |
key ​String​ | User-defined unique identifier of the Review. |
uniquenessValue ​String​ | Must be unique among Reviews. For example, if this value is set to Customer |
locale ​Locale​ | Language in which the content of the Review is written. |
authorName ​String​ | Name of the author. |
title ​String​ | Title of the Review. |
text ​String​ | Content of the Review. |
target ​Can be ProductReference, or ChannelReference​ | Identifies the target of the Review. Can be a Product or a Channel, specified as ProductReference or ChannelReference, respectively. (oneOf):ProductReferenceChannelReference ​ |
includedInStatistics ​Boolean​ | Indicates if this Review is taken into account in the ratings statistics of the target.
A Review is per default used in the statistics, unless the Review is in a state that does not have the role |
rating ​Int​ | Rating of the Product or Channel. Minimum:-100 ​Maximum: 100 ​ |
state ​ | State of the Review. Used for approval processes, see Review approval process for details. |
customer ​ | Customer who created the Review. |
custom ​CustomFields​ | Custom Fields of the Review. |
createdAt ​DateTime​ | Date and time (UTC) the Review was initially created. |
createdBy ​BETACreatedBy​ | IDs and references that created the Review. |
lastModifiedAt ​DateTime​ | Date and time (UTC) the Review was last updated. |
lastModifiedBy ​BETA | IDs and references that last modified the Review. |
{
"id": "919d5ab5-bf99-4bda-a6fd-ab3ee8123456",
"version": 1,
"includedInStatistics": true,
"authorName": "John Doe",
"title": "Incredible",
"text": "Best product ever",
"rating": 5,
"target": {
"typeId": "product",
"id": "8fddacac-6ef5-4e66-af6e-124452123456"
},
"customer": {
"typeId": "customer",
"id": "8a8b3e43-b9b0-4b30-8c27-58148123456"
},
"custom": {
"type": {
"typeId": "type",
"id": "3939dd9c-0884-4bfa-99c2-40b426123456"
},
"fields": {
"authorMail": "john.doe@example.com"
}
},
"createdAt": "2016-10-20T06:48:53.829Z",
"lastModifiedAt": "2016-10-20T06:48:53.829Z"
}
ReviewDraft
When creating a new Review, at least one of title
, text
or rating
should be set.
key ​String​ | User-defined unique identifier for the Review. |
uniquenessValue ​String​ | If set, this value must be unique among Reviews.
For example, if you want to have only one Review per Customer and per Product, you can set the value to Customer |
locale ​Locale​ | Language in which the content of the Review is written. |
authorName ​String​ | Name of the author. |
title ​String​ | Title of the Review. |
text ​String​ | Content of the Review. |
target ​Can be ProductResourceIdentifier, or ChannelResourceIdentifier​ | Identifies the target of the Review. Can be a Product or a Channel, specified as ProductResourceIdentifier or ChannelResourceIdentifier, respectively. (oneOf):ProductResourceIdentifierChannelResourceIdentifier ​ |
state ​ | State of the Review. Used for approval processes, see Review approval process for details. |
rating ​Int​ | Rating of the targeted Product or Channel.
This rating can represent the number of stars, a percentage, or a like (+1)/dislike (-1).
A rating is used in the ratings statistics of the targeted object, unless the Review is in a State that does not have the role -100 ​Maximum: 100 ​ |
customer ​ | Customer who created the Review. |
custom ​ | Custom Fields for the Review. |
{
"authorName": "John Doe",
"title": "Incredible",
"text": "Best product ever",
"rating": 5,
"target": {
"typeId": "product",
"id": "8fddacac-6ef5-4e66-af6e-124452123456"
}
}
ReviewPagedQueryResponse
limit ​Int​ | Number of results requested. Default:20 ​Minimum: 0 ​Maximum: 500 ​ |
count ​Int​ | Actual number of results returned. |
total ​Int​ | Total number of results matching the query.
This number is an estimation that is not strongly consistent.
This field is returned by default.
For improved performance, calculating this field can be deactivated by using the query parameter |
offset ​Int​ | Number of elements skipped. Default:0 ​Maximum: 10000 ​ |
results ​Array of Review​ | Reviews matching the query. |
{
"limit": 20,
"offset": 0,
"count": 2,
"total": 2,
"results": [
{
"id": "919d5ab5-bf99-4bda-a6fd-ab3ee8123456",
"version": 1,
"includedInStatistics": true,
"authorName": "John Doe",
"title": "Incredible",
"text": "Best product ever",
"rating": 5,
"target": {
"typeId": "product",
"id": "8fddacac-6ef5-4e66-af6e-124452123456"
},
"customer": {
"typeId": "customer",
"id": "8a8b3e43-b9b0-4b30-8c27-58148123456"
},
"custom": {
"type": {
"typeId": "type",
"id": "3939dd9c-0884-4bfa-99c2-40b426123456"
},
"fields": {
"authorMail": "john.doe@example.com"
}
},
"createdAt": "2016-10-20T06:48:53.829Z",
"lastModifiedAt": "2016-10-20T06:48:53.829Z"
},
{
"id": "2f60e06c-7672-47fc-962a-1eafa1123456",
"version": 1,
"includedInStatistics": true,
"authorName": ".",
"title": ".",
"text": ".",
"rating": 5,
"target": {
"typeId": "product",
"id": "2c155644-bcde-426c-b021-a2aab123456"
},
"custom": {
"type": {
"typeId": "type",
"id": "3939dd9c-0884-4bfa-99c2-40b42123456"
},
"fields": {
"authorMail": "."
}
},
"createdAt": "2016-10-20T06:51:26.795Z",
"lastModifiedAt": "2016-10-20T06:51:26.795Z"
}
]
}
ReviewRatingStatistics
averageRating ​Float​ | Average rating of one target This number is rounded with 5 decimals. |
highestRating ​Float​ | Highest rating of one target |
lowestRating ​Float​ | Lowest rating of one target |
count ​Int​ | Number of ratings taken into account |
ratingsDistribution ​Object​ | Full distribution of the ratings. The keys are the different ratings and the values are the count of reviews having this rating. Only the used ratings appear in this object. |
ReviewReference
id ​String​ | Unique identifier of the referenced Review. |
typeId ​ | review Type of referenced resource. |
obj ​Review​ | Contains the representation of the expanded Review. Only present in responses to requests with Reference Expansion for Reviews. |
ReviewResourceIdentifier
ResourceIdentifier to a Review. Either id
or key
is required. If both are set, an InvalidJsonInput error is returned.
id ​String​ | Unique identifier of the referenced Review. Required if |
key ​String​ | User-defined unique identifier of the referenced Review. Required if |
typeId ​ | review Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource. |
Get Review
Get Review by ID
view_products:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
id String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/reviews/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "919d5ab5-bf99-4bda-a6fd-ab3ee8123456",
"version": 1,
"includedInStatistics": true,
"authorName": "John Doe",
"title": "Incredible",
"text": "Best product ever",
"rating": 5,
"target": {
"typeId": "product",
"id": "8fddacac-6ef5-4e66-af6e-124452123456"
},
"customer": {
"typeId": "customer",
"id": "8a8b3e43-b9b0-4b30-8c27-58148123456"
},
"custom": {
"type": {
"typeId": "type",
"id": "3939dd9c-0884-4bfa-99c2-40b426123456"
},
"fields": {
"authorMail": "john.doe@example.com"
}
},
"createdAt": "2016-10-20T06:48:53.829Z",
"lastModifiedAt": "2016-10-20T06:48:53.829Z"
}
Get Review by Key
view_products:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
key String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/reviews/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "919d5ab5-bf99-4bda-a6fd-ab3ee8123456",
"version": 1,
"includedInStatistics": true,
"authorName": "John Doe",
"title": "Incredible",
"text": "Best product ever",
"rating": 5,
"target": {
"typeId": "product",
"id": "8fddacac-6ef5-4e66-af6e-124452123456"
},
"customer": {
"typeId": "customer",
"id": "8a8b3e43-b9b0-4b30-8c27-58148123456"
},
"custom": {
"type": {
"typeId": "type",
"id": "3939dd9c-0884-4bfa-99c2-40b426123456"
},
"fields": {
"authorMail": "john.doe@example.com"
}
},
"createdAt": "2016-10-20T06:48:53.829Z",
"lastModifiedAt": "2016-10-20T06:48:53.829Z"
}
Query Reviews
view_products:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
where | The parameter can be passed multiple times. |
sort | The parameter can be passed multiple times. |
expand | The parameter can be passed multiple times. |
limit Int ​ | Number of results requested. Default: 20 ​ |
offset Int ​ | Number of elements skipped. Default: 0 ​ |
withTotal Boolean ​ | Controls the calculation of the total number of query results. Set to Default: true ​ |
var.<varName> String ​ | Predicate parameter values. The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/reviews -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"limit": 20,
"offset": 0,
"count": 2,
"total": 2,
"results": [
{
"id": "919d5ab5-bf99-4bda-a6fd-ab3ee8123456",
"version": 1,
"includedInStatistics": true,
"authorName": "John Doe",
"title": "Incredible",
"text": "Best product ever",
"rating": 5,
"target": {
"typeId": "product",
"id": "8fddacac-6ef5-4e66-af6e-124452123456"
},
"customer": {
"typeId": "customer",
"id": "8a8b3e43-b9b0-4b30-8c27-58148123456"
},
"custom": {
"type": {
"typeId": "type",
"id": "3939dd9c-0884-4bfa-99c2-40b426123456"
},
"fields": {
"authorMail": "john.doe@example.com"
}
},
"createdAt": "2016-10-20T06:48:53.829Z",
"lastModifiedAt": "2016-10-20T06:48:53.829Z"
},
{
"id": "2f60e06c-7672-47fc-962a-1eafa1123456",
"version": 1,
"includedInStatistics": true,
"authorName": ".",
"title": ".",
"text": ".",
"rating": 5,
"target": {
"typeId": "product",
"id": "2c155644-bcde-426c-b021-a2aab123456"
},
"custom": {
"type": {
"typeId": "type",
"id": "3939dd9c-0884-4bfa-99c2-40b42123456"
},
"fields": {
"authorMail": "."
}
},
"createdAt": "2016-10-20T06:51:26.795Z",
"lastModifiedAt": "2016-10-20T06:51:26.795Z"
}
]
}
Check if Review exists
Check if Review exists by ID
Checks if a Review exists for a given id
. Returns a 200 OK
status if the Review exists or a 404 Not Found
otherwise.
view_products:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
id String ​ |
|
curl --head https://api.{region}.commercetools.com/{projectKey}/reviews/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if Review exists by Key
Checks if a Review exists for a given key
. Returns a 200 OK
status if the Review exists or a 404 Not Found
otherwise.
view_products:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
key String ​ |
|
curl --head https://api.{region}.commercetools.com/{projectKey}/reviews/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if Review exists by Query Predicate
Checks if a Review exists for a given Query Predicate. Returns a 200 OK
status if any Reviews match the Query Predicate or a 404 Not Found
otherwise.
view_products:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
where |
curl --head https://api.{region}.commercetools.com/{projectKey}/reviews -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Create Review
manage_products:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
application/json
curl https://api.{region}.commercetools.com/{projectKey}/reviews -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"authorName" : "John Doe",
"title" : "Incredible",
"text" : "Best product ever",
"rating" : 5,
"target" : {
"typeId" : "product",
"id" : "8fddacac-6ef5-4e66-af6e-124452123456"
}
}
DATA
{
"id": "919d5ab5-bf99-4bda-a6fd-ab3ee8123456",
"version": 1,
"includedInStatistics": true,
"authorName": "John Doe",
"title": "Incredible",
"text": "Best product ever",
"rating": 5,
"target": {
"typeId": "product",
"id": "8fddacac-6ef5-4e66-af6e-124452123456"
},
"customer": {
"typeId": "customer",
"id": "8a8b3e43-b9b0-4b30-8c27-58148123456"
},
"custom": {
"type": {
"typeId": "type",
"id": "3939dd9c-0884-4bfa-99c2-40b426123456"
},
"fields": {
"authorMail": "john.doe@example.com"
}
},
"createdAt": "2016-10-20T06:48:53.829Z",
"lastModifiedAt": "2016-10-20T06:48:53.829Z"
}
This method produces the Review Created Message.
Update Review
Update Review by ID
manage_products:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
id String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
application/json
curl https://api.{region}.commercetools.com/{projectKey}/reviews/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "setAuthorName",
"authorName" : "John Doe"
} ]
}
DATA
{
"id": "919d5ab5-bf99-4bda-a6fd-ab3ee8123456",
"version": 1,
"includedInStatistics": true,
"authorName": "John Doe",
"title": "Incredible",
"text": "Best product ever",
"rating": 5,
"target": {
"typeId": "product",
"id": "8fddacac-6ef5-4e66-af6e-124452123456"
},
"customer": {
"typeId": "customer",
"id": "8a8b3e43-b9b0-4b30-8c27-58148123456"
},
"custom": {
"type": {
"typeId": "type",
"id": "3939dd9c-0884-4bfa-99c2-40b426123456"
},
"fields": {
"authorMail": "john.doe@example.com"
}
},
"createdAt": "2016-10-20T06:48:53.829Z",
"lastModifiedAt": "2016-10-20T06:48:53.829Z"
}
Update Review by Key
manage_products:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
key String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
application/json
curl https://api.{region}.commercetools.com/{projectKey}/reviews/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "setAuthorName",
"authorName" : "John Doe"
} ]
}
DATA
{
"id": "919d5ab5-bf99-4bda-a6fd-ab3ee8123456",
"version": 1,
"includedInStatistics": true,
"authorName": "John Doe",
"title": "Incredible",
"text": "Best product ever",
"rating": 5,
"target": {
"typeId": "product",
"id": "8fddacac-6ef5-4e66-af6e-124452123456"
},
"customer": {
"typeId": "customer",
"id": "8a8b3e43-b9b0-4b30-8c27-58148123456"
},
"custom": {
"type": {
"typeId": "type",
"id": "3939dd9c-0884-4bfa-99c2-40b426123456"
},
"fields": {
"authorMail": "john.doe@example.com"
}
},
"createdAt": "2016-10-20T06:48:53.829Z",
"lastModifiedAt": "2016-10-20T06:48:53.829Z"
}
Update actions
Set Key
action ​String​ | "setKey" |
key ​String​ | Value to set. If empty, any existing value will be removed. |
{
"action": "setKey",
"key": "myReviewKey"
}
Set Customer
action ​String​ | "setCustomer" |
customer ​ | Value to set. If empty, any existing value will be removed. |
{
"action": "setCustomer",
"customer": {
"typeId": "customer",
"id": "0c2eaad4-833c-43c1-98a4-5d03f57e9329"
}
}
Set Rating
This update action produces the ReviewRatingSet Message.
action ​String​ | "setRating" |
rating ​Int​ | Value to set. If empty, any existing value will be removed. Minimum:-100 ​Maximum: 100 ​ |
{
"action": "setRating",
"rating": 60
}
Set Target
action ​String​ | "setTarget" |
target ​Can be ProductResourceIdentifier, or ChannelResourceIdentifier​ | Value to set, specified as ProductResourceIdentifier or ChannelResourceIdentifier, respectively. If empty, any existing value will be removed. (oneOf):ProductResourceIdentifierChannelResourceIdentifier ​ |
{
"action": "setTarget",
"target": {
"typeId": "product",
"id": "{{product-id}}"
}
}
Set Text
action ​String​ | "setText" |
text ​String​ | Value to set. If empty, any existing value will be removed. |
{
"action": "setText",
"text": "reviewText"
}
Set Title
action ​String​ | "setTitle" |
title ​String​ | Value to set. If empty, any existing value will be removed. |
{
"action": "setTitle",
"title": "reviewTitle"
}
Set Locale
action ​String​ | "setLocale" |
locale ​Locale​ | Value to set. If empty, any existing value will be removed. |
{
"action": "setLocale",
"locale": "en-US"
}
Transition State
Transition to a new State. This update action produces the Review State Transition Message.
action ​String​ | "transitionState" |
state ​ | Value to set. If there is no State yet, the new State must be an initial State. If the existing State has |
force ​Boolean​ | Switch validations on or off. |
{
"action": "transitionState",
"state": {
"typeId": "state",
"id": "{{state-id}}"
}
}
Set Custom Type
action ​String​ | "setCustomType" |
type ​ | Defines the Type that extends the Review with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Review. |
fields ​ | Sets the Custom Fields fields for the Review. |
{
"action": "setCustomType",
"type": {
"id": "{{type-id}}",
"typeId": "type"
},
"fields": {
"exampleStringField": "TextString"
}
}
Set CustomField
action ​String​ | "setCustomField" |
name ​String​ | Name of the Custom Field. |
value ​ | If |
{
"action": "setCustomField",
"name": "exampleStringField",
"value": "TextString"
}
Delete Review
Delete Review by ID
manage_products:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
id String ​ |
|
version Int ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
dataErasure Boolean ​ | To erase all related personal data in compliance with GDPR, set to Default: false ​ |
application/json
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/reviews/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "919d5ab5-bf99-4bda-a6fd-ab3ee8123456",
"version": 1,
"includedInStatistics": true,
"authorName": "John Doe",
"title": "Incredible",
"text": "Best product ever",
"rating": 5,
"target": {
"typeId": "product",
"id": "8fddacac-6ef5-4e66-af6e-124452123456"
},
"customer": {
"typeId": "customer",
"id": "8a8b3e43-b9b0-4b30-8c27-58148123456"
},
"custom": {
"type": {
"typeId": "type",
"id": "3939dd9c-0884-4bfa-99c2-40b426123456"
},
"fields": {
"authorMail": "john.doe@example.com"
}
},
"createdAt": "2016-10-20T06:48:53.829Z",
"lastModifiedAt": "2016-10-20T06:48:53.829Z"
}
Delete Review by Key
manage_products:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ |
|
key String ​ |
|
version Int ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
dataErasure Boolean ​ | To erase all related personal data in compliance with GDPR, set to Default: false ​ |
application/json
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/reviews/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
{
"id": "919d5ab5-bf99-4bda-a6fd-ab3ee8123456",
"version": 1,
"includedInStatistics": true,
"authorName": "John Doe",
"title": "Incredible",
"text": "Best product ever",
"rating": 5,
"target": {
"typeId": "product",
"id": "8fddacac-6ef5-4e66-af6e-124452123456"
},
"customer": {
"typeId": "customer",
"id": "8a8b3e43-b9b0-4b30-8c27-58148123456"
},
"custom": {
"type": {
"typeId": "type",
"id": "3939dd9c-0884-4bfa-99c2-40b426123456"
},
"fields": {
"authorMail": "john.doe@example.com"
}
},
"createdAt": "2016-10-20T06:48:53.829Z",
"lastModifiedAt": "2016-10-20T06:48:53.829Z"
}