REVIEWS.io MCP by usefulapi

The recommended way to read reviews: company (store) reviews, product reviews, third-party reviews and product questions in one filterable timeline, with the account's private data (reviewer e-mail, order). Filter by type, SKU/MPN/GTIN, tag, branch, keyword, date range, minimum rating, photos/videos; sort newest-first by default. Pages are 1-based; next_page is set when more results remain. GET /reviews.

{
  "type": "object",
  "properties": {
    "type": {
      "description": "What to return (default: all review kinds).",
      "type": "string",
      "enum": [
        "store_review",
        "product_review",
        "store_third_party_review",
        "questions"
      ]
    },
    "sku": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000,
      "description": "Product SKUs, separated by semicolons for several (e.g. \"SKU-1;SKU-2\")."
    },
    "mpn": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000,
      "description": "Product MPNs, separated by semicolons for several (e.g. \"SKU-1;SKU-2\")."
    },
    "gtin": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000,
      "description": "Product GTINs, separated by semicolons for several (e.g. \"SKU-1;SKU-2\")."
    },
    "tag": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000,
      "description": "Review tags, separated by semicolons for several (e.g. \"SKU-1;SKU-2\")."
    },
    "branch": {
      "description": "Only reviews of this branch name.",
      "type": "string",
      "maxLength": 200
    },
    "keyword": {
      "description": "Only reviews whose text contains this keyword.",
      "type": "string",
      "maxLength": 200
    },
    "email": {
      "description": "Only reviews left by this e-mail address.",
      "type": "string",
      "maxLength": 254
    },
    "with": {
      "description": "Only reviews with active photos, videos or either.",
      "type": "string",
      "enum": [
        "images",
        "videos",
        "media"
      ]
    },
    "date_from": {
      "description": "Reviews newer than this date (yyyy-mm-dd).",
      "type": "string"
    },
    "date_to": {
      "description": "Reviews older than this date (yyyy-mm-dd).",
      "type": "string"
    },
    "min_rating": {
      "description": "Minimum star rating 1-5.",
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    },
    "sort": {
      "description": "Sort order (default date_desc).",
      "type": "string",
      "enum": [
        "date_desc",
        "date_asc",
        "highest_rating",
        "lowest_rating",
        "helpful_desc",
        "helpful_asc",
        "date_update_desc",
        "date_update_asc"
      ]
    },
    "must_have_body": {
      "description": "Only reviews with a comment.",
      "type": "boolean"
    },
    "page": {
      "description": "Page, 1-based (default 1).",
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    },
    "per_page": {
      "description": "Results per page, 1-100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Company (store) reviews with private data (order number, reviewer details, tags) and optionally the replies. Filter by rating range, dates, order number, branch, invitation id; order by date or rating. Pages are 0-based; next_page is set when more remain. GET /merchant/reviews.

{
  "type": "object",
  "properties": {
    "review_id": {
      "description": "Return only this review.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "order_number": {
      "description": "Only reviews for this order number.",
      "type": "string",
      "maxLength": 200
    },
    "branch": {
      "description": "Only reviews of this branch name.",
      "type": "string",
      "maxLength": 200
    },
    "invitation_id": {
      "description": "Only the review that answered this invitation (service_feedback_email_id).",
      "type": "string",
      "maxLength": 100
    },
    "min_rating": {
      "description": "Minimum star rating 1-5.",
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    },
    "max_rating": {
      "description": "Maximum star rating 1-5.",
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    },
    "min_date": {
      "description": "Reviews created on or after this date (yyyy-mm-dd).",
      "type": "string"
    },
    "max_date": {
      "description": "Reviews created on or before this date (yyyy-mm-dd).",
      "type": "string"
    },
    "min_updated": {
      "description": "Reviews updated since this date (yyyy-mm-dd).",
      "type": "string"
    },
    "max_updated": {
      "description": "Reviews not updated after this date (yyyy-mm-dd).",
      "type": "string"
    },
    "order": {
      "description": "Order by date ascending/descending, or by rating.",
      "type": "string",
      "enum": [
        "asc",
        "desc",
        "rating"
      ]
    },
    "include_replies": {
      "description": "Include the store's replies to each review.",
      "type": "boolean"
    },
    "photos": {
      "description": "Only reviews with photos.",
      "type": "boolean"
    },
    "page": {
      "description": "Page, 0-based (default 0).",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000
    },
    "per_page": {
      "description": "Results per page, 1-100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Basic review statistics: average rating and review count for product reviews, company reviews and third-party reviews. GET /stats/all.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Average rating and review count for one or more products by SKU (batch). GET /product/rating-batch.

{
  "type": "object",
  "properties": {
    "sku": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000,
      "description": "Product SKUs, separated by semicolons for several (e.g. \"SKU-1;SKU-2\")."
    }
  },
  "required": [
    "sku"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Short, highlight-worthy review snippets (nuggets) of company and/or product reviews, for marketing. Filter by SKU, tags, branch, minimum rating. GET /review-nuggets/data.

{
  "type": "object",
  "properties": {
    "types": {
      "minItems": 1,
      "maxItems": 2,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "store_review",
          "product_review"
        ]
      },
      "description": "Which review kinds to draw nuggets from."
    },
    "sku": {
      "description": "Only these product SKUs.",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      }
    },
    "tags": {
      "description": "Only reviews with these tags.",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      }
    },
    "branch": {
      "description": "Only reviews of this branch.",
      "type": "string",
      "maxLength": 200
    },
    "min_rating": {
      "description": "Minimum star rating 1-5.",
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    },
    "per_page": {
      "description": "Results per page, 1-100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "types"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Customer photos/videos (UGC) collected through REVIEWS.io, filterable by SKU, tag, category or videos only. GET /ugc.

{
  "type": "object",
  "properties": {
    "sku": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000,
      "description": "Product SKUs, separated by semicolons for several (e.g. \"SKU-1;SKU-2\")."
    },
    "tags": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000,
      "description": "Tags, separated by semicolons for several (e.g. \"SKU-1;SKU-2\")."
    },
    "categories": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000,
      "description": "Categories, separated by semicolons for several (e.g. \"SKU-1;SKU-2\")."
    },
    "include_videos": {
      "description": "Only videos.",
      "type": "boolean"
    },
    "per_page": {
      "description": "Results per page, 1-100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The store's surveys (campaigns) with their ids; use an id with reviewsio_list_survey_responses. GET /widget/surveys.

{
  "type": "object",
  "properties": {
    "exclude_inactive": {
      "description": "Leave out inactive surveys.",
      "type": "boolean"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The responses submitted to one survey. Get the survey id from reviewsio_list_surveys. GET /widget/survey-responses.

{
  "type": "object",
  "properties": {
    "survey_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The survey id (campaign_id)."
    }
  },
  "required": [
    "survey_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Product review invitations that are queued or sent (customer, order, send date, status); filter by SKU, order id or sent state, and page through with page/limit. GET /product/invitation.

{
  "type": "object",
  "properties": {
    "sku": {
      "description": "Only invitations for this product SKU.",
      "type": "string",
      "maxLength": 200
    },
    "order_id": {
      "description": "Only invitations for this order id.",
      "type": "string",
      "maxLength": 200
    },
    "invite_sent": {
      "description": "true = only invitations already sent, false = only those still queued.",
      "type": "boolean"
    },
    "page": {
      "description": "Page (default 1).",
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    },
    "limit": {
      "description": "Invitations per page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Company review invitations that are queued or sent (customer, order, send date, status); filter by order id or sent state, and page through with page/limit. GET /merchant/invitations.

{
  "type": "object",
  "properties": {
    "order_id": {
      "description": "Only invitations for this order id.",
      "type": "string",
      "maxLength": 200
    },
    "invite_sent": {
      "description": "true = only invitations already sent, false = only those still queued.",
      "type": "boolean"
    },
    "page": {
      "description": "Page (default 1).",
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    },
    "limit": {
      "description": "Invitations per page.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

E-mail addresses that unsubscribed from (or were unsubscribed from) REVIEWS.io invitation e-mails. GET /unsubscribe/list.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The review-submitted webhooks registered for the store (read-only; this server never adds or removes webhooks). GET /webhook/list.

{
  "type": "object",
  "properties": {
    "page": {
      "description": "Page (default 1).",
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    },
    "per_page": {
      "description": "Results per page, 1-100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: adds a tag to one company review (visible in your REVIEWS.io dashboard and usable as a filter). Adding the same tag twice changes nothing. Nothing is sent to the customer. POST /review/tag/{id}.

{
  "type": "object",
  "properties": {
    "review_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The company review id (store_review_id)."
    },
    "tag": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "The tag to add, e.g. positive-review. Tags help you filter and display reviews."
    }
  },
  "required": [
    "review_id",
    "tag"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: adds a tag to one product review (visible in your REVIEWS.io dashboard and usable as a filter). Adding the same tag twice changes nothing. Nothing is sent to the customer. POST /product-review/tag/{id}.

{
  "type": "object",
  "properties": {
    "review_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The product review id."
    },
    "tag": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "The tag to add, e.g. positive-review. Tags help you filter and display reviews."
    }
  },
  "required": [
    "review_id",
    "tag"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: stops REVIEWS.io sending review invitation e-mails to one e-mail address. Use it for a customer who asked not to be contacted. This server has no tool to re-subscribe an address; it can only be undone in the REVIEWS.io dashboard. Nothing is sent to the customer. POST /unsubscribe/email.

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "maxLength": 254,
      "description": "The customer's e-mail address."
    }
  },
  "required": [
    "email"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE - SENDS A MESSAGE TO A REAL CUSTOMER: queues ONE company review invitation e-mail to the given customer address; REVIEWS.io then e-mails that person (when and with which template follows your Flow Sequence / template_id, usually within hours or days). It cannot be recalled from this server. Only call it when the user has explicitly asked to invite this exact customer, and pass confirm_send_email: true. There is no bulk or SMS invitation tool. POST /merchant/invitation.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "The customer's name (used in the e-mail greeting)."
    },
    "email": {
      "type": "string",
      "maxLength": 254,
      "description": "The customer's e-mail address: the invitation is sent HERE."
    },
    "order_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "The order reference (e.g. #12345)."
    },
    "template_id": {
      "description": "Invitation e-mail template id (overrides the Flow Sequence template).",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "confirm_send_email": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: confirms the user asked for a real e-mail to this customer."
    }
  },
  "required": [
    "name",
    "email",
    "order_id",
    "confirm_send_email"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}