openapi: 3.0.0
info:
  title: Shopify App Store Reviews API
  description: |
    Get the merchant reviews of a Shopify App Store app, 10 per page.

    Each review carries its 1-5 rating, date, text, the store's name and country, how long the store has used the app, and the developer's reply. The response also returns the app's name, developer, icon, overall rating, review count and the number of reviews at each star rating. Sort by relevance or newest, filter by star rating, and page through up to 1,000 pages.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Shopify App Store Reviews Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: 'Search engine. Must be set to: `shopify_app_store_reviews`'
          schema:
            type: string
            enum: ["shopify_app_store_reviews"]
        - name: app_id
          in: query
          required: true
          description: The app's handle from `apps.shopify.com/<app_id>`, such as `judgeme` or `klaviyo-email-marketing`, or an `apps.shopify.com` URL. The handle has up to 100 lowercase letters, digits and hyphens, starting with a letter or digit.
          schema:
            type: string
        - name: page
          in: query
          required: false
          description: Page of reviews, 10 per page.
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 1
        - name: sort_by
          in: query
          required: false
          description: Order of the reviews.
          schema:
            type: string
            enum: ["relevance", "newest"]
            default: "relevance"
        - name: rating
          in: query
          required: false
          description: Only reviews with these star ratings, comma-separated, such as `1` or `1,2`.
          schema:
            type: string
            pattern: '^[1-5](,[1-5]){0,4}$'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      required: [search_metadata, search_parameters]
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        app:
          type: object
          required: [name]
          properties:
            name:
              type: string
              description: App name.
            developer:
              type: string
              description: App developer.
            icon:
              type: string
              description: App icon URL.
            link:
              type: string
              description: App page on the Shopify App Store.
            rating:
              type: number
              description: Overall rating out of 5.
            reviews_count:
              type: integer
              description: Total number of reviews.
            review_summary:
              type: string
              description: Summary of what merchants say in their reviews.
            reviews_histogram:
              type: object
              description: Number of reviews at each star rating, keyed "5" to "1".
              additionalProperties:
                type: integer
        reviews:
          type: array
          items:
            $ref: '#/components/schemas/Review'
        pagination:
          type: object
          properties:
            current:
              type: integer
              description: Current page.
            next_page:
              type: integer
              description: Value to pass as `page` for the next page.
            total_pages:
              type: integer
              description: Number of pages available, up to 1,000.
        error:
          type: string
          description: Why there are no reviews to return.
    Review:
      type: object
      required: [position, review_id, rating, is_edited]
      properties:
        position:
          type: integer
          description: Position of the review across pages.
        review_id:
          type: string
          description: Shopify App Store identifier of the review.
        link:
          type: string
          description: Link to the review.
        rating:
          type: integer
          description: Star rating from 1 to 5.
        date:
          type: string
          format: date
          description: Date the review was posted.
        is_edited:
          type: boolean
          description: Whether the store edited the review after posting it.
        text:
          type: string
          description: Review text, with paragraphs on separate lines.
        store:
          type: object
          properties:
            name:
              type: string
              description: Name of the store that wrote the review.
            country:
              type: string
              description: Country of the store.
            time_used:
              type: string
              description: How long the store has used the app, as shown on the review.
        reply:
          type: object
          properties:
            author:
              type: string
              description: Name of the developer who replied.
            date:
              type: string
              format: date
              description: Date of the reply.
            text:
              type: string
              description: Reply text.
    SearchMetadata:
      type: object
      required: [status, created_at]
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to make the request in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the results in seconds
        total_time_taken:
          type: number
          description: Total time taken for the search in seconds
        request_url:
          type: string
          description: Shopify App Store URL for this search
        html_url:
          type: string
          description: URL to view HTML results
        json_url:
          type: string
          description: URL to view JSON results
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
        app_id:
          type: string
        page:
          type: integer
        sort_by:
          type: string
        rating:
          type: string
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
