openapi: 3.0.1
info:
  title: REVIEWS.io Company Reviews Product Reviews API
  description: REST API for the REVIEWS.io product and company reviews / user-generated content platform. Queue review invitations, retrieve product and company reviews, fetch ratings and statistics, manage questions, and subscribe to review-submitted webhooks. Requests are authenticated with a `store` (public store key) and `apikey` (private API key), available in the REVIEWS.io dashboard under Integrations -> API.
  termsOfService: https://www.reviews.io/terms
  contact:
    name: REVIEWS.io Support
    url: https://support.reviews.io
  version: '1.0'
servers:
- url: https://api.reviews.io
  description: REVIEWS.io production API
security:
- storeKey: []
  apiKey: []
tags:
- name: Product Reviews
  description: Retrieve, create, and vote on product reviews.
paths:
  /product/review:
    get:
      operationId: retrieveProductReviews
      tags:
      - Product Reviews
      summary: Retrieve product reviews
      description: Returns product reviews filtered by SKU or MPN with options for photos, verified-only, comments-only, minimum rating, and date ranges.
      parameters:
      - $ref: '#/components/parameters/store'
      - $ref: '#/components/parameters/apikey'
      - name: sku
        in: query
        schema:
          type: string
        description: One or more product SKUs separated by semicolons.
      - name: mpn
        in: query
        schema:
          type: string
        description: One or more product MPNs separated by semicolons.
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/perPage'
      - name: photos
        in: query
        schema:
          type: boolean
        description: Only return reviews that include photos.
      - name: verified_only
        in: query
        schema:
          type: boolean
        description: Only return verified reviews.
      - name: comments_only
        in: query
        schema:
          type: boolean
        description: Only return reviews that include a comment.
      - name: minRating
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 5
        description: Minimum star rating to include.
      - name: min_date
        in: query
        schema:
          type: string
        description: Filter reviews created on or after this date.
      - name: max_date
        in: query
        schema:
          type: string
        description: Filter reviews created on or before this date.
      responses:
        '200':
          description: Product reviews
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductReviewsResponse'
  /product/review/new:
    post:
      operationId: createProductReview
      tags:
      - Product Reviews
      summary: Create a new product review
      description: Creates a new product review for the supplied SKU.
      parameters:
      - $ref: '#/components/parameters/store'
      - $ref: '#/components/parameters/apikey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProductReviewRequest'
      responses:
        '200':
          description: Product review created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductReview'
  /product/vote:
    get:
      operationId: voteProductReview
      tags:
      - Product Reviews
      summary: Add to the vote count of a product review
      description: Increments the helpful-vote count of a single product review.
      parameters:
      - $ref: '#/components/parameters/store'
      - name: product_review_id
        in: query
        required: true
        schema:
          type: integer
        description: The identifier of the product review to vote on.
      responses:
        '200':
          description: Vote recorded
          content:
            application/json:
              schema:
                type: object
components:
  parameters:
    perPage:
      name: per_page
      in: query
      schema:
        type: integer
      description: Number of items per page.
    store:
      name: store
      in: query
      required: true
      schema:
        type: string
      description: Your REVIEWS.io public store key.
    page:
      name: page
      in: query
      schema:
        type: integer
      description: Results page number.
    apikey:
      name: apikey
      in: query
      required: false
      schema:
        type: string
      description: Your REVIEWS.io private API key (required for write and private data).
  schemas:
    ProductReviewsResponse:
      type: object
      properties:
        store:
          type: string
        word:
          type: string
        reviews:
          type: object
          properties:
            total:
              type: integer
            per_page:
              type: integer
            current_page:
              type: integer
            data:
              type: array
              items:
                $ref: '#/components/schemas/ProductReview'
    ProductReview:
      type: object
      properties:
        store_review_id:
          type: integer
        product:
          type: object
          properties:
            sku:
              type: string
            name:
              type: string
            mpn:
              type: string
        rating:
          type: integer
        title:
          type: string
        review:
          type: string
        date_created:
          type: string
        reviewer:
          type: object
          properties:
            first_name:
              type: string
            last_name:
              type: string
            verified_buyer:
              type: string
    CreateProductReviewRequest:
      type: object
      required:
      - sku
      - name
      - email
      - rating
      - review
      properties:
        sku:
          type: string
          description: Product SKU the review applies to.
        name:
          type: string
          description: Reviewer name.
        email:
          type: string
          format: email
          description: Reviewer email.
        rating:
          type: integer
          minimum: 1
          maximum: 5
          description: Star rating from 1 to 5.
        review:
          type: string
          description: Review body text.
        order_id:
          type: string
          description: Associated order reference.
        tags:
          type: string
          description: Comma-separated tags to apply to the review.
        address:
          type: string
          description: Reviewer address.
        ip_address:
          type: string
          description: Reviewer IP address.
        images:
          type: array
          description: Review images.
          items:
            type: string
        ratings:
          type: object
          description: Sub-ratings keyed by attribute.
        attribute:
          type: object
          description: Reviewer metadata attributes.
  securitySchemes:
    storeKey:
      type: apiKey
      in: header
      name: store
      description: Your REVIEWS.io public store key.
    apiKey:
      type: apiKey
      in: header
      name: apikey
      description: Your REVIEWS.io private API key.