Reviews

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 - DateTime
• createdBy - CreatedBy BETA
  Present on resources created after 2019-02-01 except for events not tracked.
• lastModifiedAt - DateTime
• lastModifiedBy - LastModifiedBy BETA
  Present on resources updated after 2019-02-01 except for events not tracked.
• uniquenessValue - String - Optional
  This value must be unique among reviews. For example, if this value is set to customer's id + product's id, only one review per customer and per product is allowed.
• locale - String - Optional
  IETF language tag
• authorName - String - Optional
• title - String - Optional
• text - String - Optional
• target - Reference - Optional
  Identifies the target of the review. Can be a Product or a Channel
• rating - Number - Optional
  Number between -100 and 100 included.
• state - Reference to a State - Optional
• 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.
• 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 to customer's id + product's id.
• locale - String - Optional
  IETF language tag
• authorName - String - Optional
• title - String - Optional
• text - String - Optional
• target - ResourceIdentifier - Optional
  Identifies the target of the review. Can be a Product or a Channel
• state - ResourceIdentifier of a State - Optional
• rating - 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 role ReviewIncludedInStatistics.
• customer - ResourceIdentifier of 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 target
• lowestRating - Number
  Lowest rating of one target
• count- Number
  The number of ratings taken into account
• ratingsDistribution - 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

Get Review by ID

Endpoint: /{projectKey}/reviews/{id}
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}
Response Representation: Review

Get Review by Key

Endpoint: /{projectKey}/reviews/key={key}
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}
Response Representation: Review

Query Reviews

Endpoint: /{projectKey}/reviews
Method: GET
OAuth 2.0 Scopes: view_products:{projectKey}
Response Representation: PagedQueryResult with results containing an array of Review
Query Parameters:

• where - Query Predicate - Optional
• sort - Sort - Optional
• expand - Expansion - Optional
• limit - Number - Optional
• offset - Number - Optional

Create a Review

Endpoint: /{projectKey}/reviews
Method: POST
OAuth 2.0 Scopes: manage_products:{projectKey}
Request Representation: ReviewDraft
Response Representation: Review

This method produces the ReviewCreatedMessage.

Update Review

Update Review by ID

Endpoint: /{projectKey}/reviews/{id}
Method: POST
OAuth 2.0 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
OAuth 2.0 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
  If key is absent or null, the existing key, if any, will be removed.

Set Author Name

• action - String - "setAuthorName"
• authorName - String - Optional
  If authorName is absent or null, this field will be removed if it exists.

Set Customer

• action - String - "setCustomer"
• customer - ResourceIdentifier of a Customer - Optional
  The customer who created the review.
  If customer is absent or null, this field will be removed if it exists.

Set Rating

• action - String - "setRating"
• rating - Number - Optional
  Number between -100 and 100 included.
  If rating is absent or null, this field will be removed if it exists.

This update action produces the ReviewRatingSetMessage.

Set Target

• action - String - "setTarget"
• target - ResourceIdentifier - Optional
  Identifies the target of the review. Can be a Product or a Channel
  If target is absent or null, this field will be removed if it exists.

Set Text

• action - String - "setText"
• text - String - Optional
  If text is absent or null, this field will be removed if it exists.

Set Title

• action - String - "setTitle"
• title - String - Optional
  If title is absent or null, this field will be removed if it exists.

Set Locale

• action - String - "setLocale"
• locale - String - Optional
  If locale is absent or null, 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 of a State
• force - Boolean - Optional - Defaults to false

This update action produces the ReviewStateTransitionMessage.

Set Custom Type

This action sets or removes the custom type for an existing review. If present, this action overwrites any existing custom type and fields.

• action - String - "setCustomType"
• type - ResourceIdentifier of 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.

Set CustomField

Delete Review

Delete Review by ID

Endpoint: /{projectKey}/reviews/{id}
Method: DELETE
OAuth 2.0 Scopes: manage_products:{projectKey}
Query Parameters:

• version - Number - Required
• dataErasure - Boolean - Optional, defaults to false

Delete Review by Key

Endpoint: /{projectKey}/reviews/key={key}
Method: DELETE
OAuth 2.0 Scopes: manage_products:{projectKey}
Query Parameters:

• version - Number - Required
• dataErasure - Boolean - Optional, defaults to false