API reference product ratings - WEBSALE Dokumentation

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/

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

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

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

{
    "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 or 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

https://www.<your-shop>.de/admin/api/v1/productRating/123

Response

{
    "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 or 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

https://www.<your-shop>.de/admin/api/v1/productRating/123

Request body

{
    "approval": false,
    "merchantComment": "",
    "disapprovalReason": "Bad rating"
}

Response

{
    "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 or you do not have the required permissions to write ratings.
404 Not Found		The rating was not found. 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. `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

https://www.<your-shop>.de/admin/api/v1/productRating/123

Response

{
    "success": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in or 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 Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.

​Supported methods

​Data fields ratings (rating resource)

​Example of a record

​Using the methods

​GET productRating

​Example

​Response

​Filter fields

​Sort fields

​Error codes

​GET productRating/{id}

​Example

​Response

​Error codes

​PUT productRating/{id}

​Example

​Request body

​Response

​Error codes

​DELETE productRating/{id}

​Example

​Response

​Error codes

​Support

Supported methods

Data fields ratings (rating resource)

Example of a record

Using the methods

GET productRating

Example

Response

Filter fields

Sort fields

Error codes

GET productRating/{id}

Example

Response

Error codes

PUT productRating/{id}

Example

Request body

Response

Error codes

DELETE productRating/{id}

Example

Response

Error codes

Support