@mercurjs/docs 2.3.8-canary.3 → 2.3.9-canary.1

package/content/platform/product-edit/reference/workflows.mdx

@@ -1,49 +1,191 @@
 ---
-title: "Workflows"
+title: "Product Edit workflows"
 sidebarTitle: "Workflows"
-description: "Product change workflows, service methods, and events."
+description: "Inputs, hooks, and events of every product change workflow, from staging to audit records."
 ---
 
-This reference lists the workflows for the Product Edit domain. Import them from
-`@mercurjs/core/workflows` and run them against the Medusa container.
+This page lists the workflows that stage, resolve, apply, and record product changes. Import them from `@mercurjs/core/workflows` and run them with the Medusa container, for example `confirmProductChangeWorkflow(container).run({ input })`. Each section gives the workflow id, the input, the hooks, and the events.
 
-## Lifecycle workflows
+## Edit workflows
 
-| Workflow | Input | Purpose |
+These workflows load the current product, diff your input against it, check that the author has no pending change on the product, and stage the result through `stageProductChangeWorkflow`. They return the staged `ProductChangeDTO`.
+
+### productEditUpdateProductWorkflow
+
+Id `product-edit-update-product`. Stages an `UPDATE` action per changed product field, and a `STATUS_CHANGE` action when `status` differs.
+
+| Input | Type | Description |
 | --- | --- | --- |
-| `createProductChangeWorkflow` | `{ changes[], additional_data? }` | Create pending changes (rejects if one is already pending) |
-| `stageProductChangeWorkflow` | `{ product_id, actions[], created_by?, internal_note?, external_note?, auto_confirm? }` | Create a change with actions, then run auto-confirm |
-| `confirmProductChangeWorkflow` | `{ ids[], confirmed_by?, internal_note?, external_note? }` | Mark `confirmed` and apply pending actions |
-| `rejectProductChangeWorkflow` | `{ id, declined_by?, declined_reason? }` | Move a `pending` change to `declined` |
-| `cancelProductChangeWorkflow` | `{ id, canceled_by? }` | Move a `pending` change to `canceled` |
-| `autoConfirmProductChangeWorkflow` | `{ change_id, confirmed_by?, force? }` | Confirm when review is off, or when `force` is set |
+| `product_id` | `string` | The product to edit |
+| `created_by` | `string`, optional | The author. Scopes the pending check |
+| `update` | `Record<string, unknown>` | Proposed values. Keys outside the diffed field list are ignored |
+| `additional_data` | `Record<string, unknown>`, optional | Passed to the `productChangeCreated` hook |
 
