@mercurjs/docs 2.2.1 → 2.3.0-canary.1

package/content/platform/product-edit/guides/edit-a-product.mdx

@@ -0,0 +1,74 @@
+---
+title: "Edit a product"
+sidebarTitle: "Edit a product"
+description: "Stage a product change from server code with the edit workflows."
+---
+
+In this guide, you'll learn how to route a product edit through the change
+pipeline from your own server code, such as a custom API route or a bulk tool.
+
+Instead of writing to a product directly, you stage a `ProductChange`. Mercur
+exposes high-level edit workflows that diff your update against the current
+product and stage only the fields that actually changed.
+
+## Update product fields
+
+`productEditUpdateProductWorkflow` diffs the `update` payload against the product
+and stages an `UPDATE` action per changed field.
+
+```ts title="src/api/custom/edit/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { productEditUpdateProductWorkflow } from "@mercurjs/core/workflows"
+
+export async function POST(req: MedusaRequest, res: MedusaResponse) {
+  const { result } = await productEditUpdateProductWorkflow(req.scope).run({
+    input: {
+      product_id: req.params.id,
+      created_by: req.auth_context?.actor_id,
+      update: { title: "Updated title", material: "Cotton" },
+    },
+  })
+
+  res.status(201).json({ product_change: result })
+}
+```
+
+<Note>
+  If a product already has a `pending` change, staging another one is rejected.
+  Only one active change per product is allowed. Resolve or cancel the open
+  change first.
+</Note>
+
+## Stage actions directly
+
+For finer control (variants, attributes, mixed operations), stage the actions
+yourself with `stageProductChangeWorkflow`:
+
+```ts
+import { stageProductChangeWorkflow } from "@mercurjs/core/workflows"
+
+await stageProductChangeWorkflow(container).run({
+  input: {
+    product_id: "prod_123",
+    created_by: "user_123",
+    actions: [
+      { product_id: "prod_123", action: "UPDATE", details: { field: "subtitle", value: "New" } },
+      { product_id: "prod_123", action: "VARIANT_REMOVE", details: { variant_id: "variant_123" } },
+    ],
+  },
+})
+```
+
+## Auto-confirm
+
+Both workflows run auto-confirm after staging: with review off the change
+applies immediately, with review on it stays `pending`. Pass `auto_confirm: true`
+to `stageProductChangeWorkflow` to force immediate application regardless of the
+review setting.
+
+<Tip>
+  Dedicated helpers exist for common shapes, such as
+  `productEditUpdateVariantsWorkflow`, `productEditUpdateAttributesWorkflow`, and
+  `productEditDeleteProductWorkflow`. Each stages the right action types for you.
+  See the [Workflows reference](/platform/product-edit/reference/workflows).
+</Tip>

package/content/platform/product-edit/guides/request-a-revision.mdx

@@ -0,0 +1,54 @@
+---
+title: "Request a revision"
+sidebarTitle: "Request a revision"
+description: "Send a product submission back to the vendor from server code."
+---
+
+In this guide, you'll learn how to ask a vendor to rework a submission instead of
+approving or rejecting it outright.
+
+A revision request doesn't mutate the product. It records a `CHANGE_REQUESTED`
+action in the audit trail carrying your message, and emits
+`product.change-requested` so the vendor is notified. The product stays with the
+vendor to revise and resubmit.
+
+## Run the workflow
+
+`requestProductChangeWorkflow` validates that the product is in `proposed`,
+records the audit action, and emits the event.
+
+```ts title="src/api/custom/request-revision/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { requestProductChangeWorkflow } from "@mercurjs/core/workflows"
+
+export async function POST(req: MedusaRequest, res: MedusaResponse) {
+  await requestProductChangeWorkflow(req.scope).run({
+    input: {
+      product_id: req.params.id,
+      actor_id: req.auth_context?.actor_id,
+      message: "Please add a size guide and sharper photos.",
+    },
+  })
+
+  res.sendStatus(200)
+}
+```
+
+<Note>
+  The request is only valid while the product is `proposed`. The workflow
+  validates the product status first and fails otherwise.
+</Note>
+
+## Where the message goes
+
+The `message` is stored in two places for durability: the `CHANGE_REQUESTED`
+action's `details.message`, and the parent change's `external_note` (the
+vendor-facing note). Because the audit change is created already `confirmed`, the
+request is a permanent entry in the product's history.
+
+<Tip>
+  Subscribe to `product.change-requested` to send the vendor a notification. The
+  payload includes the `id` (product), the `message`, and the `actor_id` of the
+  operator who asked. See the
+  [Event reference](/platform/product-edit/reference/events).
+</Tip>

package/content/platform/product-edit/overview.mdx

