About the Reviews API

With the Reviews API you can manage reviews for a site's services, content, or products. The review object holds the content of the review, a rating score, images or video media, and information about the author. Learn more about Wix Reviews.

The Wix Reviews API allows your app to:

  • Import reviews from other sites and export reviews to other sites.
  • Retrieve and display positive review data. Use the Media API to retrieve associated review media.
  • Retrieve negative review data enabling site owners to respond effectively.

The Reviews API can be used in conjunction with the Ratings API to provide broader rating functionality. For example, the Ratings API enables rating of multiple attributes of a product such as comfort and value for money.

Moderation

If moderation is turned on, reviews are checked for content that requires moderation. If moderation is required, the review remains pending until the site owner rejects or approves it in the site's Dashboard. The site owner can configure moderation settings in the site's Dashboard. Learn more about managing reviews.

Before you begin

It’s important to note the following points before starting to code:

  • Every review needs a contact. To check whether a contact exists, your app can call the Contacts API with the author's email. If the author is already listed as a contact, use either Create Review or Create Review and Contact. If the author is not yet a site contact, use Create Review and Contact.
  • A review author is limited to one review per entity. Duplicate reviews receive an error response.
  • Replying to a review is available only in the site owner's Dashboard.

Use Cases

Terminology

  • Entity: The entity to review. For example, a Wix Stores product.
  • Namespace: The Wix module that the Reviews API is integrated with. Currently only Wix Stores.
  • Rating: The rating score for the review item. An author can give a rating score between 1 and 5. The rating is displayed with the site review.
  • Helpfulness: Helpfulness is the overall helpfulness score calculated by subtracting Found Unhelpful from Found Helpful. Site visitors can indicate whether a review was helpful or not.
  • Reply: A direct reply to a review that was left on the site. The reply is displayed with the review.
Was this helpful?
Yes
No

Reviews: Sample Use Cases and Flows

This article shares some possible use cases your app can support. You are not limited to these use cases, but they can be a helpful jumping off point as you plan your app's implementation.

Real-time 2-way sync with an eCommerce solution

Site owners can use your app to keep reviews from an eCommerce solution up to date with their reviews on Wix with a two-way sync. To synchronize Wix and the eCommerce solution, think about how your app will handle these flows:

  • Initial setup
  • Synchronize to the eCommerce solution
  • Synchronize to Wix

Initial setup

Create mappings for the following from the Wix site to the eCommerce solution using common fields so the reviews can be synced:

  • Wix site entities to entities in the eCommerce solution.
  • Wix site Contact IDs to author IDs in the eCommerce solution, for example using email addresses.
  • Wix review fields to the review fields in the eCommerce solution for example, title, body, author.

Store the mappings on your app's server. Then follow these flows to create the two-way sync.

Synchronize to the eCommerce solution

Listen for a change in Wix reviews with the following webhooks:

When one of the webhooks is triggered, you'll receive the review in the payload. You can send those changes to the eCommerce solution with a flow like this one:

  1. Get the slug (which tells you what the event was), entityId (ID of the review), and other relevant information from the payload data.

  2. Use the mappings from the initial setup to send the relevant information to the eCommerce solution.

  3. Ignore the resulting event from the eCommerce solution so you don’t create an endless loop of updates.

Synchronize to Wix

Listen for review events from the eCommerce solution. When your app receives a change it needs to synchronize, follow this basic flow:

  1. Use the Contacts API to check if the review author has a contact ID on the Wix site.

  2. The Reviews API allows only one review for each entity per contact. Use the mappings from the initial setup to filter out imported reviews if there is already a Wix site review from the contact for the entity.

  3. Use the mappings from the initial setup and call Create Review if the author is a contact. If the author is not a contact, call Create Review And Contact.

  4. Ignore the resulting event from Wix so you don’t create an endless loop of updates.

Display review media in a widget

Note: This flow requires Wix Blocks which is currently in Beta.

To enable a site owner to create a media gallery of photos from reviews, retrieve images from reviews and then display them in media layout.

  1. Use Query Reviews to retrieve reviews that have media.

  2. Extract the image.url from the response and use the Media API to retrieve the media.

  3. Display the retrieved media items in gallery layout in a widget using Wix Blocks. Learn more about Wix Blocks apps.

Get immediate updates of negative customer feedback

To enable a site owner to receive timely customer feedback, gain insights into product satisfaction, and identify areas for improvement, follow this basic flow.

  1. Listen for new reviews using the Review Created Webhook.

  2. Get the entityId (ID of the review), content, and any other relevant information from the payload data.

  3. Extract reviews from the payload that have content.rating less than 3.

  4. Provide the extracted review IDs to the site owner so they can reply in the Dashboard.

Display the most helpful product reviews in a widget

Note: This flow requires Wix Blocks which is currently in Beta.