-## Apply workflows
+Hooks: `validate` with `{ input }`, and `productChangeCreated` with `{ product_change, additional_data }`.
+
+### productEditUpdateVariantsWorkflow
+
+Id `product-edit-update-variants`. Stages `VARIANT_ADD`, `VARIANT_UPDATE`, and `VARIANT_REMOVE` actions.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `product_id` | `string` | The product to edit |
+| `created_by` | `string`, optional | The author. Scopes the pending check |
+| `operations` | `ProductEditVariantOperation[]` | `{ type: "add", variant }`, `{ type: "update", variant_id, fields }`, or `{ type: "remove", variant_id }` |
+
+An update stages only the fields that differ, and `manage_inventory` is never staged. No hooks.
+
+### productEditUpdateAttributesWorkflow
+
+Id `product-edit-update-attributes`. Stages `ATTRIBUTE_ADD`, `ATTRIBUTE_UPDATE`, and `ATTRIBUTE_REMOVE` actions, skipping entries that wouldn’t change the product.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `product_id` | `string` | The product to edit |
+| `created_by` | `string`, optional | The author. Scopes the pending check |
+| `add` | `ProductAttributeBatchAdd[]`, optional | Attributes to attach |
+| `remove` | `string[]`, optional | Attribute ids to detach |
+| `update` | `ProductAttributeBatchUpdate[]`, optional | Changes to attached attributes |
+| `additional_data` | `Record<string, unknown>`, optional | Passed to the `productChangeCreated` hook |
+
+Hooks: `validate` with `{ input }`, and `productChangeCreated` with `{ product_change, additional_data }`.
+
+### productEditDeleteProductWorkflow
+
+Id `product-edit-delete-product`. Stages a single `PRODUCT_DELETE` action.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `product_id` | `string` | The product to delete |
+| `created_by` | `string`, optional | The author. Scopes the pending check |
+| `auto_confirm` | `boolean`, optional | Defaults to `true` when the product is a `draft`, else `false` |
+
+No hooks. On confirm, the product and its offers are deleted.
+
+## Staging and resolution workflows
+
+These workflows create a change and move it through its statuses.
+
+### stageProductChangeWorkflow
+
+Id `stage-product-change`. Creates one `pending` change with the given actions, emits `product-change.created`, then runs `autoConfirmProductChangeWorkflow`. It doesn’t check for an open change.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `product_id` | `string` | The product the change targets |
+| `actions` | `Omit<CreateProductChangeActionDTO, "product_change_id">[]` | The actions to stage |
+| `created_by` | `string`, optional | The author. Also used as `confirmed_by` on auto-confirm |
+| `internal_note` | `string`, optional | Note for operators |
+| `external_note` | `string`, optional | Note for the seller |
+| `auto_confirm` | `boolean`, optional | Confirm and apply in the same run |
+
+No hooks. Returns the created `ProductChangeDTO`, without its actions.
+
+### createProductChangeWorkflow
+
+Id `create-product-change`. Creates `pending` changes without actions, after checking that none of the products has a pending change from the same author. When the batch spans several authors, the check covers every pending change on those products.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `changes` | `CreateProductChangeDTO[]` | `product_id`, plus optional notes, `created_by`, and `metadata` |
+| `additional_data` | `Record<string, unknown>`, optional | Passed to the `productChangeCreated` hook |
+
+Hooks: `validate` with `{ input }`, and `productChangeCreated` with `{ changes, additional_data }`. Emits `product-change.created` per change.
 
-| Workflow | Input | Purpose |
+### autoConfirmProductChangeWorkflow
+
+Id `auto-confirm-product-change`. Runs `confirmProductChangeWorkflow` when `force` is `true` or the `product_request` feature flag is off. Otherwise it does nothing.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `change_id` | `string` | The change to confirm |
+| `confirmed_by` | `string`, optional | Stamped on the change |
+| `force` | `boolean`, optional | Confirm regardless of the flag |
+
+### confirmProductChangeWorkflow
+
+Id `confirm-product-change`. Sets every change in `ids` to `confirmed`, runs `applyProductChangeActionsWorkflow`, and emits `product-change.confirmed` per change. Fails if any change is missing or not `pending`.
+
+| Input | Type | Description |
 | --- | --- | --- |
-| `applyProductChangeActionsWorkflow` | `{ change_ids[] }` | Bucket not-yet-applied actions and dispatch them to product/variant workflows |
-| `applyProductAttributeChangeActionsWorkflow` | `{ product_id, add[], remove[], update[] }` | Apply the attribute batch for a change |
+| `ids` | `string[]` | The changes to confirm |
+| `confirmed_by` | `string`, optional | Stamped on each change |
+| `internal_note` | `string`, optional | Overwrites the operator note |
+| `external_note` | `string`, optional | Overwrites the seller note |
+| `additional_data` | `Record<string, unknown>`, optional | Passed to the `productChangeConfirmed` hook |
 
-## Edit helpers
+Hooks: `validate` with `{ input }`, and `productChangeConfirmed` with `{ ids, additional_data }`.
 
-High-level workflows that diff your input and stage the right actions for you.
+### rejectProductChangeWorkflow
 
-| Workflow | Input | Purpose |
+Id `reject-product-change`. Sets one `pending` change to `declined` and emits `product-change.declined`.
+
+| Input | Type | Description |
 | --- | --- | --- |
