Reviews

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 id + Product id, only one Review per Customer and per Product is allowed.

locale
Locale

Language in which the content of the Review is written.

Pattern: ^[a-z]{2}(-[A-Z]{2})?$
authorName
String

Name of the author.

title
String

Title of the Review.

text
String

Content of the Review.

target
ProductReference | ChannelReference

Identifies the target of the Review. Can be a Product or a Channel, specified as ProductReference or ChannelReference, respectively.

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 ReviewIncludedInStatistics. If the role of a State is modified after the calculation of this field, the calculation is not updated.

rating
Int

Rating of the Product or Channel.

Minimum: -100Maximum: 100
state

State of the Review. Used for approval processes, see Review approval process for details.

customer

Customer who created the Review.

custom

Custom Fields of the Review.

createdAt

Date and time (UTC) the Review was initially created.

createdByBETA

Present on resources created after 1 February 2019 except for events not tracked.

lastModifiedAt

Date and time (UTC) the Review was last updated.

lastModifiedByBETA

Present on resources created after 1 February 2019 except for events not tracked.

Example: json
{
"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 id + Product id.

locale

Language in which the content of the Review is written.

Pattern: ^[a-z]{2}(-[A-Z]{2})?$
authorName
String

Name of the author.

title
String

Title of the Review.

text
String

Content of the Review.

target
ProductResourceIdentifier | ChannelResourceIdentifier

Identifies the target of the Review. Can be a Product or a Channel, specified as ProductResourceIdentifier or ChannelResourceIdentifier, respectively.

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 ReviewIncludedInStatistics.

Minimum: -100Maximum: 100
customer

Customer who created the Review.

custom

Custom Fields for the Review.

Example: json
{
"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.

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 withTotal=false. When the results are filtered with a Query Predicate, total is subject to a limit.

offset
Int

Number of elements skipped.

results
Array of Review

Reviews matching the query.

Example: json
{
"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
String
"review"

References a Review.

obj

Contains the representation of the expanded Review. Only present in responses to requests with Reference Expansion for Reviews.

ReviewResourceIdentifier

id
String

Unique identifier of the referenced Review. Either id or key is required.

key
String

User-defined unique identifier of the referenced Review. Either id or key is required.

typeId
String
"review"

References a Review.

Get Review

Get Review by ID

GET
https://api.{region}.commercetools.com/{projectKey}/reviews/{id}
OAuth 2.0 Scopes:
view_products:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Review.

Query parameters:
expand
The parameter can be passed multiple times.
Response:

200Review

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/reviews/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Reviewjson
{
"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

GET
https://api.{region}.commercetools.com/{projectKey}/reviews/key={key}
OAuth 2.0 Scopes:
view_products:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the Review.

Query parameters:
expand
The parameter can be passed multiple times.
Response:

200Review

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/reviews/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Reviewjson
{
"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

GET
https://api.{region}.commercetools.com/{projectKey}/reviews
OAuth 2.0 Scopes:
view_products:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
where
The parameter can be passed multiple times.
/^var[.][a-zA-Z0-9]+$/
Any string parameter matching this regular expression

Predicate parameter values.

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
offset
Int

Number of elements skipped.

withTotal
Boolean

Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.

Response:

200ReviewPagedQueryResponse

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/reviews -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: ReviewPagedQueryResponsejson
{
"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"
} ]
}

Create a Review

POST
https://api.{region}.commercetools.com/{projectKey}/reviews
OAuth 2.0 Scopes:
manage_products:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:ReviewDraft
Response:

201Review

Request Example:cURL
curl -X POST 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
201 Response Example: Reviewjson
{
"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

POST
https://api.{region}.commercetools.com/{projectKey}/reviews/{id}
OAuth 2.0 Scopes:
manage_products:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Review.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
version
Int

The expected version of the review on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.

actions
Array of ReviewUpdateAction

The list of update actions to be performed on the review.

Response:

200Review

Request Example:cURL
curl -X POST 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
200 Response Example: Reviewjson
{
"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

POST
https://api.{region}.commercetools.com/{projectKey}/reviews/key={key}
OAuth 2.0 Scopes:
manage_products:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the Review.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
version
Int

The expected version of the review on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.

actions
Array of ReviewUpdateAction

The list of update actions to be performed on the review.

Response:

200Review

Request Example:cURL
curl -X POST 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
200 Response Example: Reviewjson
{
"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.

Example: json
{
"action" : "setKey",
"key" : "myReviewKey"
}

Set Author Name

action
String
"setAuthorName"
authorName
String

Value to set. If empty, any existing value will be removed.

Example: json
{
"action" : "setAuthorName",
"authorName" : "myAuthorName"
}

Set Customer

action
String
"setCustomer"
customer

Value to set. If empty, any existing value will be removed.

Example: json
{
"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: -100Maximum: 100
Example: json
{
"action" : "setRating",
"rating" : 60
}

Set Target

action
String
"setTarget"
target
ProductResourceIdentifier | ChannelResourceIdentifier

Value to set, specified as ProductResourceIdentifier or ChannelResourceIdentifier, respectively. If empty, any existing value will be removed.

Example: json
{
"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.

Example: json
{
"action" : "setText",
"text" : "reviewText"
}

Set Title

action
String
"setTitle"
title
String

Value to set. If empty, any existing value will be removed.

Example: json
{
"action" : "setTitle",
"title" : "reviewTitle"
}

Set Locale

action
String
"setLocale"
locale

Value to set. If empty, any existing value will be removed.

Pattern: ^[a-z]{2}(-[A-Z]{2})?$
Example: json
{
"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 transitions set, there must be a direct transition to the new State. If transitions is not set, no validation is performed. If the new State does not have the role ReviewIncludedInStatistics, the Review is not taken into account in the ratings statistics of the target.

force
Boolean

Switch validations on or off.

Default: false
Example: json
{
"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.

Example: json
{
"action" : "setCustomType",
"type" : {
"id" : "{{type-id}}",
"typeId" : "type"
},
"fields" : {
"examplaryStringTypeField" : "TextString"
}
}

Set CustomField

action
String
"setCustomField"
name
String

Name of the Custom Field.

value

If value is absent or null, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
"action" : "setCustomField",
"name" : "ExamplaryStringTypeField",
"value" : "TextString"
}

Delete Review

Delete Review by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/reviews/{id}
OAuth 2.0 Scopes:
manage_products:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Review.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
dataErasure
Boolean

Defaults to false. Set to true if you want to erase all related personal data in compliance with GDPR.

Response:

200Review

Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/reviews/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Reviewjson
{
"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

DELETE
https://api.{region}.commercetools.com/{projectKey}/reviews/key={key}
OAuth 2.0 Scopes:
manage_products:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the Review.

Query parameters:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
dataErasure
Boolean

Defaults to false. Set to true if you want to erase all related personal data in compliance with GDPR.

Response:

200Review

Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/reviews/key={key}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Reviewjson
{
"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"
}