Shopper Approved API

openapi: 3.1.0
info:
  title: Shopper Approved API
  description: >-
    The Shopper Approved API allows merchants to programmatically access their
    review data, submit order information for review collection, retrieve site
    statistics, manage product reviews, and update review follow-up details.
    Authentication uses a Site ID and API token passed as query parameters.
    Shopper Approved is a trusted source for Google Seller Ratings and enables
    merchants to collect and display verified customer reviews.
  version: '1.0'
  contact:
    name: Shopper Approved Support
    url: https://help.shopperapproved.com/
  termsOfService: https://www.shopperapproved.com/terms/
servers:
  - url: https://api.shopperapproved.com
    description: Shopper Approved API
security:
  - SiteIdToken: []
paths:
  /aggregates/{site_id}:
    get:
      operationId: getSiteStats
      summary: Get Site Statistics
      description: >-
        Retrieves aggregated review statistics for a site including overall
        rating, total review count, and distribution of ratings.
      tags:
        - Statistics
      parameters:
        - name: site_id
          in: path
          required: true
          description: Your Shopper Approved site ID
          schema:
            type: string
        - name: token
          in: query
          required: true
          description: Your Shopper Approved API token
          schema:
            type: string
      responses:
        '200':
          description: Site statistics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SiteStats'
  /reviews/{site_id}:
    get:
      operationId: listReviews
      summary: List Reviews
      description: >-
        Retrieves a list of customer reviews for the site. Supports filtering
        by date range and pagination via limit and page parameters.
      tags:
        - Reviews
      parameters:
        - name: site_id
          in: path
          required: true
          description: Your Shopper Approved site ID
          schema:
            type: string
        - name: token
          in: query
          required: true
          description: Your Shopper Approved API token
          schema:
            type: string
        - name: from
          in: query
          description: Start date for reviews (defaults to last 30 days if not specified)
          schema:
            type: string
            format: date
        - name: limit
          in: query
          description: Maximum number of reviews to return
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
            minimum: 1
            default: 1
      responses:
        '200':
          description: List of reviews retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  reviews:
                    type: array
                    items:
                      $ref: '#/components/schemas/Review'
                  total:
                    type: integer
                    description: Total number of reviews matching the query
                  page:
                    type: integer
                  limit:
                    type: integer
  /reviews/{site_id}/{review_id}:
    get:
      operationId: getReview
      summary: Get Review
      description: Retrieves a specific review by review ID (order ID).
      tags:
        - Reviews
      parameters:
        - name: site_id
          in: path
          required: true
          description: Your Shopper Approved site ID
          schema:
            type: string
        - name: review_id
          in: path
          required: true
          description: The order ID of the review to retrieve
          schema:
            type: string
        - name: token
          in: query
          required: true
          description: Your Shopper Approved API token
          schema:
            type: string
      responses:
        '200':
          description: Review retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Review'
  /orders/{site_id}:
    post:
      operationId: submitOrder
      summary: Submit Order
      description: >-
        Submits order information to Shopper Approved to trigger a review
        request to the customer at a specified follow-up date. Use this endpoint
        when you cannot use the survey script directly on your checkout page.
      tags:
        - Orders
      parameters:
        - name: site_id
          in: path
          required: true
          description: Your Shopper Approved site ID
          schema:
            type: string
        - name: token
          in: query
          required: true
          description: Your Shopper Approved API token
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderSubmission'
      responses:
        '200':
          description: Order submitted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
  /products/{site_id}:
    get:
      operationId: listProductReviews
      summary: List Product Reviews
      description: >-
        Retrieves a list of product-specific reviews for the site.
        Supports date filtering and pagination.
      tags:
        - Product Reviews
      parameters:
        - name: site_id
          in: path
          required: true
          description: Your Shopper Approved site ID
          schema:
            type: string
        - name: token
          in: query
          required: true
          description: Your Shopper Approved API token
          schema:
            type: string
        - name: from
          in: query
          description: Start date for product reviews
          schema:
            type: string
            format: date
        - name: limit
          in: query
          description: Maximum number of product reviews to return
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
            minimum: 1
            default: 1
      responses:
        '200':
          description: List of product reviews retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  reviews:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProductReview'
                  total:
                    type: integer
  /reviews/{site_id}/{review_id}/update:
    put:
      operationId: updateReview
      summary: Update Review
      description: >-
        Updates a review's follow-up date or marks a review as cancelled.
        Useful for adjusting when a follow-up email will be sent to the customer.
      tags:
        - Reviews
      parameters:
        - name: site_id
          in: path
          required: true
          description: Your Shopper Approved site ID
          schema:
            type: string
        - name: review_id
          in: path
          required: true
          description: The order ID of the review to update
          schema:
            type: string
        - name: token
          in: query
          required: true
          description: Your Shopper Approved API token
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReviewUpdate'
      responses:
        '200':
          description: Review updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