-| `productEditUpdateProductWorkflow` | `{ product_id, update, created_by? }` | Diff and stage `UPDATE` actions per changed field |
-| `productEditUpdateVariantsWorkflow` | `{ product_id, ... }` | Stage `VARIANT_*` actions |
-| `productEditUpdateAttributesWorkflow` | `{ product_id, ... }` | Stage `ATTRIBUTE_*` actions |
-| `productEditDeleteProductWorkflow` | `{ product_id, ... }` | Stage a `PRODUCT_DELETE` action |
+| `id` | `string` | The change to decline |
+| `declined_by` | `string`, optional | Stamped on the change |
+| `declined_reason` | `string`, optional | Reason for the seller |
+| `additional_data` | `Record<string, unknown>`, optional | Passed to the `productChangeRejected` hook |
+
+Hooks: `validate` with `{ input }`, and `productChangeRejected` with `{ id, additional_data }`.
 
-## Audit-trail workflows
+### cancelProductChangeWorkflow
 
-| Workflow | Input | Purpose |
+Id `cancel-product-change`. Sets one `pending` change to `canceled` and emits `product-change.canceled`.
+
+| Input | Type | Description |
 | --- | --- | --- |
-| `recordProductAuditChangeWorkflow` | `{ actor_id?, changes[] }` | Record already-`confirmed` audit changes (actions stored `applied`) |
-| `requestProductChangeWorkflow` | `{ product_id, message?, actor_id? }` | Record a `CHANGE_REQUESTED` revision request on a `proposed` product |
+| `id` | `string` | The change to cancel |
+| `canceled_by` | `string`, optional | Stamped on the change |
+| `additional_data` | `Record<string, unknown>`, optional | Passed to the `productChangeCanceled` hook |
+
+Hooks: `validate` with `{ input }`, and `productChangeCanceled` with `{ id, additional_data }`.
+
+## Apply workflows
+
+`confirmProductChangeWorkflow` runs these for you, so you rarely call them yourself.
+
+### applyProductChangeActionsWorkflow
+
+Id `apply-product-change-actions`. Input `{ change_ids: string[] }`. Loads the unapplied actions of the given changes, groups them by type, runs Medusa’s product and variant workflows, deletes the offers of deleted products, and marks the handled actions `applied`. No hooks, no events of its own.
+
+### applyProductAttributeChangeActionsWorkflow
+
+Id `apply-product-attribute-change-actions`. Input `{ product_id, add, remove, update }`. Runs `createAndLinkProductAttributesToProductWorkflow` when any array is non-empty. No hooks.
+
+## Audit workflows
+
+These workflows record history that doesn’t need review.
+
+### recordProductAuditChangeWorkflow
+
+Id `record-product-audit-change`. Creates changes that start `confirmed`, with `actor_id` as both `created_by` and `confirmed_by`, and stores every action with `applied: true`. It doesn’t touch the product and emits no event.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `actor_id` | `string`, optional | The actor to stamp |
+| `changes` | `array` | Each entry has `product_id`, `actions`, and optional `internal_note` and `external_note` |
+
+### requestProductChangeWorkflow
+
+Id `mercur-request-product-change`. Checks that the product is `proposed`, records a `CHANGE_REQUESTED` audit change with the message as `external_note`, and emits `product.change-requested`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `product_id` | `string` | The proposed product |
+| `message` | `string`, optional | What the seller should change |
+| `actor_id` | `string`, optional | The operator making the request |
+| `additional_data` | `Record<string, unknown>`, optional | Passed to the hook |
+
+Hooks: `productChangeRequested` with `{ product_id, message, additional_data }`.
+
+## Steps
+
+The module’s steps are exported from `@mercurjs/core/workflows` for your own workflows:
+
+- **Create**: `createProductChangesStep`, `createProductChangeActionsStep`, `addProductChangeActionStep`
+- **Resolve**: `confirmProductChangesStep`, `declineProductChangeStep`, `cancelProductChangeStep`
+- **Update**: `updateProductChangeActionsStep`, `applyVariantImageLinksStep`
+- **Validate**: `validateNoPendingProductChangeStep`, `validateProductChangeIsPendingStep`, `confirmProductChangeValidationStep`
 
