Skip to content

List reviews

GET
/stores/{storeRef}/reviews
curl --request GET \
--url 'https://apibase.ecomweb.app/api/v1/stores/example/reviews?filters=%5B%7B%22field%22%3A%22status%22%2C%22operator%22%3A%22is%22%2C%22values%22%3A%5B%22PENDING%22%5D%7D%5D&sort_order=asc&limit=20&offset=0&status=PENDING' \
--header 'x-api-key: <x-api-key>'

Returns the store’s product reviews in pages, whatever their moderation status. By default pinned reviews come first, then the newest; set sort_by to change that. Filter with the query parameters or with filters. Pass include_replies=true to attach each review’s replies. Deleted reviews are not returned.

Required scopes: read:reviews

storeRef
required
string

The store’s ref, as returned by GET /stores.

search
string

Search review titles and content.

filters
string

Example

[{"field":"status","operator":"is","values":["PENDING"]}]

Filters as a JSON array of {field, operator, values} clauses, at most 10 clauses with at most 50 values each. Fields: status (is, is_not), rating (gte, lte), is_verified_buyer, has_media, has_reply, product_id (is) and created_at (gte, lte).

sort_by
string

Field to sort by: created_at, updated_at, rating, display_order or is_featured. Without it, pinned reviews come first, then the newest.

sort_order
string
Allowed values: asc desc

Sort direction. Applies only when sort_by is set; defaults to desc.

limit
number
default: 20 >= 1 <= 10000

Maximum number of reviews to return.

offset
number
0

Number of reviews to skip.

include_replies
string

Send true to include each review’s visible and hidden replies in review_replies.

product_id
string
/^\d+$/

Only reviews of this product ID.

status
string
Allowed values: PENDING APPROVED REJECTED HIDDEN

Only reviews with this status.

rating
number
>= 1 <= 5

Only reviews with this rating, 1 to 5.

min_rating
number
>= 1 <= 5

Only reviews with at least this rating, 1 to 5.

max_rating
number
>= 1 <= 5

Only reviews with at most this rating, 1 to 5.

is_verified_buyer
boolean

Send true for verified-buyer reviews only, false for the rest.

has_media
boolean

Send true for reviews with photos or media, false for reviews without.

has_reply
boolean

Send true for reviews that have a reply, false for reviews without one.

created_after
string

Only reviews created at or after this ISO 8601 timestamp.

created_before
string

Only reviews created at or before this ISO 8601 timestamp.

Media typeapplication/json
object
data
required
Array<object>
object
variant_id

ID of the reviewed variant, or null.

number
nullable
variant_name

Name of the reviewed variant, or null.

string
nullable
order_id

ID of the order the review is about, or null.

number
nullable
order_number

Number of the order the review is about, or null.

number
nullable
user_id

ID of the customer account that wrote the review, or null.

string
nullable
reviewer_avatar

URL of the reviewer’s avatar, or null.

string
nullable
title

Review title, or null.

string
nullable
media
required

Photos or other media attached to the review: a list of objects such as { "url": "https://...", "type": "image" }.

Array<object>
object
key
additional properties
any
status
required

Moderation status: PENDING, APPROVED, REJECTED or HIDDEN. Only APPROVED reviews are shown to shoppers.

string
Allowed values: PENDING APPROVED REJECTED HIDDEN
moderation_notes

Internal moderation notes, or null.

string
nullable
approved_by

ID of the user who approved the review, or null.

string
nullable
approved_at

When the review was approved, as an ISO 8601 timestamp, or null.

string
nullable
rejected_reason

Why the review was rejected, or null.

string
nullable
display_order

Position used when sorting by display_order, or null.

number
nullable
external_review_id

The review’s ID on the platform it was imported from, or null.

string
nullable
review_date

The date shown for the review, as an ISO 8601 timestamp, or null. Imported reviews keep their original date here.

string
nullable
deleted_at

When the review was deleted. Always null on reviews you can read.

string
nullable
review_replies

The review’s replies. Present only when replies are requested with include_replies on the list route.

Array<object>
object
deleted_at

When the reply was deleted. Always null on replies you can read.

string
nullable
id
required

Reply ID.

string
review_id
required

ID of the review the reply answers.

string
content
required

Reply text.

string
author_id
required

ID of the user who wrote the reply.

string
author_name
required

Name shown as the reply’s author.

string
is_visible
required

Whether the reply is shown to shoppers.

boolean
created_at
required

When the reply was created, as an ISO 8601 timestamp.

string
updated_at
required

When the reply was last updated, as an ISO 8601 timestamp.

string
id
required

Review ID.

string
product_id
required

ID of the reviewed product.

number
product_name
required

Name of the reviewed product when the review was written.

string
reviewer_name
required

Reviewer’s name.

string
reviewer_email
required

Reviewer’s email.

string
is_verified_buyer
required

Whether the reviewer bought the product from the store.

boolean
rating
required

Star rating, 1 to 5.

number
content
required

Review text.

string
pros
required

What the reviewer liked.

Array<string>
cons
required

What the reviewer disliked.

Array<string>
is_featured
required

Whether the review is featured.

boolean
is_pinned
required

Whether the review is pinned to the top of the list.

boolean
created_at
required

When the review was created, as an ISO 8601 timestamp.

string
updated_at
required

When the review was last updated, as an ISO 8601 timestamp.

string
meta
required
object
total
required

Total number of items matching the request.

number
limit
required

Maximum number of items in this page.

number
offset
required

Number of items skipped before this page.

number
page
required

Current page number, starting at 1.

number
totalPages
required

Total number of pages.

number
hasNext
required

Whether a next page exists.

boolean
hasPrev
required

Whether a previous page exists.

boolean

Example

{
"data": [
{
"status": "PENDING"
}
]
}

The request is malformed or failed validation.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key is missing, invalid, revoked or expired.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}