Storefront API Customer Reviews - WEBSALE Dokumentation

The Storefront API for customer reviews provides functions to create, retrieve, update, delete, and evaluate customer reviews. In addition, you can, for example, query the own review of a logged-in account, all approved reviews of a product, as well as statistical values. For the correct use of the customer reviews API, an x-session must always be sent. More about this here.

Supported methods

List of all supported methods.

Command	Endpoints	GET	POST	PUT	DELETE
Retrieve latest review	`account/rating/latest`
Retrieve all reviews	`account/rating/list`
Check existence of a review	`productRating/check`
Retrieve a specific review	`productRating/get`
Retrieve all reviews of a product	`productRating/get`
Retrieve review average of a product	`productRating/statistics`
Create review	`productRating/add`
Update review	`productRating/update`
Delete review	`productRating/update`

Methods for reviews within a customer account

These methods can be used to query reviews from the perspective of a specific customer account. This allows the frontend to display the current review of the customer after a review process or to reuse it in “My Account” areas (e.g. overview of own reviews).

GET account/rating/latest

The following call provides the most recently submitted customer review of the currently logged-in customer. Example call of the most recently submitted customer review of the logged-in account

GET https://<your-shop>.de/api/v1/account/rating/latest

Example response

{
   "accountId" : "126",
   "accountType" : 2,
   "anonymous" : false,
   "answeredAt" : "",
   "approval" : false,
   "createdAt" : "1970-01-01T00:00:00.000Z",
   "description" : "Description",
   "disapprovalReason" : "",
   "merchantComment" : "",
   "orderId" : "4857",
   "points" : 5,
   "productId" : "83-1782",
   "subject" : "Title",
   "subshopId" : "deutsch"
}

Parameter overview

Header parameters

Parameter	Description
`x-session`	Required field ID of the current session. More information: Storefront API Basics

GET account/rating/list

The following call lists all product reviews of the currently logged-in account. The command can be used, for example, to display a review overview in the customer account “My Account”.

GET https://<your-shop>.de/api/v1/account/rating/list

Parameter overview

Header parameters

Parameter	Description
`x-session`	Required field ID of the current session. More information: Storefront API Basics

Example response

{
  "items": [
    {
      "accountId": "126",
      "accountType": 2,
      "anonymous": false,
      "answeredAt": "",
      "approval": false,
      "createdAt": "1970-01-01T00:00:00.000Z",
      "description": "Description",
      "disapprovalReason": "",
      "merchantComment": "",
      "orderId": "4857",
      "points": 5,
      "productId": "12345",
      "subject": "Title",
      "subshopId": "deutsch"
    }
  ]
}

Methods for customer reviews (per order)

These methods are used to manage customer reviews that a customer has submitted for a particular product within a specific order. In addition, new reviews can be created, existing reviews can be changed, or deleted again. In addition, check and read methods are available to determine whether a review already exists for the combination of product and order and to retrieve this review in detail (e.g. after calling a review link in a service email).

GET productRating/get

This call retrieves — if available — the customer review already submitted for the specified combination of order and product in detail, in order to display it, for example, in forms or “My Account” views. Example call to retrieve a customer review for the product with the ID 99 from the order 0404-12

GET https://<your-shop>.de/api/v1/productRating/get?productId=99-0984&orderId=0404-12

Example response

{}

Parameter overview

Header parameters

Parameter	Description
`x-session`	Required field ID of the current session. More information: Storefront API Basics

Body parameters

Parameter	Type	Description
`productId`	string	Required field ID of the product for which the review was submitted.
`orderId`	string	Required field ID of the associated order via which the review is assigned to the purchase.

GET productRating/check

This method checks whether a customer review already exists for the specified combination of order and product (e.g. to control whether a review link or form should still be displayed). Example call to determine whether a customer review exists for the product with the ID 99 from the order with the ID 4857

GET https://<your-shop>.de/api/v1/productRating/check?productId=99-0984&orderId=4857

Example response

Example response if the review exists, otherwise you get “false” back:

{ "exists": true }

Parameter overview

Header parameters

Parameter	Description
`x-session`	Required field ID of the current session. More information: Storefront API Basics

Body parameters

Parameter	Type	Description
`productId`	string	Required field ID of the product for which it is checked whether a review exists.
`orderId`	string	Required field ID of the associated order via which the review is assigned to the purchase.

POST productRating/add

This method creates a new customer review for a specific combination of order orderId and product productId. Example call that submits a customer review for the product with the ID 99-0984 for the order with the ID 4900

POST https://<your-shop>.de/api/v1/productRating/add

Example request

{
  "productId": "99-0984",
  "orderId": "4900",
  "subject": "Title",
  "description": "My review",
  "points": 5,
  "anonymous": false
}

Example response

{}

Parameter overview

Header parameters

Parameter	Description
`x-session`	Required field ID of the current session. More information: Storefront API Basics

Body parameters

Parameter	Type	Description
`productId`	string	Required field ID of the product for which the review is to be submitted.
`orderId`	string	Required field ID of the order with which the purchase of the product is associated.
`subject`	string	Short title of the review
`description`	string	Free text of the review for product description / feedback
`points`	int	Required field Review value. This can be individually defined here: general - General shop settings
`anonymous`	bool	Publishes the review without personal attribution. Default: false

Error codes

Error code	Description
`orderNotExists`	The specified order does not exist in the system.
`duplicateRating`	A review has already been submitted for this product by this user.