-To work with records directly instead of through a workflow, see the
-[Service reference](/platform/product-edit/reference/service). To run side effects
-when a change resolves, see the
-[Event reference](/platform/product-edit/reference/events).
+The create, resolve, and `updateProductChangeActionsStep` steps compensate by deleting or restoring what they wrote. `applyVariantImageLinksStep` has no compensation, and the validation steps write nothing.

package/content/platform/review/concepts/product-vs-seller-reviews.mdx

@@ -1,63 +1,64 @@
 ---
-title: "Product vs seller reviews"
+title: "Product reviews and store reviews"
 sidebarTitle: "Product vs seller reviews"
-description: "The reference discriminator and the links that anchor each review."
+description: "How the reference field picks a review's target, and the four links that anchor every review."
 ---
 
-This page covers how one review model serves two targets and how each review is
-anchored to the rest of the marketplace.
+A customer can rate the product they bought, the store that sold it, or both. Mercur uses one `Review` model for both cases and sets `reference` to `product` or `seller` to say which one a review rates. The target itself is stored as a module link, written when the review is created, alongside links to the order and the customer.
 
-## Reference
+## The reference field picks the link
 
-The `reference` field on the `Review` model decides what a review is about. It's
-an enum with two values, `product` and `seller`, and it works together with the
-review's link to the target record. There is no polymorphic id column on the
-model itself; the target is resolved through a module link.
+You pass `reference` and `reference_id` to `createReviewWorkflow`. The workflow stores `reference` on the review, then writes one link from `reference_id` to the review:
+
+| `reference` | `reference_id` is | Link written |
+| --- | --- | --- |
+| `product` | A product id, such as `prod_01JD8Q1234567` | Product to review |
+| `seller` | A seller id, such as `sel_01JD8Q1234567` | Seller to review |
+
+`reference_id` isn’t stored on the review. To read the target back, follow the relation that matches `reference`:
 
 ```ts
-// A product review
-{ reference: "product", reference_id: "prod_123", rating: 5 }
+const { data: [review] } = await query.graph({
+  entity: "review",
+  fields: ["id", "reference", "rating", "product.title", "seller.name"],
+  filters: { id: "rev_01JD8Q1234567" },
+})
 
-// A seller review
-{ reference: "seller", reference_id: "sel_123", rating: 4 }
+const target = review.reference === "product"
+  ? review.product
+  : review.seller
 ```
 
-When a review is created, the `reference` value selects which link is written:
-`reference: "product"` links the review to a product, and `reference: "seller"`
-links it to a seller. Reading a review back, you follow the matching relation
-(`review.product` or `review.seller`) to reach its target.
+Only one of `review.product` and `review.seller` is set on any review.
 
 <Note>
-  Products are the shared master catalog, not seller-owned. A **product** review
-  rates the master product; a **seller** review rates the store. They are
-  independent. A customer can leave both for the same order.
+  Products are Mercur’s shared master catalog, not owned by a store. A product review rates the master product, so it has no link to the store that sold it. Only seller reviews are linked to a seller.
 </Note>
 
-## Order & customer links
+## Every review links to its order and customer
 
-Beyond its target, every review is anchored to the order that earned it and the
-customer who wrote it. Creating a review writes two more links, one to the
-`Order` and one to the `Customer`, so a review always has a verifiable purchase
-behind it.
+Apart from its target, each review is linked to the order that earned it and the customer who wrote it. The `create-review` step writes both links in the same step that creates the record. These links back the ownership checks across the APIs:
 
-```ts
-// resolved through the customer link when listing a customer's own reviews
-const { data } = await query.graph({
-  entity: "customer_customer_review_review",
-  fields: ["review.*"],
-  filters: { customer_id: "cus_123" },
-})
-```
+- **Store API**: a customer can read, edit, and delete only reviews linked to their customer id
+- **Vendor API**: a store can list, read, and answer only reviews linked to its seller id
+- **Validation**: duplicate checks look up existing reviews through the order link
 
-## One review per target, per order
+## Stores see only seller reviews
 
