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

# API reference product ratings

> Retrieve, filter, update, and delete product ratings through the Admin Interface API including average scores and customer account references.

The `/productRating` endpoint provides an interface to manage product ratings in our shop system. You can fetch, update, filter and delete product ratings.

***

## Supported methods

List of all supported methods.

| **Command/Info**   | **Endpoints**  | **GET**               | **POST**            | **PUT**               | **DELETE**            |
| ------------------ | -------------- | --------------------- | ------------------- | --------------------- | --------------------- |
| **General rating** | productRating/ | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="check" /> | <Icon icon="check" /> |

## Data fields ratings (rating resource)

Ratings are stored in a database table. There is another table for average values and the number of ratings of a product. This table is updated automatically, and its values are read when querying a single rating.

| Name               | Type    | Meaning                                                                           |
| ------------------ | ------- | --------------------------------------------------------------------------------- |
| accountId          | String  | ID of the customer account that submitted the rating                              |
| accountType        | Integer | Type of the customer account (e.g. guest (`1`) or registered customer (`3`))      |
| anonymous          | Boolean | `True` = rating was submitted anonymously, `False` = linked to a customer account |
| answeredAt         | String  | Time of the merchant response (ISO 8601 format, UTC)                              |
| approval           | Boolean | Indicates whether the rating has been approved                                    |
| categoryId         | String  | Category to which the rated product is assigned                                   |
| createdAt          | String  | Time when the rating was created (ISO 8601 format, UTC)                           |
| description        | String  | Detailed description or text of the rating                                        |
| disapprovalReason  | String  | Reason for rejecting the rating (if rejected)                                     |
| id                 | Integer | Unique ID of the rating                                                           |
| merchantComment    | String  | Merchant's response or comment on the rating                                      |
| orderId            | String  | ID of the order with which the product was purchased                              |
| points             | Number  | Awarded score, e.g. in the range 1–5                                              |
| productId          | String  | Technical ID of the rated product                                                 |
| productName        | String  | Current name of the product                                                       |
| productNumber      | String  | Article number of the product                                                     |
| productType        | String  | Product type (e.g. `standard`, `digital`)                                         |
| subject            | String  | Subject or title of the rating                                                    |
| subshopId          | String  | Subshop in which the rating was submitted                                         |
| averageRating      | Number  | Average rating score of the product                                               |
| totalRating        | Integer | Total number of ratings of the product                                            |
| variationSelection | Array   | Selected product variations from the corresponding order                          |
| orderSubshop       | String  | Subshop of the corresponding order                                                |

#### Example of a record

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "accountId": "1",
    "accountType": 0,
    "anonymous": false,
    "answeredAt": "2024-12-16 14:14:43",
    "approval": false,
    "categoryId": "911-78497",
    "createdAt": "2024-09-27 13:26:10",
    "description": "Meaningful description",
    "disapprovalReason": "You shall not pass",
    "id": 3,
    "merchantComment": "",
    "orderId": "233",
    "points": 2,
    "productId": "440-35068",
    "productName": "Regular product",
    "productNumber": "123456",
    "productType": "standard",
    "subject": "I do not like it",
    "subshopId": "deutsch"
}
```

## Using the methods

### GET productRating

Access ratings with filtering options.

#### Example

Access up to 100 unapproved ratings in the period 2024.12.02–2025.01.06.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/productRating?size=100&filter_gte[createdAt]=2024-12-02T00:00:00.000Z
&filter_lte[createdAt]=2025-01-05T23:59:59.000Z&filter_eq[approval]=false
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "endReached": true,
    "items": [
        {
            "accountId": "1",
            "accountType": 0,
            "anonymous": false,
            "answeredAt": "",
            "approval": false,
            "categoryId": "911-78497",
            "createdAt": "2024-09-27 13:26:10",
            "description": "Meaningful description",
            "disapprovalReason": "You shall not pass",
            "id": 3,
            "merchantComment": "",
            "orderId": "233",
            "points": 2,
            "productId": "440-35068",
            "productType": "standard",
            "subject": "I do not like it",
            "subshopId": "deutsch",

            "productName": "Regular product",
            "productNumber": "123456"
        }
    ],
    "nextPageToken": "MQ",
    "totalCount": 2
}
```

#### Filter fields

`id`, `productId`, `accountId`, `orderId`, `points`, `approval`, `createdAt`, `answeredAt`, `subject`, `disapprovalReason`, `anonymous`, `subshopId`

#### Sort fields

