VTEX Review API

openapi: 3.2.0
info:
  title: VTex Reviews and Ratings Review 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. \n\n ## Index \n\n ### Rating\n\n- `GET` [Get product rating](https://developers.vtex.com/docs/api-reference/reviews-and-ratings-api#get-/reviews-and-ratings/api/rating/-productId-)\n\n### Review\n\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-)\n- `DELETE` [Delete review](https://developers.vtex.com/docs/api-reference/reviews-and-ratings-api#delete-/reviews-and-ratings/api/review/-reviewId-)\n- `PATCH` [Update a review](https://developers.vtex.com/docs/api-reference/reviews-and-ratings-api#patch-/reviews-and-ratings/api/review/-reviewId-)\n- `GET` [Get a list of Reviews](https://developers.vtex.com/docs/api-reference/reviews-and-ratings-api#get-/reviews-and-ratings/api/reviews)\n- `POST` [Create Multiple Reviews](https://developers.vtex.com/docs/api-reference/reviews-and-ratings-api#post-/reviews-and-ratings/api/reviews)\n- `DELETE` [Delete Multiple Reviews](https://developers.vtex.com/docs/api-reference/reviews-and-ratings-api#delete-/reviews-and-ratings/api/reviews)\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
security:
- appKey: []
  appToken: []
- VtexIdclientAutCookie: []
tags:
- name: Review
paths:
  /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.\n\n ## Permissions\n\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
                    - 'null'
                  approved:
                    description: Indicates if the review was approved (`true`) or not (`false`).
                    type: boolean
                  location:
                    description: Review's origin location.
                    type:
                    - string
                    - 'null'
                  locale:
                    description: Review's locale.
                    type:
                    - string
                    - 'null'
                  pastReviews:
                    description: Past reviews of the same product.
                    type:
                    - string
                    - 'null'
              example:
                id: 5323fdaa-c012-11ec-835d-0ebee58edbb3
                productId: '1'
                rating: 5
                title: Great product
                text: Great product.
                reviewerName: Arturo
                shopperId: user@email.com
                reviewDateTime: 04/19/2022 18:55:58
                searchDate: '2022-04-19T18:55:58Z'
                verifiedPurchaser: false
                sku: '2'
                approved: false
                location: null
                locale: en-US
                pastReviews: null
        '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. \n\n ## Permissions\n\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. \n\n## Permissions\n\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: user@email.com
                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
                  - 'null'
                  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
                    - 'null'
                  approved:
                    description: Indicates if the review was approved (`true`) or not (`false`).
                    type: boolean
                  location:
                    description: Review's origin location.
                    type:
                    - string
                    - 'null'
                  locale:
                    description: Review's locale.
                    type:
                    - string
                    - 'null'
                  pastReviews:
                    description: Past reviews of the same product.
                    type:
                    - string
                    - 'null'
              example:
                id: 5323fdaa-c012-11ec-835d-0ebee58edbb3
                productId: '1'
                rating: 5
                title: Great product
                text: Great product.
                reviewerName: Arturo
                shopperId: user@email.com
                reviewDateTime: 04/19/2022 18:55:58
                searchDate: '2022-04-19T18:55:58Z'
                verifiedPurchaser: false
                sku: '2'
                approved: false
                location: null
                locale: en-US
                pastReviews: null
      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.

        ## Permissions


        This 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
                          - 'null'
                        approved:
                          description: Indicates if the review was approved (`true`) or not (`false`).
                          type: boolean
                        location:
                          description: Review's origin location.
                          type:
                          - string
                          - 'null'
                        locale:
                          description: Review's locale.
                          type:
                          - string
                          - 'null'
                        pastReviews:
                          description: Past reviews of the same product.
                          type:
                          - string
                          - 'null'
                  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: anon@email.com
                  reviewDateTime: 06/02/2021 20:58:43
                  searchDate: '2021-06-02T20:58:43Z'
                  verifiedPurchaser: false
                  sku: null
                  approved: true
                  location: ''
                  locale: null
                  pastReviews: null
                - id: '2'
                  productId: '880035'
                  rating: 5
                  title: logged in
                  text: it's cool
                  reviewerName: Brian
                  shopperId: brian@email.com.br
                  reviewDateTime: 06/02/2021 21:00:00
                  searchDate: '2021-06-02T21:00:00Z'
                  verifiedPurchaser: false
                  sku: null
                  approved: true
                  location: ''
                  locale: null
                  pastReviews: null
                - id: c66d8bc0-787c-11ec-82ac-028dd4526e77
                  productId: '880035'
                  rating: 3
                  title: Korean
                  text: ko-KR
                  reviewerName: ko-KR
                  shopperId: user@email.com
                  reviewDateTime: 01/18/2022 16:36:33
                  searchDate: '2022-01-18T16:36:33Z'
                  verifiedPurchaser: false
                  sku: null
                  approved: true
                  location: null
                  locale: ko-KR
                  pastReviews: null
                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.\n## Permissions\n\nThis endpoint does not require [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). \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. \n\n ## Permissions\n\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. \n## Permissions\n\nThis endpoint does not require [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). \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
                    - 'null'
                  approved:
                    description: Indicates if the review was approved (`true`) or not (`false`).
                    type: boolean
                  location:
                    description: Review's origin location.
                    type:
                    - string
                    - 'null'
                  locale:
                    description: Review's locale.
                    type:
                    - string
                    - 'null'
                  pastReviews:
                    description: Past reviews of the same product.
                    type:
                    - string
                    - 'null'
              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: user@email.com
                reviewDateTime: 04/19/2022 18:55:58
                searchDate: '2022-04-19T18:55:58Z'
                verifiedPurchaser: false
                sku: '2'
                approved: false
                location: null
                locale: en-US
                pastReviews: null
      deprecated: false
components:
  schemas:
    SaveReviewRequest:
      title: SaveReviewRequest
      required:
      - productId
      - rating
      - title
      - text
      - reviewerName
      - approved
      type: object
      description: Request body.
      properties:
        productId:
          description: Product ID.
          type: string
          example: '65444'
        rating:
          description: Customer rating.
          type: integer
          format: int32
          example: 5
        title:
          description: Review's title.
          type: string
          example: Good Product
        text:
          description: Review's text.
          type: string
          example: It is the best product that I have seen
        reviewerName:
          description: Reviewer name.
          type: string
          example: Arturo
        approved:
          description: Indicates if the review was approved (`true`) or not (`false`).
          type: boolean
          example: true
    SaveMultipleReviewsRequest:
      title: SaveMultipleReviewsRequest
      required:
      - productId
      - rating
      - title
      - text
      - reviewerName
      - approved
      type: object
      description: Request body.
      properties:
        id:
          description: Review ID.
          type: string
          example: '1'
        productId:
          description: Product ID.
          type: string
          example: '65444'
        rating:
          description: Customer rating.
          type: number
          example: 4
        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
        approved:
          description: Defines if the review was approved (`true`) or not (`false`).
          type: boolean
          example: true
  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).
    VtexIdclientAutCookie:
      type: apiKey
      in: header
      name: VtexIdclientAutCookie
      description: '[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours.'