-Because a review is tied to an order, the create flow enforces that a customer
-can leave **at most one review per target per order**. Submitting a second review
-for the same `reference` and `reference_id` on the same order is rejected. The
-order must also belong to the customer submitting the review.
+Because product reviews carry no seller link, the Vendor API never returns them. `GET /vendor/reviews` filters on the seller link, and answering a review checks the same link. A store can’t answer a review of a product it sells: only an operator can, through the Admin API.
+
+## One review per target per order
+
+`createReviewWorkflow` rejects a second review of the same target from the same order. It loads every review linked to `order_id` and fails with “Review already exists” when one has the same `reference` and the same target id. It also fails with “Order not found!” when the order doesn’t belong to `customer_id`.
 
 <Tip>
-  A single order can still produce several reviews, one per distinct target. For
-  example, a customer may review the master product *and* the store that
-  fulfilled it from the same order.
+  One order can back several reviews, one per distinct target. A customer can rate the master product and the store from the same order, as order `#1001` does in the overview figure.
 </Tip>
+
+The workflow doesn’t check that `reference_id` appears in the order. A customer with any order can review any product or seller id. Add that check in your own route if your marketplace needs it.
+
+## Related
+
+- [The four review links and their query.graph aliases](/platform/review/reference/links)
+- [Respond to a review as a store](/platform/review/guides/respond-to-a-review)
+- [What a review stores](/platform/review/concepts/the-review-model)

package/content/platform/review/concepts/ratings-and-moderation.mdx

@@ -1,64 +1,65 @@
 ---
-title: "Ratings & moderation"
+title: "How reviews are moderated and rated"
 sidebarTitle: "Ratings & moderation"
-description: "The review status lifecycle, store responses, and aggregate ratings."
+description: "The review status values, who can change them, how a store answers, and how average ratings are computed."
 ---
 
-This page covers how a review moves from submission to a public rating, and how
-per-product and per-seller averages are computed.
+A review reaches shoppers only after an operator approves it, and a store can add one public answer. Moderation is a change to the review’s `status` field, an answer is a write to its `seller_note`, and removal is a soft delete. Average ratings aren’t stored anywhere: the Review module service computes them from the review rows each time you ask.
 
-## Status
+## Status values
 
-A review's state is held in the `status` field of the `Review` model. A review
-moves through three statuses:
-
-```
-   ┌──────────┐   publish   ┌────────────┐
-   │  pending  │───────────►│  published  │
-   └────┬─────┘             └────────────┘
-        │ reject
-        ▼
-   ┌────────────┐
-   │  rejected   │
-   └────────────┘
-```
+A review’s `status` holds one of three values. Every review starts as `pending`, and only `updateReviewWorkflow` changes it.
 
 | Status | Meaning |
 | --- | --- |
-| `pending` | Submitted, awaiting moderation. The default on creation |
-| `published` | Approved and visible on the storefront |
-| `rejected` | Declined by a moderator |
+| `pending` | Submitted and waiting for an operator. The default |
+| `published` | Approved for display |
+| `rejected` | Declined by an operator |
+
+<img className="block dark:hidden" src="/images/figures/review-moderation-light.svg" alt="Behind, a review record. In front, the changes each workflow makes: updateReviewWorkflow moves status between pending, published, and rejected in any direction, respondReviewWorkflow sets seller_note once, and deleteReviewWorkflow sets deleted_at." />
+<img className="hidden dark:block" src="/images/figures/review-moderation-dark.svg" alt="Behind, a review record. In front, the changes each workflow makes: updateReviewWorkflow moves status between pending, published, and rejected in any direction, respondReviewWorkflow sets seller_note once, and deleteReviewWorkflow sets deleted_at." />
+
+The workflow enforces no order between statuses. An operator can publish a rejected review or move a published one back to `pending`. Who can set the status depends on the API:
+
+- **Admin API**: `POST /admin/reviews/:id` sets `status`, `rating`, and `customer_note`
+- **Vendor API**: a store can’t change `status` or `rating`; the respond route ignores both fields
+- **Store API**: a customer can edit `rating` and `customer_note`, but not `status`
 
-A review is created as `pending`. Moderation moves it to `published` or
-`rejected` by updating the `status` field. See
-[Moderate a review](/platform/review/guides/moderate-a-review).
+<Warning>
+  A customer edit doesn’t reset a published review to `pending`. If edited reviews should go back through moderation, wrap the Store route or `updateReviewWorkflow` and set the status yourself.
+</Warning>
 
