Wish Ratings API

openapi: 3.2.0
info:
  contact:
    email: partner-api@wish.com
  x-wish-dev-contact:
    assignee: kwei
    email: marketplace-external-api@contextlogic.com
  description: 'Wish Marketplace V3 API


    # General Information


    The Wish Marketplace API will be using oAuth to authenticate in order to offer better security for its users


    * Learn about oAuth here.'
  version: 3.0.65
  title: Wish Marketplace V3 Ratings API
servers:
- url: https://merchant.wish.com
  description: V3 API endpoint
security:
- OAuth2: []
tags:
- name: Ratings
paths:
  /api/v3/ratings/products:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ProductRating'
                type: array
          description: successful operation
        '400':
          content:
            application/json:
              examples:
                ExtAPIInvalidParam:
                  value:
                    message: Incorrect sort_by parameter is provided, please review the documentation for correct use!
                    code: '1003'
                ExtAPIUnauthorizedAccess:
                  value:
                    message: Unauthorized Request
                    code: '1006'
              schema:
                $ref: '#/components/schemas/APIError'
          description: failed request
      parameters:
      - required: false
        in: query
        description: Id of a product associated with the ratings. If the id is provided, it will only return the ratings of the specific product. If the id is not given, it will return ratings of all products starting from September 9th, 2019 unless a later created_at_min time is specified
        name: product_id
        schema:
          type: string
          format: object-id
      - required: false
        in: query
        description: The starting point of the ratings retrieved
        name: offset
        schema:
          default: 0
          type: integer
      - required: false
        in: query
        description: It is a limit on the number of ratings that can be returned. Limit can range from <b>1</b> to <b>500</b> items.
        name: limit
        schema:
          default: 100
          minimum: 1
          type: integer
          maximum: 500
      - required: false
        in: query
        description: A date/time string which indicates the earliest creation time of product ratings to fetch. If created_at_min is not provided, the default is to set it to the creation time of the earliest created rating.
        name: created_at_min
        schema:
          type: string
          format: date-time
      - required: false
        in: query
        description: A date/time string which indicates the latest creation time of product ratings to fetch. If created_at_max is not provided, created_at_max will be set to the current time.
        name: created_at_max
        schema:
          type: string
          format: date-time
      - description: Filter ratings by value. ratings range from <b>1</b> to <b>5</b>. If ratings is not provided, the default is to select ratings in all values.
        required: false
        name: ratings
        examples:
          MultipleRatings:
            value:
            - 1
            - 2
            - 4
        in: query
        schema:
          items:
            minimum: 0
            type: integer
            maximum: 5
            format: int32
          type: array
      - required: false
        in: query
        description: Sort results by the given attribute. Enabled attributes are `created_at` and `rating` Default order is `desc`, use `asc` to sort in reverse.
        name: sort_by
        schema:
          default: created_at.desc
          pattern: ^(created_at|rating)(\.(asc|desc))?$
          type: string
      tags:
      - Ratings
      summary: Fetch product ratings
      security:
      - OAuth2:
        - ratings:read
      operationId: FetchProductRatings
      x-code-samples:
      - lang: java_unirest
        source: "HttpResponse<String> response = Unirest.get(\"https://merchant.wish.com/api/v3/ratings/products?product_id=SOME_STRING_VALUE&offset=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE&created_at_min=SOME_STRING_VALUE&created_at_max=SOME_STRING_VALUE&ratings=SOME_ARRAY_VALUE&sort_by=SOME_STRING_VALUE\")\n  .header(\"authorization\", \"Bearer REPLACE_BEARER_TOKEN\")\n  .asString();"
      - lang: php_curl
        source: "<?php\n\n$curl = curl_init();\n\ncurl_setopt_array($curl, array(\n  CURLOPT_URL => \"https://merchant.wish.com/api/v3/ratings/products?product_id=SOME_STRING_VALUE&offset=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE&created_at_min=SOME_STRING_VALUE&created_at_max=SOME_STRING_VALUE&ratings=SOME_ARRAY_VALUE&sort_by=SOME_STRING_VALUE\",\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_ENCODING => \"\",\n  CURLOPT_MAXREDIRS => 10,\n  CURLOPT_TIMEOUT => 30,\n  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n  CURLOPT_CUSTOMREQUEST => \"GET\",\n  CURLOPT_HTTPHEADER => array(\n    \"authorization: Bearer REPLACE_BEARER_TOKEN\"\n  ),\n));\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n  echo \"cURL Error #:\" . $err;\n} else {\n  echo $response;\n}"
      - lang: javascript_jquery
        source: "var settings = {\n  \"async\": true,\n  \"crossDomain\": true,\n  \"url\": \"https://merchant.wish.com/api/v3/ratings/products?product_id=SOME_STRING_VALUE&offset=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE&created_at_min=SOME_STRING_VALUE&created_at_max=SOME_STRING_VALUE&ratings=SOME_ARRAY_VALUE&sort_by=SOME_STRING_VALUE\",\n  \"method\": \"GET\",\n  \"headers\": {\n    \"authorization\": \"Bearer REPLACE_BEARER_TOKEN\"\n  }\n}\n\n$.ajax(settings).done(function (response) {\n  console.log(response);\n});"
      - lang: shell_curl
        source: "curl --request GET \\\n  --url 'https://merchant.wish.com/api/v3/ratings/products?product_id=SOME_STRING_VALUE&offset=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE&created_at_min=SOME_STRING_VALUE&created_at_max=SOME_STRING_VALUE&ratings=SOME_ARRAY_VALUE&sort_by=SOME_STRING_VALUE' \\\n  --header 'authorization: Bearer REPLACE_BEARER_TOKEN'"
      - lang: python_requests
        source: 'import requests


          url = "https://merchant.wish.com/api/v3/ratings/products"


          querystring = {"product_id":"SOME_STRING_VALUE","offset":"SOME_INTEGER_VALUE","limit":"SOME_INTEGER_VALUE","created_at_min":"SOME_STRING_VALUE","created_at_max":"SOME_STRING_VALUE","ratings":"SOME_ARRAY_VALUE","sort_by":"SOME_STRING_VALUE"}


          headers = {''authorization'': ''Bearer REPLACE_BEARER_TOKEN''}


          response = requests.request("GET", url, headers=headers, params=querystring)


          print(response.text)'
      description: The goal of the rating API is to allow merchants to locate and track their product ratings more easily. If the total rating of a specific product changed, merchants should easily be able to determine which orders caused the changes.
  /api/v3/ratings/products/{id}:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductOverallRating'
          description: successful operation
        '400':
          content:
            application/json:
              examples:
                ExtAPIUnauthorizedAccess:
                  value:
                    message: Unauthorized Request
                    code: '1006'
              schema:
                $ref: '#/components/schemas/APIError'
          description: failed request
      parameters:
      - required: true
        in: path
        description: ID of the product to query
        name: id
        schema:
          type: string
          format: object-id
      tags:
      - Ratings
      summary: Fetch the overall rating of the product
      security:
      - OAuth2:
        - ratings:read
      operationId: FetchOverallProductRatings
      x-code-samples:
      - lang: java_unirest
        source: "HttpResponse<String> response = Unirest.get(\"https://merchant.wish.com/api/v3/ratings/products/{id}\")\n  .header(\"authorization\", \"Bearer REPLACE_BEARER_TOKEN\")\n  .asString();"
      - lang: php_curl
        source: "<?php\n\n$curl = curl_init();\n\ncurl_setopt_array($curl, array(\n  CURLOPT_URL => \"https://merchant.wish.com/api/v3/ratings/products/{id}\",\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_ENCODING => \"\",\n  CURLOPT_MAXREDIRS => 10,\n  CURLOPT_TIMEOUT => 30,\n  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,\n  CURLOPT_CUSTOMREQUEST => \"GET\",\n  CURLOPT_HTTPHEADER => array(\n    \"authorization: Bearer REPLACE_BEARER_TOKEN\"\n  ),\n));\n\n$response = curl_exec($curl);\n$err = curl_error($curl);\n\ncurl_close($curl);\n\nif ($err) {\n  echo \"cURL Error #:\" . $err;\n} else {\n  echo $response;\n}"
      - lang: javascript_jquery
        source: "var settings = {\n  \"async\": true,\n  \"crossDomain\": true,\n  \"url\": \"https://merchant.wish.com/api/v3/ratings/products/{id}\",\n  \"method\": \"GET\",\n  \"headers\": {\n    \"authorization\": \"Bearer REPLACE_BEARER_TOKEN\"\n  }\n}\n\n$.ajax(settings).done(function (response) {\n  console.log(response);\n});"
      - lang: shell_curl
        source: "curl --request GET \\\n  --url 'https://merchant.wish.com/api/v3/ratings/products/{id}' \\\n  --header 'authorization: Bearer REPLACE_BEARER_TOKEN'"
      - lang: python_requests
        source: 'import requests


          url = "https://merchant.wish.com/api/v3/ratings/products/{id}"


          headers = {''authorization'': ''Bearer REPLACE_BEARER_TOKEN''}


          response = requests.request("GET", url, headers=headers)


          print(response.text)'
      description: Enable merchants to retrieve the overall rating metrics for the product
