> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoply.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Reviews

> What buyers say about their orders: how a review is left, where it shows, what nobody can do to one, and how to ask for one to be removed

A review belongs to a paid order. Every order can have one: a rating from one to five stars, and words if the buyer has any, up to 1,000 characters.

## How one is left

| | |
| - | - |
| **By the buyer** | On the order's own page, once it is paid. Every receipt has a **Leave a Review** button that leads there. That button is on every store's receipts and cannot be switched off. |
| **By itself** | An order nobody reviewed gets five stars seven days after it was paid, marked as left automatically. |

Automatic reviews are on for a new store. To stop them, open **Settings**, then **Payment Options**, then **Order Settings**, and switch **Automatic Reviews** off. Orders already reviewed keep what they have.

## A review is final

Nobody changes a review once it is left.

* The buyer cannot edit theirs, or replace one that was left automatically.
* You cannot edit, hide or delete one, from the dashboard or with the API.

That is the point of them: a rating a store could prune would tell a buyer nothing.

## Asking for one to be removed

A review that breaks the rules can be taken down, by Shoply and not by you. Under **Audience**, then **Reviews**, open a review's menu and choose **Flag for Removal**. Say what is wrong with it, and add your own words if they help.

| What Is Wrong with It | For a review that |
| - | - |
| **Abusive or Hateful** | Insults or threatens somebody, or attacks people for who they are. |
| **Shares Private Details** | Gives a name, an address, a phone number or anything else that identifies a person. |
| **Advertising or Spam** | Sells something, or sends readers to another shop. |
| **Not About This Order** | Is about another product, another store, or nothing the order held. |
| **Unlawful Content** | Says something the law does not allow to be published. |
| **Something Else** | Is none of these. Your own words are needed for this one. |

Somebody at Shoply reads every flag and answers it one of two ways.

* **Removed.** The review leaves your store, its products' ratings are worked out again without it, and the order's history says so. That order cannot be given another review.
* **Kept.** The review stays, and its row on your Reviews page reads **Flag Declined** with the reason.

A low rating is not a reason by itself, and neither is a review you think is unfair: a buyer may say what they thought of their order.

| | |
| - | - |
| **How Often** | A review can be flagged once. A store can flag 10 reviews a day. |
| **Which reviews** | The ones a buyer left. An automatic review is five stars with no words, so there is nothing in it to flag. |
| **Your own words** | Up to 1,000 characters. |

## Where they show

Your store's **Reviews** page lists them, newest first, each with what was bought. A buyer is shown as a verified buyer and never by their email address. A product's rating and its number of reviews, where a theme shows them, are worked out from the reviews of orders that held it.

In the dashboard they are under **Audience**, then **Reviews**: the average rating, how many are five stars, how many were written by buyers and how many were left automatically. Search by a buyer's email, an order's ID or a review's words.

## Being told

Under **Settings**, then **Notifications**, **New Reviews** posts each review a buyer writes to your store's Discord, with its stars, its words and its order. Automatic reviews are not posted.

Your own server can hear of every review, automatic ones included, with the [`review.created`](/api-reference/webhook-events#reviews) webhook event.

## With the API

Reviews can be read and nothing else: see [List reviews](/api-reference/reviews/list-reviews.md). A review you flagged carries `flag`, with how the flag stands and the answer it was given. Flagging itself is done in the dashboard.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.