`createdAt`, `answeredAt`, `id`, `productId`, `accountId`, `orderId`, `points`, `approval`, `anonymous`, `subject`, `description`, `merchantComment`, `disapprovalReason`, `subshopId`

#### Error codes

| **Error**        | **Type**            | **Reason**                                                |
| ---------------- | ------------------- | --------------------------------------------------------- |
| 401 Unauthorized |                     | Not authorized: you are not logged in.                    |
| 403 Forbidden    |                     | You do not have the required permissions to read ratings. |
| 400 Bad Request  | "invalidValue"      |                                                           |
| 400 Bad Request  | "unknownDataField"  | A filter or sort field is invalid.                        |
| 400 Bad Request  | "unknownOperation"  | A filter type is invalid.                                 |
| 400 Bad Request  | "syntaxError"       | `sort` contains more than one or no ":".                  |
| 400 Bad Request  | "invalidCharacters" | `size` is not an integer.                                 |

### GET productRating/\{id}

Access a specific rating. The response also indicates how often the corresponding product has been rated and what the average value is. If a variation was selected, this is also returned.

#### Example

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

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "accountId": "1",
    "accountType": 0,
    "anonymous": false,
    "answeredAt": "2025-01-16 11:33:52",
    "approval": true,
    "categoryId": "911-78497",
    "createdAt": "2024-12-18 22:35:24",
    "description": "I recomend it",
    "disapprovalReason": "",
    "id": 2,
    "merchantComment": "Thanks!",
    "orderId": "233",
    "points": 4,
    "productId": "105-59442",
    "productType": "standard",
    "subject": "Good product",
    "subshopId": "deutsch",

    "averageRating": 4.0,
    "totalRating": 1,
    "variationSelection": [],
    "orderSubshop": "deutsch"
}
```

#### Error codes

| **Error**               | **Type**        | **Reason**                                                        |
| ----------------------- | --------------- | ----------------------------------------------------------------- |
| 401 Unauthorized        |                 | Not authorized: you are not logged in.                            |
| 403 Forbidden           |                 | You do not have the required permissions to read ratings.         |
| 404 Not Found           |                 | Rating statistics or the corresponding order could not be loaded. |
| 503 Service Unavailable | "internalError" | The rating could not be read.                                     |

### PUT productRating/\{id}

The rating with the specified id is updated. Only the fields shown in the example can be modified.

#### Example

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

#### Request body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "approval": false,
    "merchantComment": "",
    "disapprovalReason": "Bad rating"
}
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "accountId": "1",
    "accountType": 0,
    "anonymous": false,
    "answeredAt": "2025-01-16 11:33:52",
    "approval": false,
    "categoryId": "911-78497",
    "createdAt": "2024-12-18 22:35:24",
    "description": "Dislike!",
    "disapprovalReason": "Bad rating",
    "id": 2,
    "merchantComment": "",
    "orderId": "233",
    "points": 1,
    "productId": "105-59442",
    "productType": "standard",
    "subject": "Dislike",
    "subshopId": "deutsch",

    "averageRating": 4.0,
    "totalRating": 1,
    "variationSelection": [],
    "orderSubshop": "deutsch"
}
```

#### Error codes

| **Error**               | **Type**           | **Reason**                                                                                                        |
| ----------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized        |                    | Not authorized: you are not logged in.                                                                            |
| 403 Forbidden           |                    | You do not have the required permissions to write ratings.                                                        |
| 404 Not Found           |                    | The rating was not found.<br />Rating statistics or the corresponding order could not be loaded after the update. |
| 400 Bad Request         |                    | Request body could not be loaded.                                                                                 |
| 400 Bad Request         | "invalidFormat"    | `merchantComment` or `disapprovalReason` are not strings. <br />`approval` is not a boolean.                      |
| 400 Bad Request         | "unknownDataField" | A field that may not be updated is being updated.                                                                 |
| 503 Service Unavailable | "internalError"    | The update failed.                                                                                                |

### DELETE productRating/\{id}

The rating with the specified id is deleted.

#### Example

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

#### Response

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

#### Error codes

| **Error**               | **Type**        | **Reason**                                                  |
| ----------------------- | --------------- | ----------------------------------------------------------- |
| 401 Unauthorized        |                 | Not authorized: you are not logged in.                      |
| 403 Forbidden           |                 | You do not have the required permissions to delete ratings. |
| 404 Not Found           |                 | The rating was not found.                                   |
| 503 Service Unavailable | "internalError" | The deletion failed.                                        |

## Support

Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: [Zum Kundenportal](https://websale.atlassian.net/servicedesk/customer/portal/6)

Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.