Skip to main content
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.
CommandEndpointsGETPOSTPUTDELETE
Retrieve latest reviewaccount/rating/latest
Retrieve all reviewsaccount/rating/list
Check existence of a reviewproductRating/check
Retrieve a specific reviewproductRating/get
Retrieve all reviews of a productproductRating/get
Retrieve review average of a productproductRating/statistics
Create reviewproductRating/add
Update reviewproductRating/update
Delete reviewproductRating/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

ParameterDescription
x-sessionRequired 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

ParameterDescription
x-sessionRequired 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

ParameterDescription
x-sessionRequired field
ID of the current session.
More information: Storefront API Basics

​
Body parameters

ParameterTypeDescription
productIdstringRequired field ID of the product for which the review was submitted.
orderIdstringRequired 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

ParameterDescription
x-sessionRequired field
ID of the current session.
More information: Storefront API Basics

​
Body parameters

ParameterTypeDescription
productIdstringRequired field ID of the product for which it is checked whether a review exists.
orderIdstringRequired 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

ParameterDescription
x-sessionRequired field
ID of the current session.
More information: Storefront API Basics

​
Body parameters

ParameterTypeDescription
productIdstringRequired field ID of the product for which the review is to be submitted.
orderIdstringRequired field ID of the order with which the purchase of the product is associated.
subjectstringShort title of the review
descriptionstringFree text of the review for product description / feedback
pointsintRequired field Review value. This can be individually defined here: general - General shop settings
anonymousboolPublishes the review without personal attribution. Default: false

​
Error codes

Error codeDescription
orderNotExistsThe specified order does not exist in the system.
duplicateRatingA 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

ParameterDescription
x-sessionRequired field
ID of the current session.
More information: Storefront API Basics

​
Body parameters

ParameterTypeDescription
productIdstringRequired field ID of the product for which the review is to be updated.
orderIdstringRequired field ID of the order with which the purchase of the product is associated.
subjectstringShort title of the review
descriptionstringFree text of the review for product description / feedback
pointsintReview value. This can be individually defined here: general - General shop settings
anonymousboolPublishes 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

ParameterDescription
x-sessionRequired field
ID of the current session.
More information: Storefront API Basics

​
Body parameters

ParameterTypeDescription
productIdstringRequired field
ID of the product whose review is to be deleted.
orderIdstringRequired 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
ParameterDescription
x-sessionRequired field
ID of the current session.
More information: Storefront API Basics
Body parameters
ParameterTypeDescription
productIdstringRequired 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

ParameterDescription
x-sessionRequired field
ID of the current session.
More information: Storefront API Basics

​
Body parameters

ParameterTypeDescription
productIdstringRequired field
ID of the product for which reviews are to be retrieved.

​
Example response

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