{ "swagger": "2.0", "info": { "title": "Reseller Ratings API", "description": "Welcome to the the ResellerRatings API for Brand Reviews. Our API is built out and spread over several key areas of the business. These API\u2019s are constructed to tell a story about brand reviews, your review data collection effort, product reviews, and the collection of reviews around ResellerRatings as a business unit", "termsOfService": "https://business.resellerratings.com/about/terms/terms", "contact": { "email": "support@resellerratings.com" }, "license": { "name": "Private License", "url": "https://business.resellerratings.com/about/terms/api-terms" }, "version": "1.0.0" }, "host": "api.resellerratings.com", "basePath": "/v1", "schemes": [ "https", "http" ], "paths": { "/oauth/access_token": { "post": { "tags": [ "Auth" ], "summary": "Generate the access token from the provided set of client credentials", "description": "", "operationId": "oauth-access-token", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "body", "in": "body", "description": "JSON object containing the authentication details", "required": true, "schema": { "$ref": "#/definitions/OauthClientCredentialsObject" } } ], "responses": { "200": { "description": "Access detail response", "schema": { "$ref": "#/definitions/OauthBearerTokenObject" } }, "400": { "description": "Content missing or invalid" }, "401": { "description": "Invalid token" } } } }, "/seller/{id}/reviews/": { "get": { "tags": [ "Seller" ], "summary": "Get Review Information By Seller", "description": "Retrieve JSON formatted review content based for the current authorized account and additional supplied filter parameters. Content is paginated and can be traversed through additional requests.", "operationId": "sellerGetReviews", "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "description": "Seller SEO to retrieve reviews for", "required": true, "type": "string" }, { "name": "page", "in": "query", "description": "Page of paginated set of reviews to retrieve, DEFAULT 1", "required": false, "type": "integer" }, { "name": "perPage", "in": "query", "description": "Number of reviews per page to return, DEFAULT 5, MAX 100", "required": false, "type": "integer" }, { "name": "withStars", "in": "query", "description": "Filter reviews based on number of stars received - DEFAULT 1, 2, 3, 4, 5", "required": false, "type": "array", "items": { "type": "integer", "maximum": 5, "minimum": 1 }, "maximum": 5, "minimum": 1 }, { "name": "fromDate", "in": "query", "description": "Filter reviews after the specified UNIX TIMESTAMP - DEFAULT none", "required": false, "type": "integer" }, { "name": "toDate", "in": "query", "description": "Filter reviews before the specified UNIX TIMESTAMP - DEFAULT none", "required": false, "type": "integer" }, { "name": "fromModified", "in": "query", "description": "Filter reviews MODIFIED after the specified UNIX TIMESTAMP (inclusive) - DEFAULT none", "required": false, "type": "integer" }, { "name": "toModified", "in": "query", "description": "Filter reviews MODIFIED before the specified UNIX TIMESTAMP (inclusive) - DEFAULT none", "required": false, "type": "integer" }, { "name": "status", "in": "query", "description": "Set of statuses to filter the review list by, invalid options will be ignored OPTIONS acitve, pending - DEFAULT active, - Options `active`, `pending`", "required": false, "type": "array", "items": { "type": "string", "enum": [ "active", "pending" ] } }, { "name": "withTags", "in": "query", "description": "Set of tags to filter reviews for - DEFAULT ", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "sortBy", "in": "query", "description": "Sort reviews by date (newest to oldest, oldest to newest) and rating (highest rated to lowest rated, lowest rated to highest rated) - DEFAULT `newest` - Options `newest`, `oldest`, `highest`, `lowest`", "required": false, "type": "string", "enum": [ "newest", "oldest", "highest", "lowest" ] }, { "name": "includes", "in": "query", "description": "Set of flags to indicate additional data points to include. Available: `user.email`, `inactive`", "required": false, "type": "array", "items": { "type": "string", "enum": [ "user.email", "inactive" ] } } ], "responses": { "200": { "description": "successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/Review" } } }, "404": { "description": "Resources not found" } }, "security": [ { "oauth2": [ "read:reviews" ] } ] } }, "/public/seller/{id}/reviews.json": { "get": { "tags": [ "Seller" ], "summary": "Get Public Review Information By Seller", "description": "Retrieve publicly available JSON formatted review content based for the specified seller key. Content is paginated and pre-filtered for public consumption.", "operationId": "sellerGetPublicReviews", "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "description": "Seller SEO to retrieve reviews for", "required": true, "type": "string" }, { "name": "page", "in": "query", "description": "Page of paginated set of reviews to retrieve, DEFAULT 1", "required": false, "type": "integer" }, { "name": "perPage", "in": "query", "description": "Number of reviews per page to return, DEFAULT 5, MAX 100", "required": false, "type": "integer" }, { "name": "sortBy", "in": "query", "description": "Sort reviews by date (newest to oldest, oldest to newest) and rating (highest rated to lowest rated, lowest rated to highest rated) - DEFAULT `newest` - Options `newest`, `oldest`, `highest`, `lowest`", "required": false, "type": "string", "enum": [ "newest", "oldest", "highest", "lowest" ] }, { "name": "includes", "in": "query", "description": "Set of flags to indicate additional data points to include. Available: `inactive`", "required": false, "type": "array", "items": { "type": "string", "enum": [ "inactive" ] } } ], "responses": { "200": { "description": "successful operation", "schema": { "$ref": "#/definitions/PublicSeller" } }, "404": { "description": "Reviews not found" } } } }, "/seller/{seller}/review/{review}": { "get": { "tags": [ "Seller" ], "summary": "Get Review information for specified review", "description": "Retrieve detailed information about the specified review", "operationId": "sellerGetReview", "produces": [ "application/json" ], "parameters": [ { "name": "seller", "in": "path", "description": "Seller SEO or ID to scope review lookup to", "required": true, "type": "string" }, { "name": "review", "in": "path", "description": "Review ID to load", "required": true, "type": "integer" } ], "responses": { "200": { "description": "successful operation", "schema": { "$ref": "#/definitions/Review" } }, "404": { "description": "Review not accessible" } }, "security": [ { "oauth2": [ "read:reviews" ] } ] } }, "/seller/{seller}/review/{review}/author": { "get": { "tags": [ "Seller" ], "summary": "Get detailed review author information for specified review", "description": "Retrieve detailed information about the author for the specified review specified review", "operationId": "sellerGetReviewAuthor", "produces": [ "application/json" ], "parameters": [ { "name": "seller", "in": "path", "description": "Seller SEO or ID to scope review lookup to", "required": true, "type": "string" }, { "name": "review", "in": "path", "description": "Review ID to load", "required": true, "type": "integer" } ], "responses": { "200": { "description": "successful operation", "schema": { "$ref": "#/definitions/User" } }, "404": { "description": "Review not found" } }, "security": [ { "oauth2": [ "read:reviews" ] } ] } }, "/seller/": { "get": { "tags": [ "Seller" ], "summary": "Get Current Seller Information", "description": "Retrieves basic seller rating information for the seller record associated with the used credentials", "operationId": "getSeller", "produces": [ "application/json" ], "responses": { "200": { "description": "successful operation", "schema": { "$ref": "#/definitions/Seller" } }, "404": { "description": "Seller not found" } }, "security": [ { "oauth2": [ "read:seller" ] } ] } }, "/seller/{id}": { "get": { "tags": [ "Seller" ], "summary": "Get Seller Information By Id", "description": "Retrieves basic seller rating information for the specified seller", "operationId": "getSellerById", "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "description": "Seller SEO/ID to retrieve", "required": true, "type": "string" } ], "responses": { "200": { "description": "successful operation", "schema": { "$ref": "#/definitions/Seller" } }, "404": { "description": "Seller not found" } }, "security": [ { "oauth2": [ "read:seller" ] } ] } }, "/seller/{id}/tags": { "get": { "tags": [ "Seller" ], "summary": "Get Seller Tags by Seller Id", "description": "Retrieves set of seller tags associated with the seller specified", "operationId": "getSellerTags", "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "description": "Seller SEO/ID to retrieve tags for", "required": true, "type": "string" } ], "responses": { "200": { "description": "successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/SellerTag" } } }, "404": { "description": "Seller not found" } }, "security": [ { "oauth2": [ "read:seller" ] } ] } }, "/seller/{id}/ratings": { "get": { "tags": [ "Seller" ], "summary": "Get Seller Ratings by Seller Id", "description": "Retrieves set of seller ratings associated with the seller specified", "operationId": "getSellerRatings", "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "description": "Seller SEO/ID to retrieve ratings for", "required": true, "type": "string" } ], "responses": { "200": { "description": "successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/SellerRating" } } }, "404": { "description": "Seller not found" } }, "security": [ { "oauth2": [ "read:seller" ] } ] } }, "/consumer-care/find-case": { "post": { "tags": [ "Consumer Care" ], "summary": "Find a consumer care case", "description": "Finds a consumer care case based on the provided review ID and returns the JSON object with additional details", "operationId": "findCase", "consumes": [ "application/x-www-form-urlencoded", "multipart/form-data" ], "produces": [ "application/json" ], "parameters": [ { "name": "reviewId", "in": "formData", "description": "Unique review ID to find the case for", "required": true, "type": "integer" }, { "name": "createIfNotFound", "in": "formData", "description": "If no case found, create one - DEFAULT true", "required": false, "type": "boolean" }, { "name": "priority", "in": "formData", "description": "Priority to assign to cases created when not found - DEFAULT 5", "required": false, "type": "integer", "items": { "type": "integer", "maximum": 10, "minimum": 1 }, "maximum": 10, "minimum": 1 }, { "name": "agentId", "in": "formData", "description": "Unique user agent ID to assign the case to when being created. When specified this agent will be the default for future notes and public replies, when not provided other actions will require the inclusion of an agentId until the case is assigned.", "required": false, "type": "integer" } ], "responses": { "200": { "description": "successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/ConsumerCareCase" } } }, "404": { "description": "Review or case not found" }, "400": { "description": "Agent ID not found or invalid" } }, "security": [ { "oauth2": [ "write:consumer-care" ] } ] } }, "/consumer-care/get-case/{id}": { "get": { "tags": [ "Consumer Care" ], "summary": "Retrieves the specified consumer case record", "description": "Retrieves a consumer care case based on the provided case ID and returns the JSON object with additional details", "operationId": "getCase", "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "description": "Consumer Care Case UID or Case Number to retrieve", "required": true, "type": "integer" } ], "responses": { "200": { "description": "successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/ConsumerCareCase" } } }, "404": { "description": "Case not found" } }, "security": [ { "oauth2": [ "read:consumer-care" ] } ] } }, "/consumer-care/public-reply": { "post": { "tags": [ "Consumer Care" ], "summary": "Post a public reply", "description": "Post a public reply to a consumer care case viewable on the website as a merchant public response.", "operationId": "publicReply", "consumes": [ "application/x-www-form-urlencoded", "multipart/form-data" ], "produces": [ "application/json" ], "parameters": [ { "name": "caseId", "in": "formData", "description": "Consumer care case ID", "required": true, "type": "integer" }, { "name": "message", "in": "formData", "description": "Public reply message. A blank message will remove the reply", "required": true, "type": "string" }, { "name": "agentId", "in": "formData", "description": "Merchant agent to post the reply on behalf of. When not provided will use the agent assigned to the case, if the case is unassigned this value is REQUIRED.", "required": false, "type": "integer" }, { "name": "update", "in": "formData", "description": "Allows control of whether to update the public reply with the provided information as a review can only have one active public reply. This flag has no effect if the message is blank. Specifying FALSe will not produce an error when a message already exists but instead will return the original reply data. DEFAULT - true", "required": false, "type": "integer" } ], "responses": { "200": { "description": "successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/ConsumerCareCaseReply" } } }, "404": { "description": "Case not found" }, "400": { "description": "Invalid case or review, agent not found or invalid" } }, "security": [ { "oauth2": [ "write:consumer-care" ] } ] } }, "/consumer-care/agent-direct-message": { "post": { "tags": [ "Consumer Care" ], "summary": "Send a direct message to the reviewer", "description": "Providers a method to contact the author of a review directly as a company agent. Each consumer care case can have multiple messages from multiple agents. Specifying different agents does not affect the case.", "operationId": "agentDirectMessage", "consumes": [ "application/x-www-form-urlencoded", "multipart/form-data" ], "produces": [ "application/json" ], "parameters": [ { "name": "caseId", "in": "formData", "description": "Consumer care case ID", "required": true, "type": "integer" }, { "name": "message", "in": "formData", "description": "Direct message content. Can be formatted with HTML", "required": true, "type": "string" }, { "name": "agentId", "in": "formData", "description": "Merchant agent to post the reply on behalf of, does not need to be the same as the case, will not affect the case assignment.", "required": false, "type": "integer" } ], "responses": { "200": { "description": "successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/ConsumerCareCaseMessage" } } }, "404": { "description": "Case not found" }, "400": { "description": "Invalid case or review, agent not found or invalid, user not contactable" } }, "security": [ { "oauth2": [ "write:consumer-care" ] } ] } }, "/consumer-care/ask-to-revise": { "post": { "tags": [ "Consumer Care" ], "summary": "Ask the reviewer to revise their review.", "description": "Providers a method to contact the author a review through email and ask them to revise their experience. The email content is preset and can be adjusted in the merchant dashboard.", "operationId": "AskToRevise", "consumes": [ "application/x-www-form-urlencoded", "multipart/form-data" ], "produces": [ "application/json" ], "parameters": [ { "name": "caseId", "in": "formData", "description": "Consumer care case ID", "required": true, "type": "integer" }, { "name": "agentId", "in": "formData", "description": "Merchant agent to send the revision request as, does not need to be the same as the case, will not affect the case assignment.", "required": false, "type": "integer" } ], "responses": { "200": { "description": "successful operation", "schema": { "properties": { "id": { "description": "Message ID", "type": "integer", "format": "int64" }, "caseId": { "description": "Care Case ID", "type": "integer", "format": "int64" }, "actionId": { "description": "Care Case Action ID for the revision request", "type": "integer", "format": "int64" }, "agent": { "description": "Care Case Agent the revision request was sent as.", "$ref": "#/definitions/User" }, "author": { "description": "Review author details.", "$ref": "#/definitions/User" } }, "type": "object" } }, "404": { "description": "Case not found" }, "400": { "description": "Invalid case or review, agent not found or invalid, user not contactable" }, "429": { "description": "Rate limit on a case ask-to-revise hit. One request per 24 hours per review since the last revision." } }, "security": [ { "oauth2": [ "write:consumer-care" ] } ] } }, "/consumer-care/update-case": { "post": { "tags": [ "Consumer Care" ], "summary": "Updates a consumer care case", "description": "Provides a method to update a consumer care case. Can update Agent, add a note (with an agent), priority, and status.", "operationId": "updateCase", "consumes": [ "application/x-www-form-urlencoded", "multipart/form-data" ], "produces": [ "application/json" ], "parameters": [ { "name": "caseId", "in": "formData", "description": "Consumer Care Case ID", "required": true, "type": "integer" }, { "name": "agentId", "in": "formData", "description": "Agent ID to assign case to, a value of 0 will mark the case as unassigned", "required": false, "type": "integer" }, { "name": "note", "in": "formData", "description": "Note content to add to case", "required": false, "type": "string" }, { "name": "noteAgentId", "in": "formData", "description": "Agent ID to post a note as. When not provided the currently assigned agent id will be used. Ignored when `note` not specified.", "required": false, "type": "integer" }, { "name": "priority", "in": "formData", "description": "New case priority value, valid values are 1-10", "required": false, "type": "integer", "items": { "type": "integer", "maximum": 10, "minimum": 1 }, "maximum": 10, "minimum": 1 }, { "name": "status", "in": "formData", "description": "New status code to use for case. One of 'open', 'pending', or 'resolved'", "required": false, "type": "string", "enum": [ "open", "pending", "resolved" ] } ], "responses": { "200": { "description": "successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/ConsumerCareCase" } } }, "404": { "description": "Case not found" }, "400": { "description": "Invalid case or review, agent not found or invalid" } }, "security": [ { "oauth2": [ "write:consumer-care" ] } ] } }, "/consumer-care/agent-list": { "get": { "tags": [ "Consumer Care" ], "summary": "Retrieves the set of available users who are seller agents", "description": "To assist with the use of the consumer care API calls that require user agents, this end point provides a list of all currently available agents.", "operationId": "agentList", "produces": [ "application/json" ], "responses": { "200": { "description": "successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/Agent" } } }, "401": { "description": "Current account doesn't have access to agent list" } }, "security": [ { "oauth2": [ "read:consumer-care" ] } ] } }, "/consumer-care/list-changes": { "get": { "tags": [ "Consumer Care" ], "summary": "Retrieves the complete set of changes for all cases for the given time period", "description": "To assist with keeping external services in sync with internal changes this end point provides a complete list of the changes that have occurred for a specified time period. Dates should be specified in any valid date string format. If {{toDate}} is not provided the current time will be used, should {{fromDate}} not be provided it will use 24 hours prior to the {{toDate}} value.", "operationId": "listChanges", "produces": [ "application/json" ], "responses": { "200": { "description": "successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/ConsumerCareCaseChange" } } }, "401": { "description": "Current account doesn't have access seller's change list" } }, "security": [ { "oauth2": [ "read:consumer-care" ] } ] } }, "/product/answers/submit": { "post": { "tags": [ "Product" ], "summary": "answer a question", "description": "Post an answer for a particular question", "operationId": "submitAnswer", "consumes": [ "application/x-www-form-urlencoded", "multipart/form-data" ], "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "formData", "description": "id of question being answered", "required": true, "type": "string" }, { "name": "user_email", "in": "formData", "description": "email of person answering question, for profile creation and will not be displayed publicly", "required": true, "type": "string" }, { "name": "user_name", "in": "formData", "description": "nickname for person answering question", "required": true, "type": "string" }, { "name": "answer", "in": "formData", "description": "the answer being given", "required": true, "type": "string" } ], "responses": { "200": { "description": "successful operation", "schema": { "type": "object", "items": { "$ref": "#/definitions/Answer" } } } }, "security": [ { "oauth2": [ "read:reviews" ] } ] } }, "/product/answers/{id}/vote_helpful": { "post": { "tags": [ "Product" ], "summary": "vote that a answer is helpful", "operationId": "voteAnswerHelpful", "consumes": [ "application/x-www-form-urlencoded", "multipart/form-data" ], "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "description": "id of answer to vote is helpful", "required": true, "type": "string" } ], "responses": { "200": { "description": "successful operation", "schema": { "type": "integer" } } }, "security": [ { "oauth2": [ "read:reviews" ] } ] } }, "/product/answers/{id}/vote_not_helpful": { "post": { "tags": [ "Product" ], "summary": "vote that a answer is not helpful", "operationId": "voteAnswerNotHelpful", "consumes": [ "application/x-www-form-urlencoded", "multipart/form-data" ], "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "description": "id of answer to vote is not helpful", "required": true, "type": "string" } ], "responses": { "200": { "description": "successful operation", "schema": { "type": "integer" } } }, "security": [ { "oauth2": [ "read:reviews" ] } ] } }, "/product/manage/import": { "post": { "tags": [ "Product" ], "summary": "Import a product catalogue file", "description": "Post a product catalogue to update your product records at resellerratings", "operationId": "importProducts", "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "parameters": [ { "name": "products", "in": "formData", "description": "product catalogue csv to be submited", "required": true, "type": "file" } ], "responses": { "404": { "description": "File not found" }, "400": { "description": "File is missing required fields" } }, "security": [ { "oauth2": [ "read:reviews" ] } ] } }, "/product/manage/import_questions": { "post": { "tags": [ "Product" ], "summary": "Import a questions file", "description": "Post a csv file containing questions to be imported to social q&a", "operationId": "importQuestions", "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "parameters": [ { "name": "questions", "in": "formData", "description": "question csv to be submited", "required": true, "type": "file" } ], "responses": { "404": { "description": "File not found" }, "400": { "description": "File is missing required fields" } }, "security": [ { "oauth2": [ "read:reviews" ] } ] } }, "/product/manage/import_answers": { "post": { "tags": [ "Product" ], "summary": "Import a answers file", "description": "Post a csv file containing answers to be imported to social q&a", "operationId": "importAnswers", "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "parameters": [ { "name": "answers", "in": "formData", "description": "answers csv to be submited", "required": true, "type": "file" } ], "responses": { "404": { "description": "File not found" }, "400": { "description": "File is missing required fields" } }, "security": [ { "oauth2": [ "read:reviews" ] } ] } }, "/product/manage/update": { "post": { "tags": [ "Product" ], "summary": "Updates (or creates) upto 50 products based on a posted JSON document", "description": "Post a JSON document containing upto 50 products to update (or create)", "operationId": "product-manage-update", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "body", "in": "body", "description": "Product JSON object, should be array of product objects", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/ProductUpdate" } } } ], "responses": { "404": { "description": "Content missing" }, "400": { "description": "Product objects missing required fields" } }, "security": [ { "oauth2": [ "read:reviews" ] } ] } }, "/product/manage/catalog.json": { "get": { "tags": [ "Product" ], "summary": "Retrieves a page of the product catalog", "description": "Retrieves a page of basic product data for the current merchant. Producst are ordered by the `sku` value.", "operationId": "productManageCatalog", "produces": [ "application/json" ], "parameters": [ { "name": "page", "in": "query", "description": "Page of the catalog to retrieve", "required": false, "type": "integer", "default": 1, "minimum": 1 } ], "responses": { "404": { "description": "Merchant not available" }, "200": { "description": "Product catalog entries", "schema": { "type": "array", "items": { "$ref": "#/definitions/ProductSummary" } } } }, "security": [ { "oauth2": [ "read:reviews" ] } ] } }, "/product/questions/submit": { "post": { "tags": [ "Product" ], "summary": "ask a question", "description": "Post a question for a particular product", "operationId": "submitQuestion", "consumes": [ "application/x-www-form-urlencoded", "multipart/form-data" ], "produces": [ "application/json" ], "parameters": [ { "name": "sku", "in": "formData", "description": "sku of product question pertains to", "required": true, "type": "string" }, { "name": "user_email", "in": "formData", "description": "email of person asking question, for profile creation and will not be displayed publicly", "required": true, "type": "string" }, { "name": "user_name", "in": "formData", "description": "nickname for person asking question", "required": true, "type": "string" }, { "name": "question", "in": "formData", "description": "the question being asked", "required": true, "type": "string" } ], "responses": { "200": { "description": "successful operation", "schema": { "type": "object", "items": { "$ref": "#/definitions/Question" } } } }, "security": [ { "oauth2": [ "read:reviews" ] } ] } }, "/product/questions/{id}/vote_helpful": { "post": { "tags": [ "Product" ], "summary": "vote that a question is helpful", "operationId": "voteQuestionHelpful", "consumes": [ "application/x-www-form-urlencoded", "multipart/form-data" ], "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "description": "id of question to vote is helpful", "required": true, "type": "string" } ], "responses": { "200": { "description": "successful operation", "schema": { "type": "integer" } } }, "security": [ { "oauth2": [ "read:reviews" ] } ] } }, "/product/questions/{id}/vote_not_helpful": { "post": { "tags": [ "Product" ], "summary": "vote that a question is not helpful", "operationId": "voteQuestionNotHelpful", "consumes": [ "application/x-www-form-urlencoded", "multipart/form-data" ], "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "description": "id of question to vote is not helpful", "required": true, "type": "string" } ], "responses": { "200": { "description": "successful operation", "schema": { "type": "integer" } } }, "security": [ { "oauth2": [ "read:reviews" ] } ] } }, "/product/questions/answers.json": { "get": { "tags": [ "Product" ], "summary": "Get Product Questions and Answers by sku", "description": "Retrieve JSON formatted questions with answers either specified product SKU may optionally search for questions by content ", "operationId": "productQuestionsAndAnswers", "produces": [ "application/json" ], "parameters": [ { "name": "sku", "in": "query", "description": "Product SKU to look up", "required": true, "type": "string" } ], "responses": { "200": { "description": "successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/Question" } } } }, "security": [ { "oauth2": [ "read:reviews" ] } ] } }, "/product/questions/import": { "post": { "tags": [ "Product", "Questions and Answers" ], "summary": "Imports questions and optional answers for a product from a supplied JSON document", "description": "Provide a JSON document to process defining questions and their optional answers.", "operationId": "product-questions-import", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "body", "in": "body", "description": "Raw JSON object defining the question and answer data to process", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/QuestionImportObject" } } } ], "responses": { "200": { "description": "Questions & answers imported content and statistics", "schema": { "$ref": "#/definitions/QuestionImportResponseObject" } }, "400": { "description": "Content missing or invalid" } }, "security": [ { "oauth2": [ "read:reviews" ] } ] } }, "/product/reviews/reviews.{format}": { "get": { "tags": [ "Product" ], "summary": "Get Product Review content By SKU or date range", "description": "Retrieve paginated JSON or HTML formatted reviews either for specified product SKU, or for product reviews collected over a specified date range. ", "operationId": "productReviews", "produces": [ "application/json", "text/html" ], "parameters": [ { "name": "format", "in": "path", "description": "Format specifier, 'json' or 'html'. HTML is only supported when using the SKU query parameter", "required": true, "type": "string", "enum": [ "json", "html" ] }, { "name": "sku", "in": "query", "description": "Product SKU to look up", "required": false, "type": "string" }, { "name": "parent_id", "in": "query", "description": "Product parent id to look up", "required": false, "type": "string" }, { "name": "startDate", "in": "query", "description": "Limiting start date to search for reviews, INCLUSIVE of midnight UTC. When not specified and endDate is included this will default to the same day as `endDate`. Must be formatted YYYY-MM-DD.", "required": false, "type": "string", "format": "date" }, { "name": "endDate", "in": "query", "description": "Limiting end date to search for reviews, INCLUSIVE of 23:59:59 UTC. When not specified and `startDate` is included this will default to today. Must be formatted YYYY-MM-DD.", "required": false, "type": "string", "format": "date" }, { "name": "perPage", "in": "query", "description": "Number of reviews to retrieve", "required": false, "type": "integer", "default": 15, "maximum": 100, "minimum": 1 }, { "name": "page", "in": "query", "description": "Page of reviews to retrieve", "required": false, "type": "integer", "default": 1, "minimum": 1 }, { "name": "rating", "in": "query", "description": "optional, Filter reviews based on rating. Leave empty to retrieve all reviews", "required": false, "type": "integer", "default": "all", "maximum": 5, "minimum": 1 }, { "name": "sortBy", "in": "query", "description": "How reviews will be sorted, currently supports: 'date' (sort according to the review submission date), 'rating' (sort according to the star rating), 'helpful' (sort according to the total number of times a review was voted 'helpful'), and 'ratingDate' sort by rating followed by date with the most recent first within each rating group).", "required": false, "type": "string", "default": "date", "enum": [ "date", "rating", "helpful", "ratingDate" ] }, { "name": "sortDirection", "in": "query", "description": "Sort direction of reviews, supports 'asc' for ascending sort and 'desc' for descending sort, if left blank will default to descending sort", "required": false, "type": "string", "default": "desc", "enum": [ "asc", "desc" ] }, { "name": "filterBy", "in": "query", "description": "Filters results to return reviews matching the specified condition. 'verified' returns only verified reviews, 'has_images' returns only reviews with associated images", "required": false, "type": "string", "default": "none", "enum": [ "verified", "has_images" ] }, { "name": "sellerId", "in": "query", "description": "For Enterprise Clients: get review content for one of your child sellers. If left blank will retrieve reviews for the seller associated with your credentials", "required": false, "type": "integer", "default": "none" } ], "responses": { "200": { "description": "successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/ProductReview" } } }, "404": { "description": "Product / Seller not found" } }, "security": [ { "oauth2": [ "read:reviews" ] } ] } }, "/public/seller/{id}/product/reviews.{format}": { "get": { "tags": [ "Product" ], "summary": "Get Public Product Review content By SKU or date range", "description": "Retrieve paginated JSON or HTML formatted reviews either for specified product SKU, or for product reviews collected over a specified date range. ", "operationId": "productPublicReviews", "produces": [ "application/json", "text/html" ], "parameters": [ { "name": "id", "in": "path", "description": "Seller SEO to retrieve product reviews for", "required": true, "type": "string" }, { "name": "format", "in": "path", "description": "Format specifier, 'json' or 'html'. HTML is only supported when using the SKU query parameter", "required": true, "type": "string", "enum": [ "json", "html" ] }, { "name": "sku", "in": "query", "description": "Product SKU to look up", "required": false, "type": "array", "items": { "type": "string" }, "minimum": 1 }, { "name": "parent_id", "in": "query", "description": "Product parent id to look up", "required": false, "type": "string" }, { "name": "startDate", "in": "query", "description": "Limiting start date to search for reviews, INCLUSIVE of midnight UTC. When not specified and endDate is included this will default to the same day as `endDate`. Must be formatted YYYY-MM-DD.", "required": false, "type": "string", "format": "date" }, { "name": "endDate", "in": "query", "description": "Limiting end date to search for reviews, INCLUSIVE of 23:59:59 UTC. When not specified and `startDate` is included this will default to today. Must be formatted YYYY-MM-DD.", "required": false, "type": "string", "format": "date" }, { "name": "perPage", "in": "query", "description": "Number of reviews to retrieve", "required": false, "type": "integer", "default": 15, "maximum": 100, "minimum": 1 }, { "name": "page", "in": "query", "description": "Page of reviews to retrieve", "required": false, "type": "integer", "default": 1, "minimum": 1 }, { "name": "sortBy", "in": "query", "description": "How reviews will be sorted, currently supports: 'date' (sort according to the review submission date), 'rating' (sort according to the star rating), 'helpful' (sort according to the total number of times a review was voted 'helpful'), and 'ratingDate' sort by rating followed by date with the most recent first within each rating group).", "required": false, "type": "string", "default": "date", "enum": [ "date", "rating", "helpful", "ratingDate" ] }, { "name": "sortDirection", "in": "query", "description": "Sort direction of reviews, supports 'asc' for ascending sort and 'desc' for descending sort, if left blank will default to descending sort", "required": false, "type": "string", "default": "desc", "enum": [ "asc", "desc" ] }, { "name": "filterBy", "in": "query", "description": "Filters results to return reviews matching the specified condition. 'verified' returns only verified reviews, 'has_images' returns only reviews with associated images", "required": false, "type": "string", "default": "none", "enum": [ "verified", "has_images" ] } ], "responses": { "200": { "description": "successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/ProductReview" } } }, "404": { "description": "Product / Seller not found" } } } }, "/product/reviews/summary.{format}": { "get": { "tags": [ "Product" ], "summary": "Get Product Review Summary By SKU", "description": "Retrieve JSON or HTML formatted summary of the Specified Product, including review data aggregates of the overall score, experience indicators, and custom questions. ", "operationId": "productReviewsSummary", "produces": [ "application/json", "text/html" ], "parameters": [ { "name": "format", "in": "path", "description": "Format specifier, 'json' or 'html'", "required": true, "type": "string", "enum": [ "json", "html" ] }, { "name": "sku", "in": "query", "description": "Product SKU to look up", "required": true, "type": "string" }, { "name": "parent_id", "in": "query", "description": "Product parent id to look up, use either this or sku", "required": false, "type": "string" }, { "name": "sellerId", "in": "query", "description": "For Enterprise Clients: get review content for one of your child sellers. If left blank will retrieve reviews for the seller associated with your credentials", "required": false, "type": "integer", "default": "none" } ], "responses": { "200": { "description": "successful operation", "schema": { "$ref": "#/definitions/ProductSummary" } }, "404": { "description": "Product / Seller not found" } }, "security": [ { "oauth2": [ "read:reviews" ] } ] } }, "/product/reviews/full.{format}": { "get": { "tags": [ "Product" ], "summary": "Get Product data summary along with paginated review content by SKU", "description": "Retrieve JSON or HTML formatted summary of the Product, along with a sample of review images and paginated reviews", "operationId": "productReviewsCombined", "produces": [ "application/json", "text/html" ], "parameters": [ { "name": "format", "in": "path", "description": "Format specifier, 'json' or 'html'", "required": true, "type": "string", "enum": [ "json", "html" ] }, { "name": "sku", "in": "query", "description": "Product SKU to look up", "required": true, "type": "string" }, { "name": "parent_id", "in": "query", "description": "Product parent id to look up, use either this or sku", "required": false, "type": "string" }, { "name": "sellerId", "in": "query", "description": "For Enterprise Clients: get review content for one of your child sellers. If left blank will retrieve reviews for the seller associated with your credentials", "required": false, "type": "integer", "default": "none" }, { "name": "perPage", "in": "query", "description": "Number of reviews to retrieve", "required": false, "type": "integer", "default": 15, "maximum": 100, "minimum": 1 }, { "name": "page", "in": "query", "description": "Page of reviews to retrieve", "required": false, "type": "integer", "default": 1, "minimum": 1 }, { "name": "sortBy", "in": "query", "description": "How reviews will be sorted, currently supports: 'date' (sort according to the review submission date), 'rating' (sort according to the star rating), 'helpful' (sort according to the total number of times a review was voted 'helpful'), and 'ratingDate' sort by rating followed by date with the most recent first within each rating group).", "required": false, "type": "string", "default": "date", "enum": [ "date", "rating", "helpful", "ratingDate" ] }, { "name": "sortDirection", "in": "query", "description": "Sort direction of reviews, supports 'asc' for ascending sort and 'desc' for descending sort, if left blank will default to descending sort", "required": false, "type": "string", "default": "desc", "enum": [ "asc", "desc" ] }, { "name": "filterBy", "in": "query", "description": "Filters results to return reviews matching the specified condition. 'verified' returns only verified reviews, 'has_images' returns only reviews with associated images", "required": false, "type": "string", "default": "none", "enum": [ "verified", "has_images" ] } ], "responses": { "200": { "description": "successful operation", "schema": { "$ref": "#/definitions/ProductDetailed" } }, "404": { "description": "Product / Seller not found" } }, "security": [ { "oauth2": [ "read:reviews" ] } ] } }, "/product/reviews/catalogue.json": { "get": { "tags": [ "Product" ], "summary": "Get Product aggregates for your entire product cataglogue", "description": "Retrieve JSON formatted list of products by sku with their aggregate ratings and review count", "operationId": "productReviewCatalogue", "produces": [ "application/json" ], "parameters": [ { "name": "byParent", "in": "query", "description": "Find review aggregates by parent grouping rather than by individual product", "required": false, "type": "string", "default": "false", "enum": [ "true", "false" ] }, { "name": "sellerId", "in": "query", "description": "For Enterprise Clients: get review content for one of your child sellers. If left blank will retrieve reviews for the seller associated with your credentials", "required": false, "type": "integer", "default": "none" } ], "responses": { "200": { "description": "successful operation", "schema": { "type": "object", "items": { "$ref": "#/definitions/Merchant" } } }, "404": { "description": "Product / Seller not found" } }, "security": [ { "oauth2": [ "read:reviews" ] } ] } }, "/product/reviews/distribution.json": { "get": { "tags": [ "Product" ], "summary": "Get Product Rating distribution for your entire product cataglogue", "description": "Retrieve JSON ratings distribution", "operationId": "productReviewDistribution", "produces": [ "application/json" ], "parameters": [ { "name": "sellerId", "in": "query", "description": "For Enterprise Clients: get review content for one of your child sellers. If left blank will retrieve reviews for the seller associated with your credentials", "required": false, "type": "integer", "default": "none" } ], "responses": { "200": { "description": "successful operation", "schema": { "type": "object", "items": { "$ref": "#/definitions/Merchant" } } }, "404": { "description": "Product / Seller not found" } }, "security": [ { "oauth2": [ "read:reviews" ] } ] } }, "/product/reviews/images.json": { "get": { "tags": [ "Product" ], "summary": "Get Product Review Images by SKU", "description": "Retrieve JSON formatted list of review images with summary data of their associated reviews, sorted by images corresponding to the most helpful reviews first", "operationId": "productReviewImages", "produces": [ "application/json" ], "parameters": [ { "name": "sku", "in": "query", "description": "Product SKU to look up", "required": true, "type": "string" }, { "name": "parent_id", "in": "query", "description": "Parent id to look up, use either this or sku", "required": true, "type": "string" }, { "name": "perPage", "in": "query", "description": "Number of review images to retrieve", "required": false, "type": "integer", "default": 15, "maximum": 100, "minimum": 1 }, { "name": "page", "in": "query", "description": "Page of review images to retrieve", "required": false, "type": "integer", "default": 1, "minimum": 1 } ], "responses": { "200": { "description": "successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/ReviewImage" } } }, "404": { "description": "Product / Seller not found" } }, "security": [ { "oauth2": [ "read:reviews" ] } ] } }, "/product/seller/{id}/reviews/ai_summary": { "get": { "tags": [ "Product" ], "summary": "Get the AI Summary Data for a specific product if it exists", "description": "Retrieve Product Reviews AI Summary", "operationId": "productReviewAISummary", "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "description": "Seller ID to retrieve product reviews for", "required": true, "type": "string" }, { "name": "sku", "in": "query", "description": "Product SKU to look up", "required": false, "type": "string" }, { "name": "parent_id", "in": "query", "description": "Parent ID to look up", "required": false, "type": "string" } ], "responses": { "200": { "description": "successful operation", "schema": { "properties": { "summary_data": { "properties": { "summary": { "type": "string" }, "summary_sentiment": { "type": "integer", "format": "int64" }, "tags": { "type": "array", "items": { "properties": { "tag": { "type": "string" }, "reason": { "type": "string" }, "sentiment": { "type": "string" }, "isRelevant": { "type": "string" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } }, "404": { "description": "Product / Seller not found" }, "403": { "description": "Forbidden: AI Summaries are not enabled for this seller" } }, "security": [ { "oauth2": [ "read:reviews" ] } ] } }, "/product/reviews/vote_helpful": { "post": { "tags": [ "Product" ], "summary": "Vote if a review is or isn't helpful to a customer", "description": "", "operationId": "voteHelpful", "consumes": [ "application/x-www-form-urlencoded", "multipart/form-data" ], "produces": [ "application/json" ], "parameters": [ { "name": "review_id", "in": "query", "description": "id of review being voted on", "required": true, "type": "integer" }, { "name": "vote", "in": "query", "description": "whether the voter considers the review helpful or not helpful in the form of 'yes' or 'no'", "required": false, "type": "string", "default": "yes", "enum": [ "yes", "no" ] } ], "responses": { "200": { "description": "successful operation", "schema": { "properties": { "review_id": { "type": "integer", "format": "int64" }, "vote_type": { "type": "string" }, "votes": { "type": "integer", "format": "int64" } }, "type": "object" } }, "404": { "description": "Review not found" } }, "security": [ { "oauth2": [ "read:reviews" ] } ] } }, "/product/reviews/{review}/author": { "get": { "tags": [ "Seller" ], "summary": "Get detailed review author information for specified review", "description": "Retrieve detailed information about the author for the specified review specified review", "operationId": "productGetReviewAuthor", "produces": [ "application/json" ], "parameters": [ { "name": "review", "in": "path", "description": "Review ID to load", "required": true, "type": "integer" } ], "responses": { "200": { "description": "successful operation", "schema": { "$ref": "#/definitions/User" } }, "404": { "description": "Review not found" } } } } }, "definitions": { "Agent": { "properties": { "id": { "description": "Class AgentTransformer", "type": "integer", "format": "int64" }, "sellerId": { "description": "Class AgentTransformer", "type": "integer", "format": "int64" }, "access_type": { "description": "Class AgentTransformer", "type": "string" }, "username": { "description": "Class AgentTransformer", "type": "string" }, "email": { "description": "Email of user when available", "type": "string" } }, "type": "object" }, "User": { "properties": { "id": { "description": "Class ReviewTransformer", "type": "integer", "format": "int64" }, "username": { "description": "Class ReviewTransformer", "type": "string" }, "email": { "description": "Email of user when available", "type": "string" }, "location": { "description": "User location information", "type": "string" } }, "type": "object" }, "PublicSeller": { "properties": { "pagedReviews": { "description": "Class PublicFeedTransformer", "type": "array", "items": { "$ref": "#/definitions/Review" } } }, "type": "object", "allOf": [ { "$ref": "#/definitions/Seller" } ] }, "SellerRating": { "properties": { "year": { "type": "integer", "format": "int64" }, "monthly": { "type": "array", "items": { "properties": { "month": { "type": "integer", "format": "int64" }, "rating": { "type": "number", "format": "double" }, "stars": { "type": "number", "format": "double" } }, "type": "object" } }, "yearly": { "type": "array", "items": { "properties": { "quarter": { "type": "integer", "format": "int64" }, "rating": { "type": "number", "format": "double" }, "stars": { "type": "number", "format": "double" } }, "type": "object" } } }, "type": "object" }, "Review": { "properties": { "id": { "description": "Class ReviewTransformer", "type": "integer", "format": "int64" }, "date": { "description": "Class ReviewTransformer", "type": "string", "format": "int64" }, "date_modified": { "description": "Class ReviewTransformer", "type": "string", "format": "int64" }, "user": { "description": "Class ReviewTransformer", "$ref": "#/definitions/User" }, "username": { "description": "Class ReviewTransformer", "type": "string" }, "status": { "description": "Class ReviewTransformer", "type": "string" }, "status_label": { "description": "Class ReviewTransformer", "type": "string" }, "type": { "description": "Class ReviewTransformer", "type": "string" }, "solicited": { "description": "Class ReviewTransformer", "type": "boolean" }, "collection": { "description": "Class ReviewTransformer", "type": "string" }, "title": { "description": "Class ReviewTransformer", "type": "string" }, "review": { "description": "Class ReviewTransformer", "type": "string" }, "rating": { "description": "Class ReviewTransformer", "type": "number", "format": "double" }, "invoice_number": { "description": "Class ReviewTransformer", "type": "string" }, "likes": { "description": "Class ReviewTransformer", "type": "integer", "format": "int64" }, "tags": { "description": "Class ReviewTransformer", "type": "array", "items": { "$ref": "#/definitions/ReviewTag" } }, "seller_seo": { "description": "Class ReviewTransformer", "type": "string" }, "public_reply": { "description": "Class ReviewTransformer", "type": "string" }, "cart_total": { "description": "Class ReviewTransformer", "type": "number", "format": "double" } }, "type": "object" }, "ReviewTag": { "properties": { "id": { "description": "Class ReviewTransformer", "type": "integer", "format": "int64" }, "name": { "description": "Class ReviewTransformer", "type": "string" } }, "type": "object" }, "Seller": { "properties": { "id": { "type": "integer", "format": "int64" }, "type": { "type": "string" }, "name": { "type": "string" }, "websiteUrl": { "type": "string" }, "seoName": { "type": "string" }, "premium": { "type": "boolean" }, "storeRating": { "type": "number", "format": "double" }, "starRating": { "type": "number", "format": "double" }, "rating": { "$ref": "#/definitions/SellerReviewDistribution" }, "categories": { "type": "array", "items": { "properties": { "name": { "type": "string" } }, "type": "object" } }, "links": { "type": "array", "items": { "properties": { "rel": { "type": "string" }, "uri": { "type": "string" } }, "type": "object" } } }, "type": "object" }, "SellerReviewDistribution": { "properties": { "total": { "type": "integer", "format": "int64", "minimum": 0 }, "one_star": { "type": "integer", "format": "int64", "minimum": 0 }, "two_star": { "type": "integer", "format": "int64", "minimum": 0 }, "three_star": { "type": "integer", "format": "int64", "minimum": 0 }, "four_star": { "type": "integer", "format": "int64", "minimum": 0 }, "five_star": { "type": "integer", "format": "int64", "minimum": 0 } }, "type": "object" }, "SellerTag": { "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "count": { "type": "integer", "format": "int64", "minimum": 0 } }, "type": "object" }, "Merchant": { "maxProperties": 1, "properties": { "catalogue": { "description": "Class MerchantTransformer", "type": "object", "items": { "$ref": "#/definitions/Catalogue" } }, "distribution": { "description": "Class MerchantTransformer", "type": "object", "items": { "$ref": "#/definitions/Distribution" } } }, "type": "object" }, "Catalogue": { "properties": { "sku": { "description": "Class MerchantTransformer", "type": "string" }, "review_count": { "description": "Class MerchantTransformer", "type": "integer", "format": "int64" }, "score": { "description": "Class MerchantTransformer", "type": "number", "format": "int64" } }, "type": "object" }, "Distribution": { "properties": { "total_reviews": { "description": "Class MerchantTransformer", "type": "integer", "format": "int64" }, "1_stars": { "description": "Class MerchantTransformer", "type": "integer", "format": "int64" }, "2_stars": { "description": "Class MerchantTransformer", "type": "integer", "format": "int64" }, "3_stars": { "description": "Class MerchantTransformer", "type": "integer", "format": "int64" }, "4_stars": { "description": "Class MerchantTransformer", "type": "integer", "format": "int64" }, "5_stars": { "description": "Class MerchantTransformer", "type": "integer", "format": "int64" } }, "type": "object" }, "ParentSummary": { "description": "Parent product summary detail", "properties": { "parent_id": { "description": "Parent product SKU", "type": "string" }, "name": { "description": "Parent product name", "type": "string" }, "recommend_count": { "description": "Total number of reviews where user reccomended products belonging to this parent sku.", "type": "integer", "format": "int64" }, "rating": { "description": "Parent product rating detail summary", "properties": { "count": { "description": "Total number of ratings that were used to calculate the score", "type": "integer", "format": "int64" }, "min": { "description": "Minimum score *possible* for the rating value (lower bound)", "type": "integer", "format": "int64", "enum": [ "0" ] }, "max": { "description": "Maximum score *possible* for the rating value (upper bound)", "type": "integer", "format": "int64", "enum": [ "5" ] }, "score": { "description": "Current score between [min,mx]", "type": "number", "format": "double" } }, "type": "object" }, "experience_indicator_totals": { "description": "Class ProductParentTransformer", "type": "array", "items": { "description": "Indicators for various properties about the customer experience", "$ref": "#/definitions/ExperienceIndicatorTotal" } }, "question_totals": { "description": "Question details for the questions available to the parent product", "type": "array", "items": { "$ref": "#/definitions/QuestionTotal" } }, "review_images": { "description": "Class ProductParentTransformer", "type": "array", "items": { "description": "URLs for the set of review image associated with the product review", "type": "string" } }, "review_thumbnails": { "description": "Class ProductParentTransformer", "type": "array", "items": { "description": "URLs for the the thumbnail images for the product review", "type": "string" } }, "write_review_url": { "description": "Url of dedicated write a review page", "type": "string" } }, "type": "object" }, "ProductSummary": { "description": "Product summary details", "properties": { "sku": { "description": "Product SKU", "type": "string" }, "parent_id": { "description": "Parent Product SKU", "type": "string" }, "name": { "description": "Product name", "type": "string" }, "image": { "description": "Primary image URL", "type": "string" }, "url": { "description": "Product page view URL", "type": "string" }, "description": { "description": "Product description", "type": "string" }, "recommend_count": { "description": "Total number of reviews where user recommended the product", "type": "integer", "format": "int64" }, "not_recommend_count": { "description": "Total number of reviews where user does NOT recommended the product", "type": "integer", "format": "int64" }, "answered_questions_count": { "description": "Total number of questions answered about this product", "type": "integer", "format": "int64" }, "questions": { "description": "Product questions for questions & answers", "type": "array", "items": { "description": "Product summary question object defining the question details that can be asked for the product.", "properties": { "id": { "description": "Question unique ID", "type": "integer", "format": "int64" }, "question": { "description": "Question text", "type": "string" }, "short_title": { "description": "Question short title", "type": "string" }, "type": { "description": "Question type", "type": "string", "enum": [ "", "text_single", "text_area", "radio_button", "checkbox", "select_box" ] }, "required": { "description": "Is question required?", "type": "boolean" }, "options": { "description": "Answer options", "type": "array", "items": { "description": "Production question answer option", "properties": { "id": { "description": "Unique question answer option ID", "type": "integer", "format": "int64" }, "value": { "description": "Question option value for selection", "type": "string" } }, "type": "object" } } }, "type": "object" } }, "rating": { "description": "Product rating values", "properties": { "count": { "description": "Total number of ratings that were used to calculate the score", "type": "integer", "format": "int64" }, "min": { "description": "Minimum score *possible* for the rating value (lower bound)", "type": "integer", "format": "int64", "enum": [ "0" ] }, "max": { "description": "Maximum score *possible* for the rating value (upper bound)", "type": "integer", "format": "int64", "enum": [ "5" ] }, "score": { "description": "Current score between [min,mx]", "type": "number", "format": "double" } }, "type": "object" }, "stats": { "description": "Product rating statistics and additional values", "properties": { "review_count": { "description": "Total number of ratings that were used to calculate the score", "type": "integer", "format": "int64" }, "rating_average": { "description": "Current score between [rating.min] and [rating.max]", "type": "number", "format": "double" }, "recommend_count": { "description": "Total number of reviews where user recommended the product", "type": "integer", "format": "int64" }, "one_star": { "description": "Total number of ONE star ratings", "type": "integer", "format": "int64" }, "two_star": { "description": "Total number of TWO star ratings", "type": "integer", "format": "int64" }, "three_star": { "description": "Total number of THREE star ratings", "type": "integer", "format": "int64" }, "four_star": { "description": "Total number of FOUR star ratings", "type": "integer", "format": "int64" }, "five_star": { "description": "Total number of FIVE star ratings", "type": "integer", "format": "int64" } }, "type": "object" }, "experience_indicator_totals": { "description": "Class ProductTransformer", "type": "array", "items": { "description": "Indicators for various properties about the customer experience", "$ref": "#/definitions/ExperienceIndicatorTotal" } }, "question_totals": { "description": "Detailed question stats from questions & answers", "type": "array", "items": { "$ref": "#/definitions/QuestionTotal" } }, "review_images": { "description": "Class ProductTransformer", "type": "array", "items": { "description": "URLs for the set of review image associated with the product review", "type": "string" } }, "review_thumbnails": { "description": "Class ProductTransformer", "type": "array", "items": { "description": "URLs for the the thumbnail images for the product review", "type": "string" } }, "write_review_url": { "description": "Url of dedicated write a review page", "type": "string" }, "merchant": { "description": "Unique merchant number", "type": "integer" }, "seller_seo": { "description": "Unique seller identifier within ResellerRatings", "type": "string" }, "highlight_verified_answers": { "description": "", "type": "integer" }, "loyalty_campaign_title": { "description": "", "type": "string" }, "coupon_description": { "description": "", "type": "string" } }, "type": "object" }, "ProductDetailed": { "description": "Detailed product summary information including review content", "properties": { "pagedReviews": { "description": "Set of product reviews", "type": "array", "items": { "$ref": "#/definitions/ProductReview" } } }, "type": "object", "allOf": [ { "$ref": "#/definitions/ProductSummary" } ] }, "ExperienceIndicatorTotal": { "description": "Key value pairing of indicators and their score for product review user experience ratings. Fields are normalized but are unique to each client and may change over time.", "properties": { "field": { "description": "Class ProductTransformer", "type": "string" }, "score": { "description": "Class ProductTransformer", "type": "number", "format": "double" } }, "type": "object" }, "QuestionTotal": { "description": "Question detail for a product question & answer", "properties": { "question_id": { "description": "Unique question ID", "type": "integer", "format": "int64" }, "question": { "description": "Question text", "type": "string" }, "answer": { "description": "Question answer value", "format": "string" }, "count": { "description": "Number of responess for the question and answer combo", "type": "integer", "format": "int64" } }, "type": "object" }, "Question": { "description": "Product Review Question Object", "properties": { "id": { "description": "Class QuestionTransformer", "type": "integer", "format": "int64" }, "username": { "description": "name of the user asking the question", "type": "string" }, "text": { "description": "text body of the question", "type": "string" }, "votes_helpful": { "description": "number of helpful votes - not helpful votes", "type": "integer", "format": "int64" }, "is_promoted": { "description": "questions can be promoted from the dashboard, promoted questions will appear first in results", "type": "boolean" }, "date": { "description": "Unix timestamp representing date of question", "type": "integer", "format": "int64" }, "answers": { "description": "all published answers to this question", "type": "array", "items": { "$ref": "#/definitions/Answer" } } }, "type": "object" }, "Answer": { "description": "Product Review Answer Object", "properties": { "id": { "description": "Class QuestionTransformer", "type": "integer", "format": "int64" }, "username": { "description": "name of the user answering the question", "type": "string" }, "date": { "description": "Unix timestamp representing date of answer", "type": "integer", "format": "int64" }, "text": { "description": "text body of the answer", "type": "string" }, "votes_helpful": { "description": "number of helpful votes - not helpful votes", "type": "integer", "format": "int64" }, "is_promoted": { "description": "answers can be promoted from the dashboard, promoted answers will appear first in results", "type": "boolean" } }, "type": "object" }, "ReviewImage": { "properties": { "id": { "description": "Class ReviewImageTransformer", "type": "integer", "format": "int64" }, "url": { "description": "Class ReviewImageTransformer", "type": "string" }, "is_portrait": { "description": "Class ReviewImageTransformer", "type": "boolean" }, "review": { "description": "Class ReviewImageTransformer", "type": "object", "items": { "$ref": "#/definitions/ImageReview" } } }, "type": "object" }, "ImageReview": { "properties": { "id": { "description": "Class ReviewImageTransformer", "type": "integer", "format": "int64" }, "username": { "description": "Class ReviewImageTransformer", "type": "string" }, "date": { "description": "Class ReviewImageTransformer", "type": "string", "format": "date-time" }, "title": { "description": "Class ReviewImageTransformer", "type": "string" }, "text": { "description": "Class ReviewImageTransformer", "type": "string" }, "rating": { "description": "Class ReviewImageTransformer", "type": "string", "enum": [ "one", "two", "three", "four", "five" ] } }, "type": "object" }, "ProductReview": { "properties": { "id": { "description": "Class ReviewTransformer", "type": "integer", "format": "int64" }, "status": { "description": "Description of the review status, typically `published`", "type": "string" }, "author": { "description": "Class ReviewTransformer", "$ref": "#/definitions/User" }, "date": { "description": "Unix timestamp representing date of review", "type": "integer", "format": "int64" }, "title": { "description": "Class ReviewTransformer", "type": "string" }, "text": { "description": "Class ReviewTransformer", "type": "string" }, "votes_helpful": { "description": "Class ReviewTransformer", "type": "integer", "format": "int64" }, "votes_not_helpful": { "description": "Class ReviewTransformer", "type": "integer", "format": "int64" }, "rating": { "description": "Class ReviewTransformer", "properties": { "score": { "description": "Review rating between [min,max]", "type": "number", "format": "double" }, "min": { "description": "Class ReviewTransformer", "type": "integer", "format": "int64", "enum": [ 0 ] }, "max": { "description": "Class ReviewTransformer", "type": "integer", "format": "int64", "enum": [ 5 ] } }, "type": "object" }, "user_recommend": { "description": "Does this user recommend this product?", "type": "string", "enum": [ "yes", "no" ] }, "reply": { "description": "Class ReviewTransformer", "properties": { "text": { "description": "Class ReviewTransformer", "type": "string" }, "date": { "description": "Unix timestamp representing date of reply", "type": "integer", "format": "int64" }, "vote_yes": { "description": "Number of times the reply has been voted as positive / helpful", "type": "integer", "format": "int64" }, "vote_no": { "description": "Number of times the reply has been voted as negative / unhelpful", "type": "integer", "format": "int64" } }, "type": "object" }, "experience_indicators": { "description": "Class ReviewTransformer", "properties": { "field": { "description": "Class ReviewTransformer", "type": "string" }, "score": { "description": "Class ReviewTransformer", "type": "integer", "format": "int64" } }, "type": "object" }, "question_responses": { "description": "Class ReviewTransformer", "properties": { "question_id": { "description": "Class ReviewTransformer", "type": "integer", "format": "int64" }, "question": { "description": "Class ReviewTransformer", "type": "string" }, "short_question": { "description": "Class ReviewTransformer", "type": "string" }, "answer": { "description": "Class ReviewTransformer", "type": "string" } }, "type": "object" }, "merchant": { "description": "Unique merchant identifier", "type": "integer" }, "seller_seo": { "description": "Unique seller identifier within ResellerRatings", "type": "string" }, "images": { "description": "Class ReviewTransformer", "type": "array", "items": { "type": "string" } }, "thumbnails": { "description": "Class ReviewTransformer", "type": "array", "items": { "type": "string" } }, "sku": { "description": "Sku of product being reviewed", "type": "string" }, "product": { "description": "Class ReviewTransformer", "$ref": "#/definitions/ProductSummary" }, "cart_total": { "description": "Class ReviewTransformer", "type": "number", "format": "double" } }, "type": "object" }, "ReviewVideo": { "properties": { "id": { "description": "Class ReviewVideoTransformer", "type": "integer", "format": "int64" }, "url": { "description": "Class ReviewVideoTransformer", "type": "string" }, "thumbnail": { "description": "Class ReviewVideoTransformer", "type": "string" }, "is_portrait": { "description": "Class ReviewVideoTransformer", "type": "boolean" }, "review": { "description": "Class ReviewVideoTransformer", "type": "object", "items": { "$ref": "#/definitions/VideoReview" } } }, "type": "object" }, "VideoReview": { "properties": { "id": { "description": "Class ReviewVideoTransformer", "type": "integer", "format": "int64" }, "username": { "description": "Class ReviewVideoTransformer", "type": "string" }, "date": { "description": "Class ReviewVideoTransformer", "type": "string", "format": "date-time" }, "title": { "description": "Class ReviewVideoTransformer", "type": "string" }, "text": { "description": "Class ReviewVideoTransformer", "type": "string" }, "rating": { "description": "Class ReviewVideoTransformer", "type": "string", "enum": [ "one", "two", "three", "four", "five" ] } }, "type": "object" }, "ConsumerCareCaseChange": { "properties": { "caseId": { "description": "Unique case identifier", "type": "integer", "format": "int64" }, "case_id": { "description": "DEPRECATED. Duplicate of `caseId`", "type": "integer", "format": "int64" }, "number": { "description": "Class CaseChangeTransformer", "type": "integer", "format": "int64" }, "agent": { "description": "Class CaseChangeTransformer", "$ref": "#/definitions/User" }, "action": { "description": "Class CaseChangeTransformer", "type": "string" }, "date": { "description": "Class CaseChangeTransformer", "type": "string", "format": "date-time" }, "action_date": { "description": "Class CaseChangeTransformer", "type": "object" } }, "type": "object" }, "ConsumerCareCaseDirectMessage": { "properties": { "id": { "description": "Class CaseReplyTransformer\nA specific transformer for seller comment public replies", "type": "integer", "format": "int64" }, "caseId": { "description": "Class CaseReplyTransformer\nA specific transformer for seller comment public replies", "type": "integer", "format": "int64" }, "reviewId": { "description": "Class CaseReplyTransformer\nA specific transformer for seller comment public replies", "type": "integer", "format": "int64" }, "sender": { "description": "Class CaseReplyTransformer\nA specific transformer for seller comment public replies", "$ref": "#/definitions/User" }, "recipient": { "description": "Class CaseReplyTransformer\nA specific transformer for seller comment public replies", "$ref": "#/definitions/User" }, "date": { "description": "Class CaseReplyTransformer\nA specific transformer for seller comment public replies", "type": "string", "format": "date-time" }, "message": { "description": "Class CaseReplyTransformer\nA specific transformer for seller comment public replies", "type": "string" } }, "type": "object" }, "ConsumerCareCaseMessage": { "properties": { "id": { "description": "Message ID", "type": "integer", "format": "int64" }, "caseId": { "description": "Care Case ID", "type": "integer", "format": "int64" }, "reviewId": { "description": "Review ID", "type": "integer", "format": "int64" }, "sender": { "description": "Sender user record. May be an agent or customer detail", "$ref": "#/definitions/User" }, "recipient": { "description": "Deprecated, always `null`", "$ref": "#/definitions/User" }, "action": { "description": "Message action, indicates an agent message, customer message, or other message type", "type": "string", "enum": [ "reply", "customer-reply", "other" ] }, "date": { "description": "Date of message entry", "type": "string", "format": "date-time" }, "message": { "description": "Message content", "type": "string" } }, "type": "object" }, "ConsumerCareCaseReply": { "properties": { "id": { "description": "Class CaseReplyTransformer\nA specific transformer for seller comment public replies", "type": "integer", "format": "int64" }, "caseId": { "description": "Class CaseReplyTransformer\nA specific transformer for seller comment public replies", "type": "integer", "format": "int64" }, "reviewId": { "description": "Class CaseReplyTransformer\nA specific transformer for seller comment public replies", "type": "integer", "format": "int64" }, "agent": { "description": "Class CaseReplyTransformer\nA specific transformer for seller comment public replies", "$ref": "#/definitions/User" }, "date": { "description": "Class CaseReplyTransformer\nA specific transformer for seller comment public replies", "type": "string", "format": "date-time" }, "message": { "description": "Class CaseReplyTransformer\nA specific transformer for seller comment public replies", "type": "string" } }, "type": "object" }, "ConsumerCareCase": { "properties": { "id": { "description": "", "type": "integer", "format": "int64" }, "sellerId": { "description": "", "type": "integer", "format": "int64" }, "seller_seo": { "description": "", "type": "string", "format": "int64" }, "number": { "description": "", "type": "integer", "format": "int64" }, "reviewId": { "description": "", "type": "integer", "format": "int64" }, "agent": { "description": "", "$ref": "#/definitions/User" }, "priority": { "description": "", "type": "integer", "format": "int64" }, "status": { "description": "", "type": "string" }, "interactions": { "description": "", "type": "integer", "format": "int64" }, "date": { "description": "", "type": "string", "format": "date-time" }, "noteCount": { "description": "", "type": "integer", "format": "int64" }, "publicReply": { "description": "Any visibile public reply on the review.", "$ref": "#/definitions/ConsumerCareCaseReply" }, "notes": { "description": "Set of internal notes added by merchant agents", "type": "array", "items": { "properties": { "name": { "description": "Class CaseTransformer", "$ref": "#/definitions/ConsumerCareCaseNote" } }, "type": "object" } }, "directMessages": { "description": "List of direct messages delivered to and from the original review author and merchant agents.", "type": "array", "items": { "properties": { "name": { "description": "Class CaseTransformer", "$ref": "#/definitions/ConsumerCareCaseMessage" } }, "type": "object" } } }, "type": "object" }, "ConsumerCareCaseNote": { "properties": { "id": { "description": "", "type": "integer", "format": "int64" }, "agent": { "description": "", "$ref": "#/definitions/User" }, "date": { "description": "", "type": "string", "format": "date-time" }, "note": { "description": "", "type": "string" } }, "type": "object" }, "OauthClientCredentialsObject": { "description": "Object defining client credentials for an OAuth 2 Authentication request", "required": [ "grant_type", "client_id", "client_secret" ], "properties": { "grant_type": { "description": "Grant type being requested. Must be `client_credentials`", "type": "string", "default": "client_credentials", "enum": [ "client_credentials" ] }, "client_id": { "description": "Client ID value provided by ResellerRatings", "type": "string" }, "client_secret": { "description": "Client Secret value provided by ResellerRatings", "type": "string" } }, "type": "object" }, "OauthBearerTokenObject": { "description": "Object defining the OAuth 2 Client Credentials request response including the necessary bearer token", "properties": { "access_token": { "description": "Bearer token value to be used in future authenticated requests", "type": "string" }, "token_type": { "description": "Token type description. Must be `Bearer`", "type": "string", "enum": [ "Bearer" ] }, "expires_in": { "description": "Life of the token in seconds", "type": "integer" } }, "type": "object" }, "ProductUpdate": { "description": "Product Update Object", "properties": { "sku": { "description": "Unique product SKU to create / update", "type": "string" }, "product_name": { "description": "Product name, REQUIRED during `create`", "type": "string" }, "url": { "description": "Product landing page url, REQUIRED during `created`", "type": "string" }, "description": { "description": "Product description", "type": "string" }, "mpn": { "description": "Product MPN", "type": "string" }, "gtin": { "description": "Product GTIN number", "type": "string" }, "brand": { "description": "Product brand name", "type": "string" }, "category": { "description": "Product category name", "type": "string" }, "img_url": { "description": "Product image url, must be publicly accessible", "type": "string" }, "parent_id": { "description": "OPTIONAL parent_id value for product heirarchy, can be created during product update / creation, will be used as name when `product_name` not also supplied", "type": "string" }, "parent_name": { "description": "OPTIONAL parent product name", "type": "string" }, "parent_image": { "description": "OPTIONAL display image for parent product", "type": "string" }, "seller_id": { "description": "OPTIONAL / ENTERRISE ACCOUNTS Seller ID of the child seller to update product for, if not supplied, will default to the current authed seller", "type": "integer" } }, "type": "object" }, "QuestionImportObject": { "description": "Question object defining the necessary data points", "required": [ "sku", "text" ], "properties": { "sku": { "description": "SKU of product question pertains to", "type": "string" }, "text": { "description": "The text question being asked. Must be plain text, advanced formatting is not supported.", "type": "string" }, "status": { "description": "Status of the question during import - OPTIONS `pending`, `published`", "type": "string", "default": "pending", "enum": [ "pending", "published" ] }, "answers": { "description": "Array of the answers for current question", "type": "array", "items": { "$ref": "#/definitions/QuestionAnswerImportObject" } } }, "type": "object" }, "QuestionAnswerImportObject": { "description": "Answer Object", "required": [ "text" ], "properties": { "text": { "description": "The answer being given. Must be plain text, advanced formatting is not supported.", "type": "string" }, "status": { "description": "Status of the answer during import - OPTIONS `pending`, `published`", "type": "string", "default": "pending", "enum": [ "pending", "published" ] } }, "type": "object" }, "QuestionImportResponseObject": { "description": "The response object to the import questions and answers request", "properties": { "errors": { "description": "Set of error messages generated during the import process. May be empty", "type": "array", "items": { "type": "string" } }, "questions": { "description": "Imported question objects", "type": "array", "items": { "$ref": "#/definitions/Question" } }, "stats": { "description": "Statistics for the result of the import", "type": "object" } }, "type": "object" } }, "securityDefinitions": { "oauth2": { "type": "oauth2", "flow": "application", "authorizationUrl": "https://api.resellerratings.com/oauth/access_token", "tokenUrl": "https://api.resellerratings.com/oauth/access_token", "scopes": { "read:reviews": "Read brand reviews", "read:seller": "Read seller reviews" } } }, "externalDocs": { "description": "Find out more about ResellerRatings", "url": "https://business.resellerratings.com/productset" } }