PUT productRating/update

This method changes an existing customer review for a specific order orderId and a specific product productId, e.g. when the customer subsequently adjusts the text or star rating. Example call to change an already existing customer review for the product with the ID 99-0984 from the order with the ID 4900

PUT https://<your-shop>.de/api/v1/productRating/update

Example request

{
  "productId": "99-0984",
  "orderId": "4900",
  "subject": "Title",
  "description": "Description",
  "points": 5,
  "anonymous": false
}

Example response

{}

Parameter overview

Header parameters

Parameter	Description
`x-session`	Required field ID of the current session. More information: Storefront API Basics

Body parameters

Parameter	Type	Description
`productId`	string	Required field ID of the product for which the review is to be updated.
`orderId`	string	Required field ID of the order with which the purchase of the product is associated.
`subject`	string	Short title of the review
`description`	string	Free text of the review for product description / feedback
`points`	int	Review value. This can be individually defined here: general - General shop settings
`anonymous`	bool	Publishes the review without personal attribution. Default: false

DELETE productRating/update

This method deletes an existing customer review for a specific combination of order orderId and product productId so that it is no longer displayed in the frontend and no longer considered in evaluations. Example call to delete a customer review for the product with the ID 99-0984 for the order with the ID 4900

DELETE https://<your-shop>.de/api/v1/productRating/update

Example request

{
  "productId": "99-0984",
  "orderId": "4900"
}

Example response

{}

Parameter overview

Header parameters

Parameter	Description
`x-session`	Required field ID of the current session. More information: Storefront API Basics

Body parameters

Parameter	Type	Description
`productId`	string	Required field ID of the product whose review is to be deleted.
`orderId`	string	Required field ID of the order via which the review is assigned to the purchase.

Methods for review overviews per product

These methods provide all approved customer reviews as well as aggregated review information for a specific product.

GET productRating/list

This method retrieves all customer reviews available for the specified product. The returned data can be used in the frontend, for example, to display a complete review overview on the product detail page or in separate review lists. Example call to display all customer reviews for the product with the ID 99-0984

GET https://<your-shop>.de/api/v1/productRating/list?productId=99-0984

Example response

{
   "items" : [
      {
         "accountId" : "126",
         "accountType" : 2,
         "anonymous" : false,
         "answeredAt" : "",
         "approval" : true,
         "createdAt" : "1970-01-01T00:00:00.000Z",
         "description" : "Description",
         "disapprovalReason" : "",
         "displayName" : "Max Mustermann",
         "merchantComment" : "",
         "points" : 5,
         "productId" : "99-0984",
         "subject" : "Title",
         "subshopId" : "deutsch"
      }
   ]
}

Parameter overview Header parameters

Parameter	Description
`x-session`	Required field ID of the current session. More information: Storefront API Basics

Body parameters

Parameter	Type	Description
`productId`	string	Required field ID of the product for which reviews are to be retrieved.

GET productRating/statistics

This method retrieves the metrics calculated from all approved customer reviews for the specified product, in particular the average review value and the number of considered reviews. The data is particularly suitable for compact displays such as review stars and short review summaries on product detail pages or overview pages. Example call to load the statistics for the customer reviews for the product with the ID 99-0984

GET https://<your-shop>.de/api/v1/productRating/statistics?productId=99-0984

Parameter overview

Header parameters

Parameter	Description
`x-session`	Required field ID of the current session. More information: Storefront API Basics

Body parameters

Parameter	Type	Description
`productId`	string	Required field ID of the product for which reviews are to be retrieved.

Example response

{
   "averageRating" : 5,
   "productId" : "99-0984",
   "totalRatingCount" : 1
}

​Supported methods

​Methods for reviews within a customer account

​GET account/rating/latest

​Example response

​Parameter overview

​Header parameters

​GET account/rating/list

​Parameter overview

​Header parameters

​Example response

​Methods for customer reviews (per order)

​GET productRating/get

​Example response

​Parameter overview

​Header parameters

​Body parameters

​GET productRating/check

​Example response

​Parameter overview

​Header parameters

​Body parameters

​POST productRating/add

​Example request

​Example response

​Parameter overview

​Header parameters

​Body parameters

​Error codes

​PUT productRating/update

​Example request

​Example response

​Parameter overview

​Header parameters

​Body parameters

​DELETE productRating/update

​Example request

​Example response

​Parameter overview

​Header parameters

​Body parameters

​Methods for review overviews per product

​GET productRating/list

​GET productRating/statistics

​Parameter overview

​Header parameters

​Body parameters

​Example response

Supported methods

Methods for reviews within a customer account

GET account/rating/latest

Example response

Parameter overview

Header parameters

GET account/rating/list

Parameter overview

Header parameters

Example response

Methods for customer reviews (per order)

GET productRating/get

Example response

Parameter overview

Header parameters

Body parameters

GET productRating/check

Example response

Parameter overview

Header parameters

Body parameters

POST productRating/add

Example request

Example response

Parameter overview

Header parameters

Body parameters

Error codes

PUT productRating/update

Example request

Example response

Parameter overview

Header parameters

Body parameters

DELETE productRating/update

Example request

Example response

Parameter overview

Header parameters

Body parameters

Methods for review overviews per product

GET productRating/list

GET productRating/statistics

Parameter overview

Header parameters

Body parameters

Example response