@@ -0,0 +1,85 @@
+---
+title: "Product Edit"
+sidebarTitle: "Overview"
+description: "Route every product edit through a reviewable, immutable change pipeline."
+---
+
+Use Mercur to keep a full audit trail of every product change and govern your
+master data before it changes.
+
+Master-data governance depends on knowing who changed what, and reviewing it
+before it takes effect. The Product Edit domain is that auditable change
+pipeline. Every edit becomes an immutable, attributed `ProductChange` record that
+enters an approval queue, so no change to a shared product is silently written.
+Each record carries typed actions and a status lifecycle, and the trail records
+who changed what and who approved it.
+
+<Note>
+  **Product Edit ≠ product ownership.** Products are the shared master catalog,
+  and sellers sell against them through offers. Product Edit governs *changes* to
+  a product. It never makes a store the owner of one.
+</Note>
+
+## Key features
+
+- **Immutable audit trail:** every edit is an attributed `ProductChange` that is never rewritten, only appended to and resolved.
+- **Typed change actions:** each edit is expressed as `ProductChangeAction` rows such as `UPDATE`, `VARIANT_*`, `ATTRIBUTE_*`, `STATUS_CHANGE`, or `PRODUCT_ADD/DELETE`.
+- **Approval queue:** a change moves `pending` → `confirmed` / `declined` / `canceled`, each through a dedicated workflow.
+- **Deferred application:** actions are applied to the product only on confirmation, then marked `applied`.
+- **Auto-confirm:** when review is off, staged changes confirm and apply immediately.
+- **Revision requests:** operators send a submission back to the vendor as a recorded `CHANGE_REQUESTED` audit action.
+- **One active change per product:** a product can't have two pending changes at once.
+
+## Get started
+
+Learn how the domain fits together:
+
+<CardGroup cols={2}>
+  <Card title="The change pipeline" icon="clock-rotate-left" href="/platform/product-edit/concepts/change-pipeline">
+    The `ProductChange` record, immutability, and the audit trail.
+  </Card>
+  <Card title="Change actions" icon="list-check" href="/platform/product-edit/concepts/change-actions">
+    The typed actions that make up a change and their `details`.
+  </Card>
+  <Card title="Status & auto-confirm" icon="arrows-rotate" href="/platform/product-edit/concepts/status-and-auto-confirm">
+    The status lifecycle, revision requests, and auto-confirm.
+  </Card>
+</CardGroup>
+
+## Examples
+
+Build against the Product Edit domain in your own code:
+
+<CardGroup cols={2}>
+  <Card title="Edit a product" icon="pen" href="/platform/product-edit/guides/edit-a-product">
+    Stage a product change from server code.
+  </Card>
+  <Card title="Confirm or decline" icon="gavel" href="/platform/product-edit/guides/confirm-or-decline-a-change">
+    Resolve a pending change in code.
+  </Card>
+  <Card title="Request a revision" icon="rotate-left" href="/platform/product-edit/guides/request-a-revision">
+    Send a submission back to the vendor.
+  </Card>
+</CardGroup>
+
+## Resources
+
+Data models, workflows, service methods, and events for the Product Edit domain:
+
+<CardGroup cols={2}>
+  <Card title="Data models" icon="table" href="/platform/product-edit/reference/data-models">
+    The `ProductChange` and `ProductChangeAction` entities.
+  </Card>
+  <Card title="Links" icon="link" href="/platform/product-edit/reference/links">
+    How the Product Edit domain links to other modules.
+  </Card>
+  <Card title="Workflows" icon="diagram-project" href="/platform/product-edit/reference/workflows">
+    Create, confirm, decline, cancel, and stage workflows.
+  </Card>
+  <Card title="Service" icon="gear" href="/platform/product-edit/reference/service">
+    Module service methods for working with records directly.
+  </Card>
+  <Card title="Events" icon="bell" href="/platform/product-edit/reference/events">
+    Events emitted as changes move through the pipeline.
+  </Card>
+</CardGroup>

package/content/platform/product-edit/reference/data-models.mdx

