> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Storefront API Customer Reviews

> Create, retrieve, update, delete, and evaluate customer reviews in the storefront with the Storefront API including statistics and per-account queries.

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](https://websaleag-44ee7ea6.mintlify.app/schnittstellen/storefront-api/storefront-api-basics#3-session-handling).

***

## Supported methods

List of all supported methods.

| **Command**                          | **Endpoints**              | **GET**               | **POST**              | **PUT**               | **DELETE**            |
| ------------------------------------ | -------------------------- | --------------------- | --------------------- | --------------------- | --------------------- |
| Retrieve latest review               | `account/rating/latest`    | <Icon icon="check" /> | <Icon icon="ban" />   | <Icon icon="ban" />   | <Icon icon="ban" />   |
| Retrieve all reviews                 | `account/rating/list`      | <Icon icon="check" /> | <Icon icon="ban" />   | <Icon icon="ban" />   | <Icon icon="ban" />   |
| Check existence of a review          | `productRating/check`      | <Icon icon="check" /> | <Icon icon="ban" />   | <Icon icon="ban" />   | <Icon icon="ban" />   |
| Retrieve a specific review           | `productRating/get`        | <Icon icon="check" /> | <Icon icon="ban" />   | <Icon icon="ban" />   | <Icon icon="ban" />   |
| Retrieve all reviews of a product    | `productRating/get`        | <Icon icon="check" /> | <Icon icon="ban" />   | <Icon icon="ban" />   | <Icon icon="ban" />   |
| Retrieve review average of a product | `productRating/statistics` | <Icon icon="check" /> | <Icon icon="ban" />   | <Icon icon="ban" />   | <Icon icon="ban" />   |
| Create review                        | `productRating/add`        | <Icon icon="ban" />   | <Icon icon="check" /> | <Icon icon="ban" />   | <Icon icon="ban" />   |
| Update review                        | `productRating/update`     | <Icon icon="ban" />   | <Icon icon="ban" />   | <Icon icon="check" /> | <Icon icon="ban" />   |
| Delete review                        | `productRating/update`     | <Icon icon="ban" />   | <Icon icon="ban" />   | <Icon icon="ban" />   | <Icon icon="check" /> |

## 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**

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<your-shop>.de/api/v1/account/rating/latest
```

#### Example response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
   "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**<br />ID of the current session.   <br />More information: [Storefront API Basics](../storefront-api/storefront-api-basics.md#2-session-handling) |

### 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".

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<your-shop>.de/api/v1/account/rating/list
```

#### Parameter overview

#### Header parameters

| **Parameter** | **Description**                                                                                                                                                                                                      |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session`   | **Required field**<br />ID of the current session.   <br />More information: [Storefront API Basics](https://websaleag-44ee7ea6.mintlify.app/schnittstellen/storefront-api/storefront-api-basics#3-session-handling) |

#### Example response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "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`

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<your-shop>.de/api/v1/productRating/get?productId=99-0984&orderId=0404-12
```

#### Example response

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{}
```

#### Parameter overview

#### Header parameters

| **Parameter** | **Description**                                                                                                                                                                                                      |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session`   | **Required field**<br />ID of the current session.   <br />More information: [Storefront API Basics](https://websaleag-44ee7ea6.mintlify.app/schnittstellen/storefront-api/storefront-api-basics#3-session-handling) |

#### 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`

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{ "exists": true }
```

#### Parameter overview

#### Header parameters

| **Parameter** | **Description**                                                                                                                                                                                                      |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session`   | **Required field**<br />ID of the current session.   <br />More information: [Storefront API Basics](https://websaleag-44ee7ea6.mintlify.app/schnittstellen/storefront-api/storefront-api-basics#3-session-handling) |

#### 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`

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
POST https://<your-shop>.de/api/v1/productRating/add
```

#### Example request

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "productId": "99-0984",
  "orderId": "4900",
  "subject": "Title",
  "description": "My review",
  "points": 5,
  "anonymous": false
}
```

#### Example response

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{}
```

#### Parameter overview

#### Header parameters

| **Parameter** | **Description**                                                                                                                                                                                                      |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session`   | **Required field**<br />ID of the current session.   <br />More information: [Storefront API Basics](https://websaleag-44ee7ea6.mintlify.app/schnittstellen/storefront-api/storefront-api-basics#3-session-handling) |

#### 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](/konfiguration/general-allgemeine-shopeinstellungen#generalproductrating-produktbewertung) |
| `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`

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
PUT https://<your-shop>.de/api/v1/productRating/update 
```

#### Example request

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "productId": "99-0984",
  "orderId": "4900",
  "subject": "Title",
  "description": "Description",
  "points": 5,
  "anonymous": false
}
```

#### Example response

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{}
```

#### Parameter overview

#### Header parameters

| **Parameter** | **Description**                                                                                                                                                                                                      |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session`   | **Required field**<br />ID of the current session.   <br />More information: [Storefront API Basics](https://websaleag-44ee7ea6.mintlify.app/schnittstellen/storefront-api/storefront-api-basics#3-session-handling) |

#### 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](/konfiguration/general-allgemeine-shopeinstellungen#generalproductrating-produktbewertung) |
| `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`

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
DELETE https://<your-shop>.de/api/v1/productRating/update
```

#### Example request

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "productId": "99-0984",
  "orderId": "4900"
}
```

#### Example response

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{}
```

#### Parameter overview

#### Header parameters

| **Parameter** | **Description**                                                                                                                                                                                                      |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session`   | **Required field**<br />ID of the current session.   <br />More information: [Storefront API Basics](https://websaleag-44ee7ea6.mintlify.app/schnittstellen/storefront-api/storefront-api-basics#3-session-handling) |

#### Body parameters

| **Parameter** | **Type** | **Description**                                                                           |
| ------------- | -------- | ----------------------------------------------------------------------------------------- |
| `productId`   | string   | **Required field**<br />ID of the product whose review is to be deleted.                  |
| `orderId`     | string   | **Required field**<br />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`

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<your-shop>.de/api/v1/productRating/list?productId=99-0984
```

**Example response**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
   "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**<br />ID of the current session.   <br />More information: [Storefront API Basics](https://websaleag-44ee7ea6.mintlify.app/schnittstellen/storefront-api/storefront-api-basics#3-session-handling) |

**Body parameters**

| **Parameter** | **Type** | **Description**                                                                  |
| ------------- | -------- | -------------------------------------------------------------------------------- |
| `productId`   | string   | **Required field**<br />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`

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<your-shop>.de/api/v1/productRating/statistics?productId=99-0984
```

#### Parameter overview

#### Header parameters

| **Parameter** | **Description**                                                                                                                                                                                                      |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session`   | **Required field**<br />ID of the current session.   <br />More information: [Storefront API Basics](https://websaleag-44ee7ea6.mintlify.app/schnittstellen/storefront-api/storefront-api-basics#3-session-handling) |

#### Body parameters

| **Parameter** | **Type** | **Description**                                                                  |
| ------------- | -------- | -------------------------------------------------------------------------------- |
| `productId`   | string   | **Required field**<br />ID of the product for which reviews are to be retrieved. |

#### Example response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
   "averageRating" : 5,
   "productId" : "99-0984",
   "totalRatingCount" : 1
}
```