# Review

URL: /business/nouns/review · Id: `noun:review`

> A Review is one person’s rated evaluation of a Product, Offer or Brand, shown on a Site or an outside venue and mirrored from there.

A Review is one person’s rated evaluation of a [Product](/business/nouns/product), [Offer](/business/nouns/offer) or [Brand](/business/nouns/brand), shown on a [Site](/business/nouns/site) or an outside venue and mirrored from there.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `rating` | `integer` | Yes | The score, from 1 to 5. |
| `body` | `text` | No | The reviewer’s words. |
| `venue` | `string` | No | The venue it was posted on, by id; empty for the Startup’s own Site. |
| `displayConsent` | `boolean` | No | True once the reviewer agreed it may be shown on the Startup’s own Pages. Never randomized. |
| `status` | `string` | Yes | Where it stands; a removed Review is kept, never deleted. |
| `customer` | [Customer](/business/nouns/customer) | No | The Customer who wrote it, when known. |

## Object
```json
{
  "$id": "https://api.sb/kilnbakery.com/reviews/review_1",
  "$type": "Review",
  "rating": 1,
  "body": "Example body",
  "venue": "Example venue",
  "displayConsent": true,
  "status": "submitted",
  "customer": "customer_1"
}
```

## Relationships
- <a id="rel-evaluates"></a>A Review **evaluates** one [Offer](/business/nouns/offer): a Review evaluates one [Offer](/business/nouns/offer); Reviews of a [Product](/business/nouns/product) or [Brand](/business/nouns/brand) roll up through its Offers. `evaluates`, inverse [`reviews`](/business/nouns/offer#rel-reviews).

## Lifecycle

| State | Meaning | Moves to |
| --- | --- | --- |
| `submitted` (first) | Written and not yet shown. | `published` by [Review.publish](/business/nouns/review/publish); `withheld` by [Review.withhold](/business/nouns/review/withhold); `removed` by [Review.remove](/business/nouns/review/remove) |
| `published` | Shown on the Startup’s Pages or its venue, with its rating counted. | `withheld` by [Review.withhold](/business/nouns/review/withhold); `removed` by [Review.remove](/business/nouns/review/remove) |
| `withheld` | Kept off display for a recorded reason, never for its rating. | `published` by [Review.publish](/business/nouns/review/publish); `removed` by [Review.remove](/business/nouns/review/remove) |
| `removed` | Taken down for good at its author’s or its venue’s request; the record stays. | None: it ends here. |

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Review.publish](/business/nouns/review/publish) | Publish shows a Review on the Startup’s Pages with its rating counted, whatever the rating. | [Marketing Lead](/agents/marketing/marketing-lead) | [`Review.published`](/business/events/Review.published) | Two-way: `try`, `send`, `do` |
| [Review.remove](/business/nouns/review/remove) | Remove takes a Review down for good when its author or its venue asks; the record is kept. | [Marketing Lead](/agents/marketing/marketing-lead) | [`Review.removed`](/business/events/Review.removed) | Two-way: `try`, `send`, `do` |
| [Review.withhold](/business/nouns/review/withhold) | Withhold keeps a Review off display for one of five reasons, none of them its rating or its tone. | [Marketing Lead](/agents/marketing/marketing-lead) | [`Review.withheld`](/business/events/Review.withheld) | Two-way: `try`, `send`, `do` |
| <a id="create"></a>[Review.create](/business/nouns/review/create) | Creates a Review. Inherited from [Noun](/business/nouns/noun). | None. | `Review.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Review.get](/business/nouns/review/get) | Returns one Review by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Review.list](/business/nouns/review/list) | Returns Reviews, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Review.update](/business/nouns/review/update) | Changes the given properties of a Review. Inherited from [Noun](/business/nouns/noun). | None. | `Review.updated` | Two-way: `try`, `send`, `do` |

## Permissions
Which Access level may call each Verb. One-way Verbs wait their delay window.

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Review.create` | Yes | Yes | Yes | No |
| `Review.get` | Yes | Yes | Yes | Yes |
| `Review.list` | Yes | Yes | Yes | Yes |
| `Review.update` | Yes | Yes | Yes | No |
| `Review.publish` | Yes | Yes | Yes | No |
| `Review.remove` | Yes | Yes | Yes | No |
| `Review.withhold` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Publish the latest review.
```

**API**

```bash
curl -X POST https://api.sb/patentpad.com/reviews/review_1/publish \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
```

```json
{
  "api": "https://api.sb/patentpad.com",
  "review": {
    "$id": "https://api.sb/patentpad.com/reviews/review_1",
    "$type": "Review",
    "rating": 1,
    "status": "submitted"
  },
  "action": {
    "$id": "https://api.sb/patentpad.com/actions/action_1",
    "operation": "Review.publish",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/patentpad.com/actions/action_1"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const review = await $.Review.publish({ review: 'review_1' })
```

**CLI**

```bash
npx startup-builder do Review.publish --json '{"review":"review_1"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Review.publish({ review: 'review_1' })"
  }
}
```

## Example
A [Customer](/business/nouns/customer) of a dental-billing app leaves a 5-star Review on an outside venue after her first clean month. She agrees to display, so the Review also appears on the app's pricing [Page](/business/nouns/page).