components:
  schemas:
    RatingImage:
      type: object
      properties:
        url:
          type: string
          description: The URL of the image of the rating
        id:
          type: string
          description: The ID of the image
    RatingVideo:
      type: object
      properties:
        url:
          type: string
          description: The URL of the video of the rating
        thumbnail_url:
          type: string
          description: The thumbnail image URL for the video
        id:
          type: string
          description: The ID of the video
    ProductRating:
      type: object
      properties:
        comment:
          type: string
          description: Customer comment along with the rating
        rating:
          minimum: 0
          type: integer
          description: Value of the rating
          maximum: 5
          format: int32
        product_id:
          type: string
          description: Id of the product
          format: object-id
        videos:
          items:
            $ref: '#/components/schemas/RatingVideo'
          type: array
          description: The associated videos of the rating
        order_id:
          type: string
          description: Id of order following which the rating was created
          format: object-id
        created_at:
          type: string
          description: Creation time of the rating
          format: date-time
        variation_id:
          type: string
          description: Id of the variation
          format: object-id
        user_locale:
          type: string
          allOf:
          - $ref: '#/components/schemas/Locale'
        images:
          items:
            $ref: '#/components/schemas/RatingImage'
          type: array
          description: The associated images of the rating
        id:
          type: string
          description: ID of the rating
          format: object-id
    ProductOverallRating:
      type: object
      properties:
        average_rating:
          minimum: 0
          type: number
          description: This value represents the average rating of the product
          format: float
        ratings_count:
          type: integer
          description: The cumulative quantity of consumer ratings associated with the queried product
    APIError:
      required:
      - code
      - message
      type: object
      properties:
        message:
          type: string
        code:
          type: integer
          format: int32
    Locale:
      type: string
      description: A language tag (which is sometimes referred to as a 'locale identifier'). This consists of a 2-3 letter base language tag representing the language, optionally followed by additional subtags separated by '-'. The most common extra information is the country or region variant (like 'en-US' or 'fr-CA'). For more information, see specification [BCP 47](https://datatracker.ietf.org/doc/html/bcp47#section-2).
      format: BCP 47
  securitySchemes:
    OpenID:
      type: openIdConnect
      openIdConnectUrl: https://merchant.wish.com/oidc/.well-known/openid-configuration
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          scopes:
            payments:write: Update payments
            tickets:write: Write customer tickets
            epc:read: read EPC info
            returns:write: Write returns
            returns:read: Read returns
            fbw:read: Read FBW
            products:read: Read products
            payments:read: Read payments
            fbw:write: Write FBW
            merchant:write: Write merchant
            products:write: Write products
            ratings:read: Read ratings
            videos:read: Read videos
            compliance:write: Write Compliance
            product_boost:read: Read ProductBoost
            listing_quality:read: Read listing quality
            webhook:write: Write webhook
            orders:read: Read orders
            compliance:read: Read Compliance
            fbs:read: Read FBS
            penalties:read: Read penalties
            penalties:write: Update penalties
            infractions:read: Read infractions
            orders:write: Update orders
            merchant:read: Read merchant
            notifications:write: Write notifications
            announcements:read: Read announcements
            product_boost:write: Write ProductBoost
            notifications:read: Read notifications
            webhook:read: Read webhook
            qoo10:read: Read Qoo10
            wps_parcel:write: Write WishParcel
            wps_parcel:read: Read WishParcel
            tickets:read: Read customer tickets
            infractions:write: Write infractions
            videos:write: Write videos
            epc:write: write EPC info
          tokenUrl: https://merchant.wish.com/api/v3/oauth/access_token
          refreshUrl: https://merchant.wish.com/api/v3/oauth/refresh_token
          authorizationUrl: https://merchant.wish.com/v3/oauth/authorize
externalDocs:
  url: https://merchant.wish.com/documentation/api/v3/explorer
  description: API explorer
x-wish-hidden: false