{
    "openapi": "3.0.1",
    "info": {
      "title": "Shopper Approved API+",
      "description": "Below you will find the Shopper Approved API documentation. This API is provided for clients who need to pull data into their own backends for processing they would like to do on their own servers (for example building a custom widget). This API is not intended for use in a browser client-side context. The recommended use is to call the API and use that populate a small database.",
      "contact": {
        "email": "support@shopperapproved.com"
      },
      "version": "1.3.50"
    },
    "servers": [
      {
        "url": "https://api.shopperapproved.com/"
      }
    ],
    "tags": [
      {
        "name": "reviews",
        "description": "Endpoints related to merchant reviews."
      },
      {
        "name": "products",
        "description": "Endpoints related to product reviews."
      },
      {
        "name": "aggregates",
        "description": "Endpoints related to fetching site statistics"
      }
    ],
    "paths": {
      "/reviews/{siteid}": {
        "get": {
          "tags": [
            "reviews"
          ],
          "summary": "Fetch a number of reviews",
          "description": "This is a general purpose endpoint to retrieve reviews about the merchant or company. It is by default limited to 100 reviews at a time. Higher amounts may be requested, but could time out if the request becomes too large.",
          "parameters": [
            {
              "name": "siteid",
              "in": "path",
              "description": "The SiteId for which you are requesting reviews.",
              "required": true,
              "schema": {
                "type": "integer"
              }
            },
            {
              "name": "token",
              "in": "query",
              "description": "The site's API token.",
              "required": true,
              "schema": {
                "type": "string"
              }
            },
            {
              "name": "from",
              "in": "query",
              "description": "The first date in your desired range of results. Should be given in YYYY-MM-DD format. Defaults to 30 days prior from the current date.",
              "schema": {
                "type": "string"
              }
            },
            {
              "name": "to",
              "in": "query",
              "description": "The last date in your desired range of results. Should be given in YYYY-MM-DD format. Defaults to the current date.",
              "schema": {
                "type": "string"
              }
            },
            {
              "name": "rating",
              "in": "query",
              "description": "Returns only reviews with the given star rating(s). Provided as a comma separated list without spaces.",
              "schema": {
                "type": "string",
                "default": "1,2,3,4,5"
              }
            },
            {
              "name": "sort",
              "in": "query",
              "description": "How you would like your results sorted upon response. The 'featured' sort type will return _only_ hand-picked reviews.",
              "schema": {
                "type": "string",
                "enum": [
                  "newest",
                  "oldest",
                  "highest",
                  "lowest",
                  "featured"
                ]
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "How many reviews you want the response to include per page. This value must be at least 1.",
              "schema": {
                "minimum": 1,
                "type": "integer",
                "default": 100
              }
            },
            {
              "name": "full_name",
              "in": "query",
              "description": "Include customer full name or abbreviate last name.",
              "schema": {
                "type": "integer",
                "enum": [
                  0,
                  1
                ]
              }
            },
            {
              "name": "page",
              "in": "query",
              "description": "The offset of reviews. Starts at page 0.",
              "schema": {
                "minimum": 0,
                "type": "integer",
                "default": 0
              }
            },
            {
              "name": "removed",
              "in": "query",
              "description": "Include removed reviews? If set to 1 then reviews will include a 'removed' value equal to 1 if the review was removed and 0 if the review is active.",
              "schema": {
                "type": "integer",
                "enum": [
                  0,
                  1
                ]
              }
            },
            {
              "name": "test",
              "in": "query",
              "description": "A value of 1 will include reviews that have been marked as test or possible spam.",
              "schema": {
                "type": "boolean",
                "default": false
              }
            },
            {
              "name": "xml",
              "in": "query",
              "description": "If true, this will return an XML tree instead of a JSON response.",
              "schema": {
                "type": "boolean",
                "default": false
              }
            }
          ],
          "responses": {
            "200": {
              "description": "Success - A JSON dictionary of your reviews will be returned.",
              "content": {}
            },
            "403": {
              "description": "Not Authorized - Your siteID was not found or your token was incorrect.",
              "content": {}
            },
            "500": {
              "description": "Error - Something else went wrong. A bug report is automatically sent if this ever occurs.",
              "content": {}
            }
          }
        },
        "post": {
          "tags": [
            "reviews"
          ],
          "summary": "Create a new review entry.",
          "description": "This API endpoint is used to ingest a Order, Email, and Follow-up Date so that the Shopper Approved system will send a survey request using that data. You cannot submit reviews to this endpoint. Abuse of this endpoint could result in removal of the ability to use the Shopper Approved API. Only send a single review per call.",
          "parameters": [
            {
              "name": "siteid",
              "in": "path",
              "description": "The SiteID for which you are creating an entry.",
              "required": true,
              "schema": {
                "type": "integer"
              }
            },
            {
              "name": "xml",
              "in": "query",
              "description": "If true, this will return an XML tree instead of a JSON response.",
              "schema": {
                "type": "boolean",
                "default": false
              }
            }
          ],
          "requestBody": {
            "content": {
              "application/x-www-form-urlencoded": {
                "schema": {
                  "required": [
                    "email",
                    "followup",
                    "orderid",
                    "token"
                  ],
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string",
                      "description": "Your API token."
                    },
                    "name": {
                      "type": "string",
                      "description": "The customer's name. If not provided, will be saved as \"Anonymous Customer\""
                    },
                    "orderid": {
                      "type": "string",
                      "description": "The unique Order ID. If not unique and not test, a 419 erorr will be returned."
                    },
                    "products": {
                      "type": "string",
                      "description": "A comma separated list of product ids (no spaces after the commas) to be attached to the review."
                    },
                    "email": {
                      "type": "string",
                      "description": "The customer's email. Must be provided so that the follow up email may be sent."
                    },
                    "followup": {
                      "type": "string",
                      "description": "The date in YYYY-MM-DD format that the customer should receive the follow-up email."
                    },
                    "test": {
                      "type": "boolean",
                      "description": "Whether or not this review entry should be considered a test. Allows for duplicate order IDs, review will never be public."
                    },
                    "custom_questions": {
                      "type": "string",
                      "description": "A JSON encoded object of custom question headers and their responses."
                    }
                  }
                }
              }
            },
            "required": true
          },
          "responses": {
            "201": {
              "description": "The review was successfully created.",
              "content": {}
            },
            "403": {
              "description": "Not Authorized - Your siteID was not found or your token was incorrect.",
              "content": {}
            },
            "419": {
              "description": "Conflict - A non-test order already exists with the provided orderID.",
              "content": {}
            },
            "422": {
              "description": "Bad Request - You were either missing a parameter or one of them was malformed.",
              "content": {}
            },
            "500": {
              "description": "Error - Something else went wrong. A bug report is automatically sent if this ever occurs.",
              "content": {}
            }
          }
        }
      },
      "/reviews/{siteid}/{reviewid}": {
        "get": {
          "tags": [
            "reviews"
          ],
          "summary": "Fetch a single review.",
          "description": "This endpoiont allows you to fetch a single review either by review_id (found from the /reviews/{siteid} path) or from an order ID that was passed from your system to ours. If you have not sent us order ID information, looking up by order ID will not work.",
          "parameters": [
            {
              "name": "siteid",
              "in": "path",
              "description": "The Site ID you are requesting the review for.",
              "required": true,
              "schema": {
                "type": "integer"
              }
            },
            {
              "name": "reviewid",
              "in": "path",
              "description": "The review_id or order ID of the review you are requesting.",
              "required": true,
              "schema": {
                "type": "string"
              }
            },
            {
              "name": "token",
              "in": "query",
              "description": "Your API token.",
              "required": true,
              "schema": {
                "type": "string"
              }
            },
            {
              "name": "removed",
              "in": "query",
              "description": "Include removed reviews? If set to 1 then reviews will include a 'removed' value equal to 1 if the review was removed and 0 if the review is active.",
              "schema": {
                "type": "integer",
                "enum": [
                  0,
                  1
                ]
              }
            },
            {
              "name": "full_name",
              "in": "query",
              "description": "Include customer full name or abbreviate last name.",
              "schema": {
                "type": "integer",
                "enum": [
                  0,
                  1
                ]
              }
            },
            {
              "name": "xml",
              "in": "query",
              "description": "If true, this will return an XML tree instead of a JSON response.",
              "schema": {
                "type": "boolean",
                "default": false
              }
            }
          ],
          "responses": {
            "200": {
              "description": "Success - a JSON entry for your review will be returned.",
              "content": {}
            },
            "403": {
              "description": "Not authorized - your token is properly incorrect.",
              "content": {}
            },
            "404": {
              "description": "Not found - we couldn't find the review for your site based on the information given.",
              "content": {}
            },
            "500": {
              "description": "Error - Something else went wrong. A bug report is automatically sent if this ever occurs.",
              "content": {}
            }
          }
        },
        "put": {
          "tags": [
            "reviews"
          ],
          "summary": "Updates or cancels a review.",
          "description": "This endpoint allows to change the follow-up date of a review or mark the order as cancelled which will tell our system to not send an email if it hasn't already been sent.",
          "parameters": [
            {
              "name": "siteid",
              "in": "path",
              "description": "The Site ID you are trying to update a review for.",
              "required": true,
              "schema": {
                "type": "integer"
              }
            },
            {
              "name": "reviewid",
              "in": "path",
              "description": "The review_id or order id you would like to update",
              "required": true,
              "schema": {
                "type": "string"
              }
            },
            {
              "name": "xml",
              "in": "query",
              "description": "If true, this will return an XML tree instead of a JSON response.",
              "schema": {
                "type": "boolean",
                "default": false
              }
            }
          ],
          "requestBody": {
            "content": {
              "application/x-www-form-urlencoded": {
                "schema": {
                  "required": [
                    "token"
                  ],
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string",
                      "description": "Your API token."
                    },
                    "followup": {
                      "type": "string",
                      "description": "A YYYY-MM-DD formatted date string for the date you would like the follow-up email to be sent on. Required if cancel is not passed."
                    },
                    "cancel": {
                      "type": "integer",
                      "description": "This should be 1 if you want to cancel the review. Required if followup is not passed.",
                      "format": "int32"
                    }
                  }
                }
              }
            },
            "required": true
          },
          "responses": {
            "200": {
              "description": "Success - Your desired action was completed.",
              "content": {}
            },
            "218": {
              "description": "Nothing to do - make sure you are passing either cancel or followup.",
              "content": {}
            },
            "403": {
              "description": "Not authorized - double check your site id and token combination.",
              "content": {}
            }
          }
        }
      },
      "/products/reviews/{siteid}": {
        "get": {
          "tags": [
            "products"
          ],
          "summary": "Fetches product reviews.",
          "description": "This route will pull in all product reviews matching the provided parameters. By default it will pull 100 reviews at a time.",
          "parameters": [
            {
              "name": "siteid",
              "in": "path",
              "description": "The site ID you are requesting product reviews for.",
              "required": true,
              "schema": {
                "type": "integer"
              }
            },
            {
              "name": "token",
              "in": "query",
              "description": "Your API token",
              "required": true,
              "schema": {
                "type": "string"
              }
            },
            {
              "name": "asArray",
              "in": "query",
              "description": "If true, this will return the response as a JSON arry as opposed to the standard JSON object. (Enclosed in [] as opposed to {}.)",
              "schema": {
                "type": "boolean"
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "How many reviews you want returned in the response. Larger numbers may cause a timeout.",
              "schema": {
                "type": "integer",
                "default": 100
              }
            },
            {
              "name": "page",
              "in": "query",
              "description": "Which page you would like to request. The offset will be calculated by limit * page",
              "schema": {
                "type": "integer",
                "default": 0
              }
            },
            {
              "name": "from",
              "in": "query",
              "description": "The date you would like to start the query with. Should be given in YYYY-MM-DD format. Defaults to 30 days prior to the current day.",
              "schema": {
                "type": "string"
              }
            },
            {
              "name": "to",
              "in": "query",
              "description": "The date you would like to end the query with. Should be given in YYYY-MM-DD format. Defaults to the current date.",
              "schema": {
                "type": "string"
              }
            },
            {
              "name": "sort",
              "in": "query",
              "description": "How you would like to sort the reviews.",
              "schema": {
                "type": "string",
                "enum": [
                  "newest",
                  "oldest",
                  "highest",
                  "lowest"
                ]
              }
            },
            {
              "name": "removed",
              "in": "query",
              "description": "Include removed reviews? If set to 1 then reviews will include a 'removed' value equal to 1 if the review was removed and 0 if the review is active.",
              "schema": {
                "type": "integer",
                "enum": [
                  0,
                  1
                ]
              }
            },
            {
              "name": "xml",
              "in": "query",
              "description": "If true, this will return an XML tree instead of a JSON response.",
              "schema": {
                "type": "boolean",
                "default": false
              }
            }
          ],
          "responses": {
            "200": {
              "description": "Success - a JSON object with your product reviews will be returned.",
              "content": {}
            },
            "403": {
              "description": "Not Authorized - Either your site ID/token combination is incorrect or your site does not have product reviews.",
              "content": {}
            },
            "422": {
              "description": "Bad Request - One of your parameters was probably malformed.",
              "content": {}
            },
            "500": {
              "description": "Error - Something else went wrong. A bug report is automatically submitted.",
              "content": {}
            }
          }
        }
      },
      "/products/reviews/{siteid}/{productid}": {
        "get": {
          "tags": [
            "products"
          ],
          "summary": "Fetch reviews for a given product or parent ID.",
          "description": "This endpoint will fetch all reviews for a given product or parent ID. Using a parent ID will return reviews for all products with that parent ID. By default it will pull 100 reviews at a time. By defaul removed reviews will not be included in the result.",
          "parameters": [
            {
              "name": "siteid",
              "in": "path",
              "description": "The Site ID you are requesting the review for.",
              "required": true,
              "schema": {
                "type": "integer"
              }
            },
            {
              "name": "asArray",
              "in": "query",
              "description": "If true, this will return the response as a JSON arry as opposed to the standard JSON object. (Enclosed in [] as opposed to {}.)",
              "schema": {
                "type": "boolean"
              }
            },
            {
              "name": "productid",
              "in": "path",
              "description": "The product ID or parent ID you would like reviews for.",
              "required": true,
              "schema": {
                "type": "string"
              }
            },
            {
              "name": "token",
              "in": "query",
              "description": "Your API token.",
              "required": true,
              "schema": {
                "type": "string"
              }
            },
            {
              "name": "limit",
              "in": "query",
              "description": "How many reviews you want returned in the response. Larger numbers may cause a timeout.",
              "schema": {
                "type": "integer",
                "default": 100
              }
            },
            {
              "name": "page",
              "in": "query",
              "description": "Which page you would like to request. The offset will be calculated by limit * page",
              "schema": {
                "type": "integer",
                "default": 0
              }
            },
            {
              "name": "from",
              "in": "query",
              "description": "The date you would like to start the query with. Should be given in YYYY-MM-DD format. Defaults to 30 days prior to the current day.",
              "schema": {
                "type": "string"
              }
            },
            {
              "name": "to",
              "in": "query",
              "description": "The date you would like to end the query with. Should be given in YYYY-MM-DD format. Defaults to the current date.",
              "schema": {
                "type": "string"
              }
            },
            {
              "name": "sort",
              "in": "query",
              "description": "How you would like to sort the reviews.",
              "schema": {
                "type": "string",
                "enum": [
                  "newest",
                  "oldest",
                  "highest",
                  "lowest"
                ]
              }
            },
            {
              "name": "removed",
              "in": "query",
              "description": "Include removed reviews? If set to 1 then reviews will include a 'removed' value equal to 1 if the review was removed and 0 if the review is active.",
              "schema": {
                "type": "integer",
                "enum": [
                  0,
                  1
                ]
              }
            },
            {
              "name": "xml",
              "in": "query",
              "description": "If true, this will return an XML tree instead of a JSON response.",
              "schema": {
                "type": "boolean",
                "default": false
              }
            }
          ],
          "responses": {
            "200": {
              "description": "Success - a JSON object for your reviews will be returned.",
              "content": {}
            },
            "403": {
              "description": "Not authorized - your token is probably incorrect.",
              "content": {}
            },
            "404": {
              "description": "Not found - we couldn't find any reviews for the given product/parent ID.",
              "content": {}
            },
            "500": {
              "description": "Error - Something else went wrong. A bug report is automatically sent if this ever occurs.",
              "content": {}
            }
          }
        }
      },
      "/aggregates/reviews/{siteid}": {
        "get": {
          "tags": [
            "reviews",
            "aggregates"
          ],
          "summary": "Fetch aggregate statistics for your site",
          "description": "This endpoint will return aggregated statistics for the lifetime of your Shopper Approved account.",
          "parameters": [
            {
              "name": "siteid",
              "in": "path",
              "description": "The SiteId you are requesting statistics for",
              "required": true,
              "schema": {
                "type": "integer"
              }
            },
            {
              "name": "token",
              "in": "query",
              "description": "Your API token.",
              "required": true,
              "schema": {
                "type": "string"
              }
            },
            {
              "name": "xml",
              "in": "query",
              "description": "If true, this will return an XML tree instead of a JSON response.",
              "schema": {
                "type": "boolean",
                "default": false
              }
            }
          ],
          "responses": {
            "200": {
              "description": "Success - A JSON object with statistics will be returned",
              "content": {}
            },
            "403": {
              "description": "Not Authorized - Your token is probably incorrect.",
              "content": {}
            }
          }
        }
      },
      "/aggregates/products/{siteid}": {
        "get": {
          "tags": [
            "products",
            "aggregates"
          ],
          "summary": "Fetch aggregate product statistics for your site",
          "description": "This endpoint will return aggregated product feedback statistics for the lifetime of your Shopper Approved account as well as aggregates for all of your products.",
          "parameters": [
            {
              "name": "siteid",
              "in": "path",
              "description": "The SiteId you are requesting statistics for",
              "required": true,
              "schema": {
                "type": "integer"
              }
            },
            {
              "name": "token",
              "in": "query",
              "description": "Your API token.",
              "required": true,
              "schema": {
                "type": "string"
              }
            },
            {
              "name": "by_match_key",
              "in": "query",
              "description": "If true, this will display your product aggregate information by a matching key such as SKU or MPN. Results vary by site, only use this if you're confident it is what you need",
              "schema": {
                "type": "boolean"
              }
            },
            {
              "name": "asArray",
              "in": "query",
              "description": "If true, this will return the response as a JSON arry as opposed to the standard JSON object. (Enclosed in [] as opposed to {}.)",
              "schema": {
                "type": "boolean"
              }
            },
            {
              "name": "siteOnly",
              "in": "query",
              "description": "If true, this will return only the site_totals object and leave out specifics about each product.",
              "schema": {
                "type": "boolean"
              }
            },
            {
              "name": "xml",
              "in": "query",
              "description": "If true, this will return an XML tree instead of a JSON response.",
              "schema": {
                "type": "boolean",
                "default": false
              }
            },
            {
              "name": "fastmode",
              "in": "query",
              "description": "If true, use a highly optimized query. However, by_match and as_array will always be ignored in this mode.",
              "schema": {
                "type": "boolean",
                "default": false
              }
            }
          ],
          "responses": {
            "200": {
              "description": "Success - A JSON object with statistics will be returned",
              "content": {}
            },
            "403": {
              "description": "Not Authorized - Your token is probably incorrect.",
              "content": {}
            }
          }
        }
      },
      "/aggregates/products/{siteid}/{productid}": {
        "get": {
          "tags": [
            "products",
            "aggregates"
          ],
          "summary": "Fetch aggregate product statistics for a single product.",
          "description": "This endpoint will return aggregated product feedback statistics for a single product.",
          "parameters": [
            {
              "name": "siteid",
              "in": "path",
              "description": "The SiteId you are requesting statistics for",
              "required": true,
              "schema": {
                "type": "integer"
              }
            },
            {
              "name": "productid",
              "in": "path",
              "description": "The product or you are requesting statistics for",
              "required": true,
              "schema": {
                "type": "integer"
              }
            },
            {
              "name": "token",
              "in": "query",
              "description": "Your API token.",
              "required": true,
              "schema": {
                "type": "string"
              }
            },
            {
              "name": "xml",
              "in": "query",
              "description": "If true, this will return an XML tree instead of a JSON response.",
              "schema": {
                "type": "boolean",
                "default": false
              }
            }
          ],
          "responses": {
            "200": {
              "description": "Success - A JSON object with statistics will be returned",
              "content": {}
            },
            "403": {
              "description": "Not Authorized - Your token is probably incorrect.",
              "content": {}
            },
            "404": {
              "description": "Not Found - We could not find that product or parent ID.",
              "content": {}
            }
          }
        }
      }
    },
    "components": {},
    "x-original-swagger-version": "2.0"
  }