Reviews
On our tutorial page you can find some instructions on how to use reviews to rate products and channels.
Representations
Review
id
- String
The unique ID of the review.key
- String - Optional
User-specific unique identifier for the review.version
- Number
The current version of the review.createdAt
- DateTimecreatedBy
- CreatedBy beta
Present on resources created after 1/02/2019 except for events not tracked.lastModifiedAt
- DateTimelastModifiedBy
- LastModifiedBy beta
Present on resources updated after 1/02/2019 except for events not tracked.uniquenessValue
- String - Optional-
locale
- String - Optional
↗ IETF language tag authorName
- String - Optionaltitle
- String - Optionaltext
- String - Optionaltarget
- Reference - Optional
Identifies the target of the review. Can be a Product or a Channelrating
- Number - Optional
Number between -100 and 100 included.state
- Reference to a State - OptionalincludedInStatistics
- 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 roleReviewIncludedInStatistics
.
If the role of a State is modified after the calculation of this field, the calculation is not updated.customer
- Reference to a Customer - Optional
The customer who created the review.custom
- CustomFields - Optional
ReviewDraft
key
- String - Optional
User-specific unique identifier for the review.uniquenessValue
- String - Optional
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 tocustomer's id
+product's id
.-
locale
- String - Optional
↗ IETF language tag authorName
- String - Optionaltitle
- String - Optionaltext
- String - Optionaltarget
- ResourceIdentifier - Optional
Identifies the target of the review. Can be a Product or a Channelstate
- ResourceIdentifier to a State - Optionalrating
- Number - Optional
Number between -100 and 100 included.
Rating of the targeted object, like a product.
This rating can represent the number of stars, or 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 roleReviewIncludedInStatistics
.customer
- ResourceIdentifier to a Customer - Optional
The customer who created the review.custom
- CustomFields - Optional
When creating a new review, at least one of title
, text
or rating
should be set.
ReviewRatingStatistics
averageRating
- Number
Average rating of one target
This number is rounded with 5 decimals.highestRating
- Number
Highest rating of one targetlowestRating
- Number
Lowest rating of one targetcount
- Number
Number of ratings taken into accountratingsDistribution
- JSON object
The 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.
Get Review by ID
Endpoint: /{projectKey}/reviews/{id}
Method: GET
OAuth2 Scopes: view_products:{projectKey}
Response Representation: Review
Get Review by Key
Endpoint: /{projectKey}/reviews/key={key}
Method: GET
OAuth2 Scopes: view_products:{projectKey}
Response Representation: Review
Query Reviews
Endpoint: /{projectKey}/reviews
Method: GET
OAuth2 Scopes: view_products:{projectKey}
Response Representation: PagedQueryResult with the results
array of Review
Query Parameters:
where
- Query Predicate - Optionalsort
- Sort - Optionalexpand
- Expansion - Optionallimit
- Number - Optionaloffset
- Number - Optional
Create a Review
Endpoint: /{projectKey}/reviews
Method: POST
OAuth2 Scopes: manage_products:{projectKey}
Request Representation: ReviewDraft
Response Representation: Review
This method produces the ReviewCreated message.
Update Review
Update Review by ID
Endpoint: /{projectKey}/reviews/{id}
Method: POST
OAuth2 Scopes: manage_products:{projectKey}
Response Representation: Review
Fields:
version
- Number - Required
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 UpdateAction - Required
The list of update actions to be performed on the review.
Update Review by Key
Endpoint: /{projectKey}/reviews/key={key}
Method: POST
OAuth2 Scopes: manage_products:{projectKey}
Response Representation: Review
Fields:
version
- Number - Required
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 UpdateAction - Required
The list of update actions to be performed on the review.
Update Actions
Set Key
action
- String -"setKey"
key
- String - Optional
Ifkey
is absent ornull
, this field will be removed if it exists.
Set Author Name
action
- String -"setAuthorName"
authorName
- String - Optional
IfauthorName
is absent ornull
, this field will be removed if it exists.
Set Customer
action
- String -"setCustomer"
customer
- ResourceIdentifier to a Customer - Optional
The customer who created the review.
Ifcustomer
is absent ornull
, this field will be removed if it exists.
Set Rating
action
- String -"setRating"
rating
- Number - Optional
Number between -100 and 100 included.
Ifrating
is absent ornull
, this field will be removed if it exists.
This update action produces the ReviewRatingSet message.
Set Target
action
- String -"setTarget"
target
- ResourceIdentifier - Optional
Identifies the target of the review. Can be a Product or a Channel
Iftarget
is absent ornull
, this field will be removed if it exists.
Set Text
action
- String -"setText"
text
- String - Optional
Iftext
is absent ornull
, this field will be removed if it exists.
Set Title
action
- String -"setTitle"
title
- String - Optional
Iftitle
is absent ornull
, this field will be removed if it exists.
Set Locale
action
- String -"setLocale"
locale
- String - Optional
Iflocale
is absent ornull
, this field will be removed if it exists.
Transition State
Transition to a new state. 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.
These validations can be turned off by using the force
parameter. If the new state does not have the
role ReviewIncludedInStatistics
, the review is not taken into account in
the ratings statistics of the target.
action
- String -"transitionState"
state
- ResourceIdentifier to a Stateforce
- Boolean - Optional - Defaults tofalse
This update action produces the ReviewStateTransition message.
Set Custom Type
This action sets or removes the custom type for an existing review.
action
- String -"setCustomType"
type
- ResourceIdentifier to a Type - Optional
If absent, the custom type and any existing custom fields are removed.fields
- * - Optional
A valid JSON object, based on the FieldDefinitions of the Type. Sets the CustomFields to this value.
This action overwrites any existing custom type and fields.
Set CustomField
action
- String -"setCustomField"
name
- String - Requiredvalue
- * - Optional
Ifvalue
is absent ornull
, this field will be removed if it exists.
Ifvalue
is provided, set thevalue
of the field defined by thename
.
The FieldDefinition determines the format for thevalue
to be provided.
In particular, for the fields definitions,value
has to be provided as:- for EnumType and LocalizedEnumType fields: the
key
of the EnumValue or the LocalizedEnumValue - for LocalizedStringType fields: the LocalizedString object
- for MoneyType fields: the Money object
- for SetType fields: the entire
Set
object - for ReferenceType fields: the Reference object
- for EnumType and LocalizedEnumType fields: the
Delete Review
Delete Review by ID
Endpoint: /{projectKey}/reviews/{id}
Method: DELETE
OAuth2 Scopes: manage_products:{projectKey}
Query Parameters:
version
- Number - RequireddataErasure
- Boolean - Optional, defaults tofalse
Delete Review by Key
Endpoint: /{projectKey}/reviews/key={key}
Method: DELETE
OAuth2 Scopes: manage_products:{projectKey}
Query Parameters:
version
- Number - RequireddataErasure
- Boolean - Optional, defaults tofalse