-## Store responses
+## Store answers
 
-A store can attach a single public response to any of its reviews. The response
-lives in the `seller_note` field and is added through a dedicated respond flow,
-which refuses to overwrite an existing response.
+A store answers a review by writing `seller_note` through `respondReviewWorkflow`. The workflow refuses a second answer: it fails when `seller_note` is already set, so the first answer stays until someone clears it with `updateReviewWorkflow`. Answering never touches `status`, so a store can answer a `pending` review before it’s published.
 
-<Note>
-  Responding is separate from moderation. A store adds its `seller_note`, while
-  the `status` transition (`published` / `rejected`) stays an operator decision.
-</Note>
+Over HTTP, a store answers with `POST /vendor/reviews/:id`, which only accepts reviews linked to that store, so only seller reviews. An operator answers any review with `POST /admin/reviews/:id/respond`.
 
-## Aggregate ratings
+## Deletion is soft
 
-The module service computes average ratings on demand rather than storing a
-denormalized column. `getAvgRating` returns the average for a single product or
-seller, and `getProductsWithRating` / `getSellersWithRating` return records with
-their average rating joined in for list views.
+`deleteReviewWorkflow` soft deletes the review: it sets `deleted_at` and keeps the row and its links. `query.graph` and the APIs stop returning it, and the workflow restores it if a later step fails. Operators delete with `DELETE /admin/reviews/:id`, and customers delete their own reviews with `DELETE /store/reviews/:id`.
+
+## Average ratings are computed on read
+
+The service’s rating helpers run an `AVG(rating)` query over the review table, joined through the product or seller link table. There’s no stored average to keep in sync. The helpers apply no filters beyond the target, which affects what counts:
+
+- **Every status counts**: `pending` and `rejected` reviews are part of the average
+- **Soft deleted reviews count**: the query doesn’t check `deleted_at`, and the link rows stay in place
+- **No reviews**: `getAvgRating` returns `null`
 
 ```ts
-const service = container.resolve(MercurModules.REVIEW)
+const reviewService = container.resolve(MercurModules.REVIEW)
 
-const avg = await service.getAvgRating("seller", "sel_123")
+const average = await reviewService.getAvgRating(
+  "seller",
+  "sel_01JD8Q1234567"
+)
 ```
 
-<Tip>
-  Because averages are computed at query time, they always reflect the current
-  set of reviews. There's no cache to invalidate when a review is added, removed,
-  or moderated.
-</Tip>
+This returns the store’s average as a numeric string, such as `"4.5000000000000000"`, or `null`. When only published reviews should count, compute the average from `query.graph` results instead, as shown in [Compute aggregate ratings](/platform/review/guides/compute-aggregate-ratings).
+
+## Related
+
+- [Moderate a review from server code](/platform/review/guides/moderate-a-review)
+- [Respond to a review](/platform/review/guides/respond-to-a-review)
+- [Rating helper signatures](/platform/review/reference/service)

package/content/platform/review/concepts/the-review-model.mdx

@@ -1,56 +1,63 @@
 ---
-title: "The review model"
+title: "What a review stores"
 sidebarTitle: "The review model"
-description: "The single review entity, its rating, notes, and moderation status."
+description: "The fields of a review: its target type, rating, the customer's note, the store's answer, and its status."
 ---
 
-This page covers the review record and the fields that make up a rating.
+A review is one customer’s rating of one product or one store, earned by an order. Mercur stores it as a single `Review` record (table `review`, id prefix `rev`) in the Review module. Knowing its fields tells you what a review can hold, what a store can add to it, and what an operator changes when moderating it.
 
-## Review
+## One record per rating
 