@@ -0,0 +1,65 @@
+---
+title: "Data models"
+sidebarTitle: "Data models"
+description: "The data models owned by the Product Edit domain."
+---
+
+The Product Edit domain is owned by the **Product Edit module**
+(`MercurModules.PRODUCT_EDIT`). This reference lists its data models and their
+fields.
+
+## ProductChange
+
+Table `product_change`, id prefix `prodch`. A single reviewable edit to one
+product.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `id` | text | Primary key |
+| `product_id` | text | The product this change targets (indexed) |
+| `status` | enum | `ProductChangeStatus`, default `pending` (indexed) |
+| `internal_note` | text | Nullable; operator-only note |
+| `external_note` | text | Nullable; vendor-facing note |
+| `created_by` | text | Nullable; actor who staged the change |
+| `confirmed_by` / `confirmed_at` | text / dateTime | Nullable; set on confirm |
+| `declined_by` / `declined_at` | text / dateTime | Nullable; set on decline |
+| `declined_reason` | text | Nullable |
+| `canceled_by` / `canceled_at` | text / dateTime | Nullable; set on cancel |
+| `requires_action_by` / `requires_action_at` | text / dateTime | Nullable |
+| `requires_action_reason` | text | Nullable |
+| `metadata` | json | Nullable |
+
+Relations: `actions` (one-to-many `ProductChangeAction`, cascade-deleted with the
+change).
+
+<Note>
+  The `status` enum has four values: `pending`, `confirmed`, `declined`, and
+  `canceled`. A revision request is recorded as a `CHANGE_REQUESTED` audit action
+  rather than a distinct status.
+</Note>
+
+## ProductChangeAction
+
+Table `product_change_action`, id prefix `prodchact`. A single typed operation
+inside a change.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `id` | text | Primary key |
+| `product_id` | text | The product the action targets (indexed) |
+| `product_change_id` | text | Nullable FK to the parent change (`ON DELETE SET NULL`, indexed) |
+| `ordering` | autoincrement | Deterministic apply order (indexed) |
+| `action` | text | A `ProductChangeActionType` value |
+| `details` | json | Default `{}`; the operation payload |
+| `internal_note` | text | Nullable |
+| `applied` | boolean | Default `false`; set `true` once written to the product |
+
+## Enums
+
+`ProductChangeStatus`: `pending`, `confirmed`, `declined`, `canceled`.
+
+`ProductChangeActionType`: `UPDATE`, `STATUS_CHANGE`, `VARIANT_ADD`,
+`VARIANT_UPDATE`, `VARIANT_REMOVE`, `ATTRIBUTE_ADD`, `ATTRIBUTE_UPDATE`,
+`ATTRIBUTE_REMOVE`, `PRODUCT_ADD`, `PRODUCT_DELETE`, `CHANGE_REQUESTED`.
+
+Both enums are exported from `@mercurjs/types`.

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

@@ -0,0 +1,47 @@
+---
+title: "Event reference"
+sidebarTitle: "Events"
+description: "Events emitted by the Product Edit domain, for subscribers and side effects."
+---
+
+The Product Edit domain emits events as changes move through the pipeline.
+Subscribe to them to run side effects instead of polling. Use them to notify a
+vendor, sync external systems, or kick off follow-up workflows.
+
+```ts title="src/subscribers/product-change-confirmed.ts"
+import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+
+export default async function productChangeConfirmedHandler({
+  event,
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  const changeId = event.data.id
+  // ...notify the vendor, sync search, etc.
+}
+
+export const config: SubscriberConfig = {
+  event: "product-change.confirmed",
+}
+```
+
+## Change events
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `product-change.created` | A change is staged | `{ id }` |
+| `product-change.confirmed` | A change is confirmed | `{ id }` |
+| `product-change.declined` | A change is declined | `{ id }` |
+| `product-change.canceled` | A change is canceled | `{ id }` |
+
+## Revision events
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `product.change-requested` | An operator requests a revision | `{ id, message, actor_id }` |
+
+<Note>
+  `product.change-requested` carries the **product** id (not a change id) along
+  with the operator's `message` and `actor_id`, because a revision request is
+  recorded against the product's audit trail rather than resolving a pending
+  change.
+</Note>

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

@@ -0,0 +1,39 @@
+---
+title: "Links to other modules"
+sidebarTitle: "Links"
+description: "How the Product Edit domain links to other modules across the marketplace."
+---
+
+Modules in Mercur never reference each other directly. They connect through
+**module links**. Once a link is defined, you retrieve related records with
+`query.graph` using the link alias.
+
+## Product
+
+The Product Edit domain links to the Product module so a product's change
+history hangs off the product itself.
+
+| Linked module | Relationship |
+| --- | --- |
+| **Product** | A product has many changes (`product_change.product_id`, read-only). Exposed as `product.changes`. |
+
+```ts
+const { data: products } = await query.graph({
+  entity: "product",
+  fields: ["id", "title", "changes.status", "changes.actions.action"],
+})
+```
+
+<Note>
+  The link is **read-only** and has no pivot table. The FK lives directly on the
+  `product_change` row. It exists so you read the audit trail through
+  `product.changes`. You can't write a change through the link itself. Stage
+  changes with the [workflows](/platform/product-edit/reference/workflows).
+</Note>
+
+## Actor references
+
+The `created_by`, `confirmed_by`, `declined_by`, and `canceled_by` fields hold
+actor ids (the dashboard user who staged or resolved the change). They are plain
+text references for the audit trail, not module links, so they aren't resolved
+through `query.graph`.

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