components:
  securitySchemes:
    SiteIdToken:
      type: apiKey
      in: query
      name: token
      description: Shopper Approved API token (used with site_id path parameter)
  schemas:
    SiteStats:
      type: object
      description: Aggregated statistics for a Shopper Approved site
      properties:
        site_id:
          type: string
          description: The site ID
        rating:
          type: number
          format: float
          description: Overall average rating (1-5)
        count:
          type: integer
          description: Total number of verified reviews
        five_star:
          type: integer
          description: Number of 5-star reviews
        four_star:
          type: integer
          description: Number of 4-star reviews
        three_star:
          type: integer
          description: Number of 3-star reviews
        two_star:
          type: integer
          description: Number of 2-star reviews
        one_star:
          type: integer
          description: Number of 1-star reviews
        name:
          type: string
          description: The site/merchant name
        domain:
          type: string
          description: The site domain
    Review:
      type: object
      description: A customer review submitted through Shopper Approved
      properties:
        reviewid:
          type: string
          description: The review ID (order ID)
        name:
          type: string
          description: Customer name (may be anonymized)
        date:
          type: string
          format: date
          description: Date the review was submitted
        rating:
          type: integer
          minimum: 1
          maximum: 5
          description: Customer rating (1-5 stars)
        review:
          type: string
          description: The customer's written review text
        headline:
          type: string
          description: Review headline or title
        verified:
          type: boolean
          description: Whether this is a verified purchase review
        location:
          type: string
          nullable: true
          description: Reviewer's location (city/state)
        helpful:
          type: integer
          description: Number of helpful votes
        unhelpful:
          type: integer
          description: Number of unhelpful votes
    ProductReview:
      type: object
      description: A product-specific review
      properties:
        reviewid:
          type: string
          description: The review ID
        product_id:
          type: string
          description: The product identifier
        product_name:
          type: string
          description: The product name
        name:
          type: string
          description: Customer name
        date:
          type: string
          format: date
          description: Date the review was submitted
        rating:
          type: integer
          minimum: 1
          maximum: 5
          description: Product rating (1-5 stars)
        review:
          type: string
          description: The product review text
        headline:
          type: string
          description: Review headline
        verified:
          type: boolean
          description: Verified purchase
    OrderSubmission:
      type: object
      description: Order information to submit for review collection
      required:
        - orderid
        - email
        - name
      properties:
        orderid:
          type: string
          description: Your unique order identifier
        email:
          type: string
          format: email
          description: Customer email address for the review request
        name:
          type: string
          description: Customer name
        date:
          type: string
          format: date
          description: Order date (YYYY-MM-DD)
        followup:
          type: string
          format: date
          description: Date to send the review request email (YYYY-MM-DD)
        products:
          type: array
          description: Products in the order for product reviews
          items:
            type: object
            properties:
              id:
                type: string
                description: Product identifier
              name:
                type: string
                description: Product name
              url:
                type: string
                format: uri
                description: Product URL
              image:
                type: string
                format: uri
                description: Product image URL
    ReviewUpdate:
      type: object
      description: Fields to update on a review
      properties:
        followup:
          type: string
          format: date
          description: New follow-up date for the review request (YYYY-MM-DD)
        cancelled:
          type: boolean
          description: Set to true to cancel the review request