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 - DateTime
• createdBy - CreatedBy beta
  Present on resources created after 1/02/2019 except for events not tracked.
• lastModifiedAt - DateTime
• lastModifiedBy - 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 - 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 to 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 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 target
• lowestRating - Number
  Lowest rating of one target
• count- Number
  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 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 - Optional
• sort - Sort - Optional
• expand - Expansion - Optional
• limit - Number - Optional
• offset - 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
  If key is absent or null, this field will be removed if it exists.

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 to 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 ReviewRatingSet message.

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 to a State
• force - Boolean - Optional - Defaults to false

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 - Required
• value - * - Optional
  If value is absent or null, this field will be removed if it exists.
  If value is provided, set the  value of the field defined by the name.
  The FieldDefinition determines the format for the value 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

Delete Review

Delete Review by ID

Endpoint: /{projectKey}/reviews/{id}
Method: DELETE
OAuth2 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
OAuth2 Scopes: manage_products:{projectKey}
Query Parameters:

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

• Representations
  • Review
  • ReviewDraft
  • ReviewRatingStatistics
• Get Review by ID
• Get Review by Key
• Query Reviews
• Create a Review
• Update Review
  • Update Review by ID
  • Update Review by Key
• Update Actions
  • Set Key
  • Set Author Name
  • Set Customer
  • Set Rating
  • Set Target
  • Set Text
  • Set Title
  • Set Locale
  • Transition State
  • Set Custom Type
  • Set CustomField
• Delete Review
  • Delete Review by ID
  • Delete Review by Key