@@ -0,0 +1,43 @@
+---
+title: "Service reference"
+sidebarTitle: "Service"
+description: "The Product Edit module service methods for working with records directly."
+---
+
+The Product Edit module exposes a service you can resolve from the Medusa
+container to read and write records directly, without going through a workflow.
+Use it inside custom services, subscribers, or scheduled jobs.
+
+```ts
+import { MercurModules } from "@mercurjs/types"
+
+const productChangeModuleService = container.resolve(MercurModules.PRODUCT_EDIT)
+
+const [changes, count] = await productChangeModuleService.listAndCountProductChanges({
+  status: "pending",
+})
+```
+
+## Generated methods
+
+Each data model gets a standard set of auto-generated methods. For
+`ProductChange`:
+
+| Method | Description |
+| --- | --- |
+| `createProductChanges(data)` | Create one or more changes |
+| `retrieveProductChange(id, config?)` | Retrieve a change by id |
+| `listProductChanges(filters?, config?)` | List changes matching filters |
+| `listAndCountProductChanges(filters?, config?)` | List changes with a total count |
+| `updateProductChanges(data)` | Update one or more changes |
+| `deleteProductChanges(ids)` | Delete one or more changes |
+
+The same set exists for `ProductChangeAction`: `createProductChangeActions`,
+`listProductChangeActions`, `updateProductChangeActions`, and so on.
+
+<Warning>
+  Prefer [workflows](/platform/product-edit/reference/workflows) for anything with
+  side effects (confirming, declining, applying actions). The service writes
+  records directly and does **not** apply actions to the product, emit events, or
+  run compensation.
+</Warning>

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

@@ -0,0 +1,49 @@
+---
+title: "Workflows"
+sidebarTitle: "Workflows"
+description: "Product change workflows, service methods, and events."
+---
+
+This reference lists the workflows for the Product Edit domain. Import them from
+`@mercurjs/core/workflows` and run them against the Medusa container.
+
+## Lifecycle workflows
+
+| Workflow | Input | Purpose |
+| --- | --- | --- |
+| `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 |
+
+## Apply workflows
+
+| Workflow | Input | Purpose |
+| --- | --- | --- |
+| `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 |
+
+## Edit helpers
+
+High-level workflows that diff your input and stage the right actions for you.
+
+| Workflow | Input | Purpose |
+| --- | --- | --- |
+| `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 |
+
+## Audit-trail workflows
+
+| Workflow | Input | Purpose |
+| --- | --- | --- |
+| `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 |
+
+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).

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

@@ -0,0 +1,63 @@
+---
+title: "Product vs seller reviews"
+sidebarTitle: "Product vs seller reviews"
+description: "The reference discriminator and the links that anchor each review."
+---
+
+This page covers how one review model serves two targets and how each review is
+anchored to the rest of the marketplace.
+
+## Reference
+
+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.
+
+```ts
+// A product review
+{ reference: "product", reference_id: "prod_123", rating: 5 }
+
+// A seller review
+{ reference: "seller", reference_id: "sel_123", rating: 4 }
+```
+
+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.
+
+<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.
+</Note>
+
+## Order & customer links
+
+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.
+
+```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" },
+})
+```
+
+## One review per target, per order
+
+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.
+
+<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.
+</Tip>

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

@@ -0,0 +1,64 @@
+---
+title: "Ratings & moderation"
+sidebarTitle: "Ratings & moderation"
+description: "The review status lifecycle, store responses, and aggregate ratings."
+---
+
+This page covers how a review moves from submission to a public rating, and how
+per-product and per-seller averages are computed.
+
+## Status
+
+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   │
+   └────────────┘
+```
+
+| Status | Meaning |
+| --- | --- |
+| `pending` | Submitted, awaiting moderation. The default on creation |
+| `published` | Approved and visible on the storefront |
+| `rejected` | Declined by a moderator |
+
+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).
+
+## Store responses
+
+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.
+
+<Note>
+  Responding is separate from moderation. A store adds its `seller_note`, while
+  the `status` transition (`published` / `rejected`) stays an operator decision.
+</Note>
+
+## Aggregate ratings
+
+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.
+
+```ts
+const service = container.resolve(MercurModules.REVIEW)
+
+const avg = await service.getAvgRating("seller", "sel_123")
+```
+
+<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>

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

@@ -0,0 +1,56 @@
+---
+title: "The review model"
+sidebarTitle: "The review model"
+description: "The single review entity, its rating, notes, and moderation status."
+---
+
+This page covers the review record and the fields that make up a rating.
+
+## Review
+
+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.
+
+```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",
+  },
+})
+```
+
+Every review carries the same shape regardless of what it targets:
+
+| 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>