The VTEX Reviews and Ratings API manages customer product reviews and star ratings for VTEX stores. It provides endpoints for submitting, retrieving, approving, and moderating reviews, enabling social proof features within VTEX storefronts.
openapi: 3.0.0
info:
title: VTex Reviews and Ratings API
description: "[Reviews & Ratings](https://developers.vtex.com/vtex-developer-docs/docs/vtex-reviews-and-ratings) is a VTEX IO app that allows shoppers to submit reviews and ratings for products, and view them while navigating the store. With the Reviews and Ratings API you can manage the reviews and ratings associated with the products in your store. \r\n\r\n ## Index \r\n\r\n ### Rating\r\n\r\n- `GET` [Get product rating](https://developers.vtex.com/docs/api-reference/reviews-and-ratings-api#get-/reviews-and-ratings/api/rating/-productId-)\r\n\r\n### Review\r\n\r\n- `GET` [Get product review by review ID](https://developers.vtex.com/docs/api-reference/reviews-and-ratings-api#get-/reviews-and-ratings/api/review/-reviewId-)\r\n- `DELETE` [Delete review](https://developers.vtex.com/docs/api-reference/reviews-and-ratings-api#delete-/reviews-and-ratings/api/review/-reviewId-)\r\n- `PATCH` [Update a review](https://developers.vtex.com/docs/api-reference/reviews-and-ratings-api#patch-/reviews-and-ratings/api/review/-reviewId-)\r\n- `GET` [Get a list of Reviews](https://developers.vtex.com/docs/api-reference/reviews-and-ratings-api#get-/reviews-and-ratings/api/reviews)\r\n- `POST` [Create Multiple Reviews](https://developers.vtex.com/docs/api-reference/reviews-and-ratings-api#post-/reviews-and-ratings/api/reviews)\r\n- `DELETE` [Delete Multiple Reviews](https://developers.vtex.com/docs/api-reference/reviews-and-ratings-api#delete-/reviews-and-ratings/api/reviews)\r\n- `POST` [Create a review](https://developers.vtex.com/docs/api-reference/reviews-and-ratings-api#post-/reviews-and-ratings/api/review)"
contact: {}
version: '1.0'
servers:
- url: https://{accountName}.myvtex.com
description: VTEX server URL
variables:
accountName:
description: Name of the VTEX account. Used as part of the URL.
default: storecomponents
paths:
/reviews-and-ratings/api/rating/{productId}:
get:
tags:
- Rating
summary: VTex Get product rating
description: "Retrieves the rating of a product.\r\n ## Permissions\r\n\r\nThis endpoint does not require [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3)."
operationId: GetProductRating
parameters:
- name: productId
in: path
description: Product ID.
required: true
style: simple
schema:
type: string
example: '1'
- name: Content-Type
in: header
description: Describes the type of the content being sent.
required: true
style: simple
schema:
type: string
default: application/json
- name: Accept
in: header
description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
default: application/json
responses:
'200':
description: OK
content:
application/json:
schema:
description: Response body object.
type: object
properties:
average:
description: Average rating of the product.
type: number
totalCount:
description: Total amount of ranting of the product.
type: number
example:
average: 3.86
totalCount: 7
'404':
description: Not Found
content:
application/json:
schema:
type: object
description: Response body object.
properties:
code:
type: string
description: Error type code.
message:
type: string
description: Error message.
source:
type: string
description: Error source.
requestId:
type: string
description: VTEX request identifier.
example:
code: NotFound
message: apiexamples.myvtex.com not found
source: Vtex.Kube.Router.WebApi
requestId: b49522afa7c94b76885450f652be7bfc
deprecated: false
/reviews-and-ratings/api/review/{reviewId}:
get:
tags:
- Review
summary: VTex Get product review by review ID
description: "Retrieves information of a product review based on the review's ID.\r\n\r\n ## Permissions\r\n\r\nThis endpoint does not require [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3)."
operationId: GetReviewbyReviewId
parameters:
- name: reviewId
in: path
description: Review ID.
required: true
style: simple
schema:
type: string
example: '1'
- name: Content-Type
in: header
description: Describes the type of the content being sent.
required: true
style: simple
schema:
type: string
default: application/json
- name: Accept
in: header
description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
default: application/json
responses:
'200':
description: OK
content:
application/json:
schema:
description: Response body object.
type: object
properties:
id:
description: Review ID.
type: string
productId:
description: Product ID.
type: string
rating:
description: Customer rating.
type: number
title:
description: Review's title.
type: string
text:
description: Review's text.
type: string
reviewerName:
description: Reviewer name.
type: string
shopperId:
description: Shopper email.
type: string
reviewDateTime:
description: Review's date and time.
type: string
searchDate:
description: Review's search date.
type: string
verifiedPurchaser:
description: Indicates if the reviewer is a verified purchaser (`true`) or not (`false`).
type: boolean
sku:
description: SKU ID.
type: string
nullable: true
approved:
description: Indicates if the review was approved (`true`) or not (`false`).
type: boolean
location:
description: Review's origin location.
type: string
nullable: true
locale:
description: Review's locale.
type: string
nullable: true
pastReviews:
description: Past reviews of the same product.
type: string
nullable: true
example:
id: 5323fdaa-c012-11ec-835d-0ebee58edbb3
productId: '1'
rating: 5
title: Great product
text: Great product.
reviewerName: Arturo
shopperId: [email protected]
reviewDateTime: 04/19/2022 18:55:58
searchDate: '2022-04-19T18:55:58Z'
verifiedPurchaser: false
sku: '2'
approved: false
location:
locale: en-US
pastReviews:
'404':
description: Not Found
content:
application/json:
schema:
type: object
description: Response body object.
properties:
code:
type: string
description: Error type code.
message:
type: string
description: Error message.
source:
type: string
description: Error source.
requestId:
type: string
description: VTEX request identifier.
example:
code: NotFound
message: apiexamples.myvtex.com.br not found
source: Vtex.Kube.Router.WebApi
requestId: b49522afa7c94b76885450f652be7bfc
'500':
description: Internal Server Error
deprecated: false
delete:
tags:
- Review
summary: VTex Delete review
description: "Deletes an existing review. \r\n\r\n ## Permissions\r\n\r\nThis endpoint does not require [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3)."
operationId: DeleteReview
parameters:
- name: reviewId
in: path
description: Review ID.
required: true
style: simple
schema:
type: string
example: '1'
- name: Content-Type
in: header
description: Describes the type of the content being sent.
required: true
style: simple
schema:
type: string
default: application/json
- name: Accept
in: header
description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
default: application/json
responses:
'200':
description: OK
content:
application/json:
schema:
description: Indicates if the review was deleted (`true`) or not (`false`).
type: boolean
example: true
security:
- appKey: []
appToken: []
- VtexIdclientAutCookie: []
deprecated: false
patch:
tags:
- Review
summary: VTex Update a review
description: "Updates the information of a review. \r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3)."
operationId: EditReview
parameters:
- name: reviewId
in: path
description: Review ID.
required: true
style: simple
schema:
type: string
example: 5323fdaa-c012-11ec-835d-0ebee58edbb3
- name: Content-Type
in: header
description: Describes the type of the content being sent.
required: true
style: simple
schema:
type: string
default: application/json
- name: Accept
in: header
description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
default: application/json
requestBody:
content:
application/json:
schema:
type: object
required:
- productId
- rating
- title
- text
- reviewerName
properties:
productId:
description: Product ID.
type: string
example: '1'
rating:
description: Customer rating.
type: number
example: 5
title:
description: Review's title.
type: string
example: Great product
text:
description: Review's text.
type: string
example: Great product.
reviewerName:
description: Reviewer name.
type: string
example: Arturo
shopperId:
description: Shopper email.
type: string
example: [email protected]
verifiedPurchaser:
description: Indicates if the reviewer is a verified purchaser (`true`) or not (`false`).
type: boolean
example: false
locale:
description: Review's locale.
type: string
nullable: true
example: en-US
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
description: Response body object.
type: object
properties:
id:
description: Review ID.
type: string
productId:
description: Product ID.
type: string
rating:
description: Customer rating.
type: number
title:
description: Review's title.
type: string
text:
description: Review's text.
type: string
reviewerName:
description: Reviewer name.
type: string
shopperId:
description: Shopper email.
type: string
reviewDateTime:
description: Review's date and time.
type: string
searchDate:
description: Review's search date.
type: string
verifiedPurchaser:
description: Indicates if the reviewer is a verified purchaser (`true`) or not (`false`).
type: boolean
sku:
description: SKU ID.
type: string
nullable: true
approved:
description: Indicates if the review was approved (`true`) or not (`false`).
type: boolean
location:
description: Review's origin location.
type: string
nullable: true
locale:
description: Review's locale.
type: string
nullable: true
pastReviews:
description: Past reviews of the same product.
type: string
nullable: true
example:
id: 5323fdaa-c012-11ec-835d-0ebee58edbb3
productId: '1'
rating: 5
title: Great product
text: Great product.
reviewerName: Arturo
shopperId: [email protected]
reviewDateTime: 04/19/2022 18:55:58
searchDate: '2022-04-19T18:55:58Z'
verifiedPurchaser: false
sku: '2'
approved: false
location:
locale: en-US
pastReviews:
deprecated: false
/reviews-and-ratings/api/reviews:
get:
tags:
- Review
summary: VTex Get list of reviews
description: "Retrieves a list of reviews related to a product.\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3)."
operationId: GetalistofReviews
parameters:
- name: search_term
in: query
description: Returns Reviews that contain the search term in `productId`, `sku`, `shopperId`, or `reviewerName`.
required: true
style: form
explode: true
schema:
type: string
example: search_term
- name: from
in: query
description: Zero base starting record number, `0` is the default value.
required: true
style: form
explode: true
schema:
type: string
example: '0'
- name: to
in: query
description: Zero base ending record number, `3` is the default value.
required: true
style: form
explode: true
schema:
type: string
example: '3'
- name: order_by
in: query
description: Case-sensitive fieldName to order records (optionally add `:asc` or `:desc`).
required: true
style: form
explode: true
schema:
type: string
example: ':asc'
- name: status
in: query
description: Status of the review, approved (`true`) or not (`false`).
required: true
style: form
explode: true
schema:
type: boolean
example: true
- name: product_id
in: query
description: Filter the reviews by product ID.
required: true
style: form
explode: true
schema:
type: string
example: '1'
- name: Content-Type
in: header
description: Describes the type of the content being sent.
required: true
style: simple
schema:
type: string
default: application/json
- name: Accept
in: header
description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
default: application/json
responses:
'200':
description: OK
content:
application/json:
schema:
description: Response body object.
type: object
properties:
data:
description: Array of reviews.
type: array
items:
description: Review's information.
type: object
properties:
id:
description: Review ID.
type: string
productId:
description: Product ID.
type: string
rating:
description: Customer rating.
type: number
title:
description: Review's title.
type: string
text:
description: Review's text.
type: string
reviewerName:
description: Reviewer name.
type: string
shopperId:
description: Shopper email.
type: string
reviewDateTime:
description: Review's date and time.
type: string
searchDate:
description: Review's search date.
type: string
verifiedPurchaser:
description: Indicates if the reviewer is a verified purchaser (`true`) or not (`false`).
type: boolean
sku:
description: SKU ID.
type: string
nullable: true
approved:
description: Indicates if the review was approved (`true`) or not (`false`).
type: boolean
location:
description: Review's origin location.
type: string
nullable: true
locale:
description: Review's locale.
type: string
nullable: true
pastReviews:
description: Past reviews of the same product.
type: string
nullable: true
range:
description: Range of the reviews list.
type: object
properties:
total:
description: Total number of reviews on the list.
type: number
from:
description: Zero base starting record number.
type: number
to:
description: Zero base ending record number.
type: number
example:
data:
- id: '1'
productId: '880035'
rating: 3
title: anon
text: anon
reviewerName: anon
shopperId: [email protected]
reviewDateTime: 06/02/2021 20:58:43
searchDate: '2021-06-02T20:58:43Z'
verifiedPurchaser: false
sku:
approved: true
location: ''
locale:
pastReviews:
- id: '2'
productId: '880035'
rating: 5
title: logged in
text: it's cool
reviewerName: Brian
shopperId: [email protected]
reviewDateTime: 06/02/2021 21:00:00
searchDate: '2021-06-02T21:00:00Z'
verifiedPurchaser: false
sku:
approved: true
location: ''
locale:
pastReviews:
- id: c66d8bc0-787c-11ec-82ac-028dd4526e77
productId: '880035'
rating: 3
title: Korean
text: ko-KR
reviewerName: ko-KR
shopperId: [email protected]
reviewDateTime: 01/18/2022 16:36:33
searchDate: '2022-01-18T16:36:33Z'
verifiedPurchaser: false
sku:
approved: true
location:
locale: ko-KR
pastReviews:
range:
total: 26
from: 0
to: 3
deprecated: false
post:
tags:
- Review
summary: VTex Create multiple reviews
description: "Creates multiple reviews for more than one product in a single operation.\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). \r\n For authentication, you must generate and use only the Application Key and the Application Token to work with this endpoint. Refer to the [API authentication using application keys](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) and [Generating internal application keys](https://help.vtex.com/en/tutorial/application-keys--2iffYzlvvz4BDMr6WGUtet#generating-internal-application-keys) guide for more information."
operationId: SaveMultipleReviews
parameters:
- name: Content-Type
in: header
description: Describes the type of the content being sent.
required: true
style: simple
schema:
type: string
default: application/json
- name: Accept
in: header
description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
default: application/json
requestBody:
content:
application/json:
schema:
type: array
description: List of reviews.
items:
$ref: '#/components/schemas/SaveMultipleReviewsRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
description: List of review IDs.
type: array
items:
description: Review ID.
type: string
example:
- 8e1a5e11-c0c9-11ec-835d-0a591b8a3ec1
- 9257c203-c0c9-11ec-835d-0e02dd207951
deprecated: false
delete:
tags:
- Review
summary: VTex Delete multiple reviews
description: "Deletes multiple reviews at once. \r\n\r\n ## Permissions\r\n\r\nThis endpoint does not require [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3)."
operationId: DeleteMultipleReviews
parameters:
- name: Content-Type
in: header
description: Describes the type of the content being sent.
required: true
style: simple
schema:
type: string
default: application/json
- name: Accept
in: header
description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
default: application/json
requestBody:
content:
application/json:
schema:
description: Array of reviews IDs.
type: array
items:
type: string
description: Review ID.
example: babefcf4-e0f7-11ec-835d-16c4e59c4351
responses:
'200':
description: OK
content:
application/json:
schema:
description: Indicates if the review was deleted (`true`) or not (`false`).
type: boolean
example: true
deprecated: false
/reviews-and-ratings/api/review:
post:
tags:
- Review
summary: VTex Create a review
description: "Creates a single review. \r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). \r\n For authentication, you must generate and use only your `VtexidClientAutCookie` to work with this endpoint. Refer to the [Generating user tokens](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens#generating-a-user-token-with-the-vtex-io-cli) guide for more information."
operationId: SaveReview
parameters:
- name: Content-Type
in: header
description: Describes the type of the content being sent.
required: true
style: simple
schema:
type: string
default: application/json
- name: Accept
in: header
description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
required: true
style: simple
schema:
type: string
default: application/json
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SaveReviewRequest'
example:
productId: '65444'
rating: 5
title: Good Product
text: It is the best product that I have seen
reviewerName: Arturo
approved: true
required: true
security:
- VtexIdclientAutCookie: []
responses:
'200':
description: OK
content:
application/json:
schema:
description: Response body object.
type: object
properties:
id:
description: Review ID.
type: string
productId:
description: Product ID.
type: string
rating:
description: Customer rating.
type: number
title:
description: Review's title.
type: string
text:
description: Review's text.
type: string
reviewerName:
description: Reviewer name.
type: string
shopperId:
description: Shopper email.
type: string
reviewDateTime:
description: Review's date and time.
type: string
searchDate:
description: Review's search date.
type: string
verifiedPurchaser:
description: Indicates if the reviewer is a verified purchaser (`true`) or not (`false`).
type: boolean
sku:
description: SKU ID.
type: string
nullable: true
approved:
description: Indicates if the review was approved (`true`) or not (`false`).
type: boolean
location:
description: Review's origin location.
type: string
nullable: true
locale:
description: Review's locale.
type: string
nullable: true
pastReviews:
description: Past reviews of the same product.
type: string
nullable: true
example:
id: 5323fdaa-c012-11ec-835d-0ebee58edbb3
productId: '65444'
rating: 5
title: Good Product
text: It is the best product that I have seen
reviewerName: Arturo
shopperId: [email protected]
reviewDateTime: 04/19/2022 18:55:58
searchDate: '2022-04-19T18:55:58Z'
verifiedPurchaser: false
sku: '2'
approved: false
location:
locale: en-US
pastReviews:
deprecated: false
security:
- appKey: []
appToken: []
- VtexIdclientAutCookie: []
components:
securitySchemes:
appKey:
type: apiKey
in: header
name: X-VTEX-API-AppKey
description: Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
appToken:
type: apiKey
in: header
name: X-VTEX-API-AppToken
description: Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
Vt
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vtex/refs/heads/main/openapi/vtex-reviews-ratings-openapi-original.yml