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