Search product reviews

GET https://app.ecwid.com/api/v3/{storeId}/reviews

Request and response example

Request:

GET /api/v3/1003/reviews HTTP/1.1
Authorization: Bearer secret_token
Host: app.ecwid.com

Response:

{
  "total": 2,
  "count": 2,
  "offset": 0,
  "limit": 100,
  "items": [
    {
      "id": 712737671,
      "status": "published",
      "customerId": 8108179152,
      "productId": 123456,
      "orderId": "2D31G",
      "rating": 5,
      "review": "Just what I need",
      "reviewerInfo": {
        "name": "Abraham Smith",
        "email": "[email protected]",
        "city": "New York",
        "orders": 2
      },
      "createDate": "2025-02-26 13:37:46 +0000",
      "updateDate": "2025-02-27 04:40:33 +0000",
      "createTimestamp": 1740562666,
      "updateTimestamp": 1740616833
    },
    {
      "id": 812738127,
      "status": "published",
      "customerId": 239921001,
      "productId": 123456,
      "orderId": "HI88G",
      "rating": 5,
      "review": "A really good product. Definitely worth buying!",
      "reviewerInfo": {
        "name": "John Doe",
        "email": "[email protected]",
        "city": "New York",
        "orders": 1
      },
      "createDate": "2024-12-02 10:00:00 +0000",
      "updateDate": "2024-12-02 10:00:00 +0000",
      "createTimestamp": 1733119200,
      "updateTimestamp": 1733119200
    }
  ]
}

Required access scopes

Your app must have the following access scopes to make this request: read_reviews

Path params

All path params are required.

Param	Type	Description
storeId	number	Ecwid store ID.

Query params

All query params are optional.

Name	Type	Description
status	boolean	Search term for the review status. One of: moderated - Review is not yet published by the store owner. published - Review is published by the store owner.
rating	number	Search term for the review 5-star rating (from 1 to 5).
orderId	string	Search by the order ID associated with the review.
productId	number	Search by the product ID associated with the review.
reviewId	number	Search by the internal review ID.
createdFrom	number/string	Review creation datetime (lower bound). Supported formats: UNIX timestamp, date/time. For example: 1447804800, 2023-01-15 19:27:50
createdTo	number/string	Review creation datetime (upper bound). Supported formats: UNIX timestamp, date/time. For example: 1447804800, 2023-01-15 19:27:50-
updatedFrom	number/string	Review latest update datetime (lower bound). Supported formats: UNIX timestamp, date/time. For example: 1447804800, 2023-01-15 19:27:50
updatedTo	number/string	Review latest update datetime (upper bound). Supported formats: UNIX timestamp, date/time. For example: 1447804800, 2023-01-15 19:27:50
sortBy	string	Define review sorting in the response. One of: DATE_CREATED_ASC DATE_CREATED_DESC RATING_ASC RATING_DESC
keyword	string	Search term for the customer's review text (review field).
responseFields	string	Specify the exact fields to receive in response JSON. If not specified, the response JSON will have all available fields for the entity. For example: ?responseFields=items(id,status,rating)

Headers

The Authorization header is required.

Header	Format	Description
Authorization	Bearer secret_ab***cd	Access token of the application.

Response JSON

A JSON object with the following fields:

Field	Type	Description
total	number	Total number of found items (might be more than the number of returned items).
count	number	Total number of items returned in the response.
offset	number	Offset from the beginning of the returned items list specified in the request.
limit	number	Maximum number of returned items specified in the request. Maximum and default value: 100.
items	array of objects items	Detailed information about returned reviews.

items

Field	Type	Description
id	number	Internal unique review ID.
status	string	Review publication status. One of: moderated - Review is not yet published by the store owner. published - Review is published by the store owner.
rating	number	5-star rating of the review. (from 1 to 5).
orderId	string	Order ID associated with the review.
productId	number	Product ID associated with the review.
customerId	number	Customer ID associated with the review.
review	string	Review text left by the customer.
reviewerInfo	object reviewerInfo	Details about the customer who placed the review.
createDate	string	Datetime when customer left the review in date format. For example, 2024-05-26 13:37:46 +0000
updateDate	string	Datetime of the latest review update in date format. For example, 2024-05-26 13:37:46 +0000
createTimestamp	number	Datetime when customer left the review in UNIX timestamp format. For example, 1622036266926
updateTimestamp	number	Datetime of the latest review update in UNIX timestamp format. For example, 1622036266926

reviewerInfo

Field	Type	Description
name	string	Name of the customer who left the review.
email	string	Email of the customer who left the review.
country	string	Country specified by the customer in an order associated with the review.
city	string	City specified by the customer in an order associated with the review.
orders	number	Amount of orders placed by the customer who left the review.