-A review is a customer's rating of a single target, either a product or a seller.
-It's represented by the `Review` data model (table `review`, id prefix `rev`). It
-holds the numeric rating, an optional customer note, an optional store response,
-and the moderation status.
+Every review has the same shape, whatever it rates. The record holds the score and the text around it, while the product, store, order, and customer it belongs to live in module links rather than columns.
+
+| Field | Holds |
+| --- | --- |
+| `id` | The review id, such as `rev_01JD8Q1234567` |
+| `display_id` | An auto-incrementing number for people to read |
+| `reference` | The target type: `product` or `seller` |
+| `rating` | The score as an integer |
+| `customer_note` | The customer’s text, or `null` |
+| `seller_note` | The store’s answer, or `null` |
+| `status` | `pending`, `published`, or `rejected` |
+
+A review has no `product_id` or `seller_id` column. The `reference` value tells you which link to follow, as covered in [Product vs seller reviews](/platform/review/concepts/product-vs-seller-reviews).
+
+## Ratings are integers from 1 to 5 at the API
+
+The `rating` column is an integer with no range check in the model itself. The Store and Admin API validators accept whole numbers from 1 to 5, so every review created over HTTP falls in that range:
+
+- **Store API**: `rating` is required on create and update, and must be an integer from 1 to 5
+- **Admin API**: `rating` is optional on update, with the same 1 to 5 range
+- **Workflows**: `createReviewWorkflow` and `updateReviewWorkflow` store whatever number you pass
+
+<Warning>
+  When you run the workflows from your own code, validate `rating` yourself. A value outside 1 to 5 is stored as is and skews every average that includes it.
+</Warning>
+
+## Two notes, two authors
+
+A review keeps the two sides of the conversation in separate fields. The customer writes `customer_note` when they submit or edit the review, and the store writes `seller_note` once, through `respondReviewWorkflow`. Both are nullable text fields marked searchable, so a `q` search in the Admin and Vendor APIs matches their content.
 
 ```ts
-const { result } = await createReviewWorkflow(container).run({
-  input: {
-    order_id: "order_123",
-    reference: "product",
-    reference_id: "prod_123",
-    rating: 5,
-    customer_note: "Exactly as described, fast shipping.",
-    customer_id: "cus_123",
-  },
-})
+const review = {
+  id: "rev_01JD8Q1234567",
+  display_id: 1042,
+  reference: "product",
+  rating: 4,
+  customer_note: "Fits well, the colour is darker than shown.",
+  seller_note: "Thanks, we've updated the product photos.",
+  status: "published",
+}
 ```
 
-Every review carries the same shape regardless of what it targets:
+This is the shape `query.graph` returns for a review’s own fields. The Store API caps `customer_note` at 300 characters, the Admin API at 1000, and both APIs cap `seller_note` at 300.
 
-| Field | Purpose |
-| --- | --- |
-| `rating` | The numeric score the customer gave |
-| `reference` | Whether the review is about a `product` or a `seller` |
-| `customer_note` | The customer's optional free-text note |
-| `seller_note` | The store's optional public response |
-| `status` | The moderation state: `pending`, `published`, or `rejected` |
-| `display_id` | A human-readable auto-incrementing number |
-
-<Note>
-  There is no separate table for product reviews and seller reviews. A single
-  `Review` row is discriminated by its `reference` field. See
-  [Product vs seller reviews](/platform/review/concepts/product-vs-seller-reviews).
-</Note>
-
-## Notes
-
-A review separates the two sides of the conversation into two nullable text
-fields. `customer_note` is written by the customer when they submit the review;
-`seller_note` is the store's single response, added later through the respond
-flow. Both are searchable so operators can find reviews by their content.
-
-<Tip>
-  A store can respond **once**. The respond flow refuses to overwrite an existing
-  `seller_note`. To change a response, clear it first.
-</Tip>
+## Status starts at pending
+
+Every new review gets `status: "pending"`, the model default. An operator then sets it to `published` or `rejected` with `updateReviewWorkflow`. Nothing in core hides a pending review from a storefront for you, since core has no public review listing: your own route decides which statuses to show. See [Ratings and moderation](/platform/review/concepts/ratings-and-moderation) for the full set of changes.
+
+## Related
+
+- [How reviews pick their target](/platform/review/concepts/product-vs-seller-reviews)
+- [Every field and index of the Review model](/platform/review/reference/data-models)
+- [Create a review from a custom route](/platform/review/guides/create-a-review)