{
  "openapi": "3.0.3",
  "info": {
    "title": "AliExpress Reviews API",
    "version": "1.0.0",
    "description": "AliExpress product reviews as JSON. Filters are applied by AliExpress, one per request."
  },
  "servers": [
    {
      "url": "https://api.aliexpress-reviews.com"
    }
  ],
  "security": [
    {
      "ApiKey": []
    }
  ],
  "paths": {
    "/v1/reviews/{productId}": {
      "get": {
        "operationId": "listReviews",
        "summary": "List reviews of a product",
        "parameters": [
          {
            "name": "productId",
            "in": "path",
            "required": true,
            "description": "Numeric AliExpress product id (the number in aliexpress.com/item/<id>.html).",
            "schema": {
              "type": "string",
              "pattern": "^\\d{6,20}$"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, 1–1000.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 1
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "required": false,
            "description": "Reviews per page: up to 20 on Free, up to 100 on Pro and Max.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "filter",
            "in": "query",
            "required": false,
            "description": "One of the filters below. Some values need a higher plan.",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "5",
                "4",
                "3",
                "2",
                "1",
                "additional",
                "local",
                "image"
              ],
              "default": "all"
            }
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "Shopper country, ISO 3166-1 alpha-2. Decides which reviews filter=local returns and the local count. Requires the Pro plan.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z]{2}$",
              "default": "US"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Language reviews are translated to. originalContent keeps the buyer’s text. Requires the Pro plan.",
            "schema": {
              "type": "string",
              "enum": [
                "en_US",
                "es_ES",
                "fr_FR",
                "de_DE",
                "it_IT",
                "pt_BR",
                "nl_NL",
                "pl_PL"
              ],
              "default": "en_US"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of reviews.",
            "headers": {
              "x-ratelimit-limit": {
                "description": "Daily request quota.",
                "schema": {
                  "type": "integer"
                }
              },
              "x-ratelimit-remaining": {
                "description": "Requests left today.",
                "schema": {
                  "type": "integer"
                }
              },
              "x-ratelimit-reset": {
                "description": "Unix time of the next reset (00:00 UTC).",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReviewPage"
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key, or a parameter or filter outside your plan.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Product not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Daily quota exceeded, or global rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The upstream source failed; retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      }
    },
    "schemas": {
      "Review": {
        "type": "object",
        "required": [
          "id",
          "author",
          "country",
          "rating",
          "content",
          "originalContent",
          "additionalFeedback",
          "date",
          "sku",
          "helpfulVotes"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "AliExpress review id."
          },
          "author": {
            "type": "string",
            "description": "Buyer name, masked by AliExpress (e.g. J***n)."
          },
          "country": {
            "type": "string",
            "description": "Buyer country, ISO 3166-1 alpha-2."
          },
          "rating": {
            "type": "integer",
            "description": "Stars, 1–5."
          },
          "content": {
            "type": "string",
            "description": "Review text translated to lang."
          },
          "originalContent": {
            "type": "string",
            "description": "Review text as the buyer wrote it."
          },
          "additionalFeedback": {
            "type": "string",
            "nullable": true,
            "description": "Follow-up feedback, if any."
          },
          "date": {
            "type": "string",
            "description": "Review date, YYYY-MM-DD."
          },
          "sku": {
            "type": "string",
            "nullable": true,
            "description": "Variant the buyer bought (e.g. Color:Black)."
          },
          "helpfulVotes": {
            "type": "integer",
            "description": "Times other shoppers marked it helpful."
          },
          "images": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Full-size photo URLs. Max plan only."
          },
          "thumbnails": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Thumbnail URLs. Max plan only."
          }
        }
      },
      "Summary": {
        "type": "object",
        "properties": {
          "averageRating": {
            "type": "number",
            "nullable": true
          },
          "totalReviews": {
            "type": "integer"
          },
          "ratingDistribution": {
            "type": "object",
            "properties": {
              "1": {
                "type": "integer"
              },
              "2": {
                "type": "integer"
              },
              "3": {
                "type": "integer"
              },
              "4": {
                "type": "integer"
              },
              "5": {
                "type": "integer"
              }
            }
          },
          "filterCounts": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            }
          }
        }
      },
      "ReviewPage": {
        "type": "object",
        "properties": {
          "productId": {
            "type": "string"
          },
          "filter": {
            "type": "string"
          },
          "page": {
            "type": "integer"
          },
          "pageSize": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "totalPages": {
            "type": "integer"
          },
          "summary": {
            "$ref": "#/components/schemas/Summary"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Review"
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}