To enable a site owner to display the most helpful reviews in order to promote products, follow this basic flow.

  1. Use Query Reviews to get a list of the 10 most helpful reviews, sorted by most to least helpful.

  2. Display the retrieved reviews in a widget using Wix Blocks. Learn more about Wix Blocks apps.

Was this helpful?
Yes
No

Reviews: Supported Filters and Sorting

The following table shows field support for filters and sorting for review properties:

FieldsSupported FiltersSortable
id$eq, $ne, $in
namespace$eq, $ne, $in
entityId$eq, $ne, $in
content.rating$eq, $ne, $in, $lt, $lte, $gt, $gteSortable
content.media$isEmpty
helpfulness$eq, $ne, $in, $lt, $lte, $gt, $gteSortable
moderation.moderationStatus$eq, $ne, $in
createdDate$eq, $ne, $in, $lt, $lte, $gt, $gteSortable
Was this helpful?
Yes
No

Review Object

A Review object includes all of the details related to the review of an entity. An entity is a specific resource to be reviewed, for example, a store product. You can manage existing reviews, create new reviews, and retrieve reviews. Read more about reviews in this tutorial.

Attributes
namespacestring
Review namespace. Currently integrated with Wix Stores, as stores.

entityIdstring
ID of the entity to review. For example, a Wix Stores product ID.

idstringRead-onlyformat GUID
Review ID.

contentobject
Review content.

createdDatestringRead-onlyformat date-time
Date and time the review was created.

updatedDatestringRead-onlyformat date-time
Date and time the review was updated.

authorobject
Author of the review.

replyobject
Reply to the review.

foundHelpfulintegerRead-only
Number of site visitors who found the review helpful.

foundUnhelpfulintegerRead-only
Number of site visitors who found the review unhelpful.

helpfulnessintegerRead-only
Helpfulness score. Calculated by subtracting foundUnhelpful from foundHelpful.

moderationobject
Moderation status of the review.

revisionobjectRead-only
Revision number, which increments by 1 each time the review is updated. To prevent conflicting changes, the current revision must be passed when updating the review. Ignored when creating a review.

verifiedbooleanRead-only
Indicates whether the review has been verified through a Verify Product Purchase call to the Review Product catalog SPI.

originobject
Provides information about the origin of the review. Organic reviews are created by site visitors or members. App reviews are created by apps even though a site visitor or member is the author of the review. Apps can not create or update organic reviews.

reviewDatestringformat date-time
Date and time then review was written. It should the same time as created_date except for reviews that were imported from the other review system.
Was this helpful?
Yes
No

GetGet Review

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves a review by ID.

To include unpublished reviews, pass returnPrivateReviews as true. By default, unpublished reviews are not returned.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Reviews
Read Reviews
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Endpoint
GET
https://www.wixapis.com/reviews/v1/reviews/{reviewId}

Was this helpful?
Yes
No

DeleteDelete Review

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Deletes a review by ID.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Reviews
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Endpoint
DELETE
https://www.wixapis.com/reviews/v1/reviews/{reviewId}

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PostCreate Review

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Creates a new review using a contact ID.

This endpoint requires a review.author.contactId. If the review author is not a contact, use Create Review and Contact. After a review is created, it may require moderation.

If authorName is left empty, the member's name will be used. If the author is not a member, the field is left null.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Reviews
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Endpoint
POST
https://www.wixapis.com/reviews/v1/reviews

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PatchUpdate Review

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Updates a review.

Each time the review is updated, revision increments by 1. The existing revision must be included when updating the review. This ensures you're working with the latest review information, and it prevents unintended overwrites.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Reviews
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Endpoint
PATCH
https://www.wixapis.com/reviews/v1/reviews/{review.id}

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PostQuery Reviews

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves a list of reviews, given the provided paging, filtering, and sorting. 100 reviews can be returned per request.

Query Reviews runs with these defaults, which you can override:

  • createdDate is sorted in ASC order
  • paging.limit is 100

For field support for filters and sorting, see Reviews: Supported Filters and Sorting. To learn about working with Query endpoints, see API Query Language.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Reviews
Read Reviews
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Endpoint
POST
https://www.wixapis.com/reviews/v1/reviews/query

Was this helpful?
Yes
No

Review Created

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when a review is created.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.reviews.v1.review.

slugstring
Event name. Expected created.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

createdEventobject
Event information.
Was this helpful?
Yes
No

Review Updated

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when a review is updated.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.reviews.v1.review.

slugstring
Event name. Expected updated.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

updatedEventobject
Event information.
Was this helpful?
Yes
No

Review Moderation Status Changed

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when moderation status is changed or a review is created.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.reviews.v1.review.

slugstring
Event name. Expected moderation_status_changed.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

actionEventobject
Event information.
Was this helpful?
Yes
No

Review Deleted

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when a review is deleted.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.reviews.v1.review.

slugstring
Event name. Expected deleted.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

deletedEventstruct
Event information.
Was this helpful?
Yes
No