Reviews

Reviews are used to evaluate products and channels.

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.
  • version - Number
    The current version of the review.
  • createdAt - DateTime
  • lastModifiedAt - DateTime
  • key - String - Optional
    User-specific unique identifier for the review.
  • 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:

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
Please find below the individual update actions provided on this endpoint.

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.

This action overwrites any existing custom type and fields.

Set CustomField

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