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

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

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:

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.

Set CustomField

  • action - String - "setCustomField"
  • name - String - Required
  • value - Value - Optional
    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, set the value of the field defined by the name.

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
Developer Center
HTTP APIGraphQL APIPlatform Release NotesCustom ApplicationsBETASDKs & Client LibrariesImport & ExportSUNRISE Starter FrontendsTutorialsFAQ
Merchant Center
DocumentationRelease Notes
Sign upLog inTech BlogIntegrationsStatusSupportUser Research Program
Copyright © 2021 commercetools
Privacy PolicyImprint