@mercurjs/docs 2.2.0-canary.40

package/content/references/modules/custom-fields.mdx

@@ -0,0 +1,45 @@
+---
+title: "Custom Fields module"
+description: "Add extra columns to any entity without writing a custom module."
+---
+
+The Custom Fields module lets a project attach arbitrary extra fields to existing entities — sellers, products, orders, anything with a joiner alias — without defining a new Medusa module. Fields are declared in configuration; the module generates and manages a `<entity>_custom_fields` table per configured entity and reads/writes it directly.
+
+For the usage guide, see [Custom fields](/rc/resources/customization/custom-fields).
+
+## How it works
+
+- On application start, the module builds a map from joiner aliases (e.g. `seller`, `product`) to entity names for every entity listed in its options.
+- Each configured entity gets a dedicated table named `<entity>_custom_fields` with one column per declared field plus a `<entity>_id` foreign key.
+- Rows are soft-deleted (`deleted_at`).
+
+There are no `model.define` models and no links — the module operates dynamically over its own tables.
+
+## Module options
+
+```ts
+interface CustomFieldsModuleOptions {
+  customFields?: {
+    [entityName: string]: Record<string, Field>
+  }
+}
+```
+
+A `Field` is either a `BaseField` (scalar type) or an `EnumField` (fixed set of values). Both types are exported from the module.
+
+## Service
+
+`CustomFieldsModuleService` is a plain service (not `MedusaService`):
+
+| Method | Behavior |
+| --- | --- |
+| `list(alias, filters?, config?)` | Queries the entity's custom-fields table; supports array filters (`IN`) and field selection |
+| `upsert(alias, data)` | Diffs against existing rows per entity ID, inserts new rows and updates changed ones in a transaction |
+| `delete(alias, ids)` | Soft-deletes the rows for the given entity IDs |
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Custom fields guide" href="/rc/resources/customization/custom-fields" />
+  <Card title="Configuration" href="/rc/references/configuration" />
+</CardGroup>

package/content/references/modules/media.mdx

@@ -0,0 +1,55 @@
+---
+title: "Media module"
+description: "Image records for categories and collections — galleries, thumbnails, banners, and icons."
+---
+
+The Media module owns generic image records attached to marketplace entities through module links. It powers the media galleries on **product categories** and **product collections**, including thumbnail, banner, and icon designations.
+
+The model is deliberately named `MediaImage` (table `media_image`) to avoid colliding with Medusa's product `Image` model.
+
+## Data models
+
+### `MediaImage`
+
+Table `media_image`, ID prefix `medimg`.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `url` | text | |
+| `type` | text | Nullable; `"icon"` for icons, `null` for gallery images |
+| `is_thumbnail` | boolean | Default `false` |
+| `is_banner` | boolean | Default `false` |
+| `rank` | number | Default `0`; gallery ordering |
+| `metadata` | json | Nullable |
+
+Ownership lives in the link table, not on the record — the same module serves any linked entity.
+
+## Links
+
+| Link | Alias | Purpose |
+| --- | --- | --- |
+| `Product.productCategory` ↔ `MediaImage` | `media_images` | Category gallery + icon |
+| `Product.productCollection` ↔ `MediaImage` | `media_images` | Collection gallery + icon |
+
+## Invariants
+
+The service is plain CRUD; the invariants are enforced by the `setCategoryImagesWorkflow` / `setCollectionImagesWorkflow`:
+
+- At most **one thumbnail**, **one banner**, and **one icon** per entity.
+- The same image may be both thumbnail and banner.
+- Setting `icon: null` clears the icon; deleting the entity removes its linked images (no orphans).
+
+Create/update/delete of categories and collections goes through thin wrapper workflows (`createProductCollectionWithImagesWorkflow`, etc.) that combine Medusa's core workflow with the image-set step.
+
+## Related endpoints
+
+- `GET/POST/DELETE /admin/collections[/:id]` — accept `media[]` (with thumbnail/banner designations) and `icon` in the body; responses include the linked `images`.
+- Admin product-category routes accept the same shape.
+- Vendor collection and category routes expose the images read-only.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Workflows" href="/rc/references/workflows" />
+  <Card title="Admin API" href="/rc/references/api/admin" />
+</CardGroup>

package/content/references/modules/offer.mdx

@@ -0,0 +1,64 @@
+---
+title: "Offer module"
+description: "Data models, links, and service methods for the Offer module."
+---
+
+The Offer module owns a seller's **listing** — the binding of a shared product variant to that seller's SKU, shipping profile, price, and inventory. Products in Mercur are master catalog records; the offer is what makes a variant purchasable *from a specific seller*.
+
+## Data models
+
+### `Offer`
+
+Table `offer`, ID prefix `offer`. Unique on (`seller_id`, `sku`).
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `seller_id` | text | The listing seller |
+| `product_id` | text | The master product |
+| `variant_id` | text | The listed variant |
+| `shipping_profile_id` | text | The seller's shipping profile for this offer |
+| `sku` | text | Searchable; unique per seller |
+| `ean` / `upc` | text | Nullable, searchable |
+| `created_by` | text | Actor that created the offer |
+| `variant_count` | number | Computed; only populated in `group_by_seller` mode |
+| `metadata` | json | Nullable |
+
+Indexes exist on `variant_id`, `product_id`, `seller_id`, `shipping_profile_id`, `ean`, and `upc`.
+
+## Links
+
+Prices and inventory attach to the offer through links, not columns:
+
+| Linked entity | Cardinality | Purpose |
+| --- | --- | --- |
+| `Pricing.price` | one offer — many prices | The offer's own price set |
+| `Inventory.inventoryItem` | many-to-many (`offer_inventory_item`, with `required_quantity`, default 1) | The stock backing the offer |
+| `Cart.lineItem` / `Order.orderLineItem` | one offer — many items | Traces cart and order lines back to the offer they were bought from |
+| `Product.product` / `productVariant`, `Seller`, `Fulfillment.shippingProfile` | read-only | Resolved from the `*_id` columns |
+
+<Warning>
+  Offer inventory links to the **offer**, not the variant. For offer-backed
+  order lines, `variant.inventory_items` is empty — always read stock through
+  the offer's inventory link.
+</Warning>
+
+## Service
+
+`OfferModuleService` extends `MedusaService` with auto-generated CRUD, plus a grouped listing mode:
+
+| Method | Behavior |
+| --- | --- |
+| `listOffers(filters, config)` / `listAndCountOffers(...)` | When `filters.group_by_seller` is set, collapses results to one row per (`product_id`, `seller_id`) and computes `variant_count` per group; otherwise standard listing |
+
+## Related endpoints
+
+- `GET /admin/offers`, `POST /admin/offers/batch` — operator visibility and bulk creation
+- `GET/POST /vendor/offers`, `POST /vendor/offers/batch`, `POST /vendor/offers/:id/inventory-items/batch` — seller listing management
+- `GET /store/offers`, `GET /store/offers/:id` — storefront discovery with per-offer calculated prices
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Seller module" href="/rc/references/modules/seller" />
+  <Card title="Search module" href="/rc/references/modules/search" />
+</CardGroup>

package/content/references/modules/payout.mdx

@@ -0,0 +1,121 @@
+---
+title: "Payout module"
+description: "Data models, links, service methods, and the provider interface for the Payout module."
+---
+
+The Payout module owns vendor payout accounts, provider onboarding, and payout records. It delegates account creation, onboarding, and payout execution to a single registered **payout provider** — Stripe Connect ships out of the box — and enforces that payouts only fire for `active` accounts.
+
+For the conceptual introduction, see [Payouts](/rc/learn/payouts).
+
+## Data models
+
+### `PayoutAccount`
+
+Table `payout_account`, ID prefix `pacc`. One per seller (linked via the seller module).
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `status` | enum | `PayoutAccountStatus`, default `pending` |
+| `data` | json | Provider-owned account data |
+| `context` | json | Nullable; creation context passed to the provider |
+
+Relations: `onboarding` (one-to-one), `payouts` (one-to-many).
+
+### `Payout`
+
+Table `payout`, ID prefix `pout`.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `display_id` | autoincrement | Human-readable number |
+| `currency_code` | text | |
+| `amount` | bigNumber | |
+| `status` | enum | `PayoutStatus`, default `pending` |
+| `data` | json | Nullable; provider response data |
+
+### `Onboarding`
+
+Table `onboarding`, ID prefix `onb`. Holds the provider's onboarding state for an account:
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `data` | json | Nullable; e.g. the Stripe onboarding link |
+| `context` | json | Nullable; e.g. return/refresh URLs |
+
+## Enums
+
+```ts
+enum PayoutAccountStatus {
+  PENDING = "pending",
+  ACTIVE = "active",
+  RESTRICTED = "restricted",
+  REJECTED = "rejected",
+}
+
+enum PayoutStatus {
+  PENDING = "pending",
+  PROCESSING = "processing",
+  PAID = "paid",
+  FAILED = "failed",
+  CANCELED = "canceled",
+}
+```
+
+## Links
+
+| Linked entity | Cardinality | Purpose |
+| --- | --- | --- |
+| `Seller` ↔ `PayoutAccount` | one-to-one | A seller's provider account |
+| `Seller` ↔ `Payout` | one seller — many payouts | Settlement history |
+| `Order.order` ↔ `Payout` | one order — many payouts | Traces a payout back to the order it settles |
+
+## Service
+
+`PayoutModuleService` extends `MedusaService` with auto-generated CRUD, plus:
+
+| Method | Behavior |
+| --- | --- |
+| `createPayoutAccount(input)` | Creates the local record, calls the provider with an idempotency key, stores the provider's data and status; deletes the local record if the provider call fails |
+| `createOnboarding(input)` | Calls the provider and upserts the onboarding record for the account |
+| `createPayouts(input)` | Asserts the account is `active`, calls the provider, persists the payout with the provider's data and status |
+| `getWebhookActionAndData(input)` | Resolves an incoming provider webhook into a payout action (consumed by `POST /hooks/payout`) |
+| `getOptions()` | Returns the merged module options |
+
+## Module options
+
+| Option | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `providers` | array | — | Provider registrations (`resolve`, `id`, `options`) |
+| `disabled` | boolean | `false` | Turns payout processing off |
+| `authorizationWindowMs` | number | 7 days | How long a payment authorization is trusted before capture must happen |
+| `sellerActionWindowMs` | number | 72 h | How long the seller has to act (e.g. fulfill) before escalation |
+| `captureSafetyBufferMs` | number | 24 h | Safety margin before the authorization expires |
+| `requiredFulfillmentStatus` | string | `"fulfilled"` | Fulfillment state an order must reach before its payout is generated |
+
+## Provider interface
+
+Exactly one payout provider must be registered (under the `payout_` registration prefix); the module throws at boot otherwise. A provider implements four verbs:
+
+```ts
+interface PayoutProvider {
+  createPayoutAccount(input): Promise<{ data; status }>
+  createOnboarding(input): Promise<{ data }>
+  createPayout(input): Promise<{ data; status }>
+  getWebhookActionAndData(payload): Promise<PayoutWebhookResult>
+}
+```
+
+The Stripe Connect implementation lives in `@mercurjs/payout-stripe-connect` — see [Configuration](/rc/references/configuration#stripe-connect-payout-provider) for its options and [Stripe Connect integration](/rc/resources/integrations/stripe-connect) for the setup guide.
+
+## Related endpoints
+
+- `GET /admin/payouts` — platform-wide payout monitoring
+- `GET /vendor/payouts`, `GET/POST /vendor/payout-accounts`, `POST /vendor/payout-accounts/:id/onboarding` — seller-side account and history
+- `POST /hooks/payout` — provider webhook receiver
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Stripe Connect integration" href="/rc/resources/integrations/stripe-connect" />
+  <Card title="Configuration" href="/rc/references/configuration" />
+</CardGroup>

package/content/references/modules/product-attribute.mdx

@@ -0,0 +1,111 @@
+---
+title: "Product Attribute module"
+description: "Data models, links, and service methods for the Product Attribute module."
+---
+
+The Product Attribute module owns configurable **attributes** and their allowed **values** — the structured properties that describe products (material, color, size, condition, …). Attributes can be global (shared across the catalog) or product-scoped, can be restricted to categories, and — for `multi_select` attributes — can act as **variant axes** backed by Medusa's native global product options.
+
+## Data models
+
+### `ProductAttribute`
+
+Table `product_attribute`, ID prefix `pattr`.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `name` | text | Searchable |
+| `handle` | text | Nullable; unique when set; auto-generated for global attributes |
+| `description` | text | Nullable |
+| `type` | enum | `AttributeType`; immutable after creation |
+| `is_required` | boolean | Default `false` |
+| `is_filterable` | boolean | Default `false`; filterable attributes are tokenized into the search index |
+| `is_variant_axis` | boolean | Default `false`; only valid for `multi_select` |
+| `rank` | number | Default `0`; display ordering |
+| `is_active` | boolean | Default `true` |
+| `product_id` | text | Nullable — `null` means global, set means product-scoped (inline) |
+| `product_option_id` | text | Nullable; mirror to the native `ProductOption` for axis attributes |
+| `created_by` | text | Nullable |
+| `metadata` | json | Nullable |
+
+### `ProductAttributeValue`
+
+Table `product_attribute_value`, ID prefix `pattrval`. Unique on (`attribute_id`, `handle`) when the handle is set.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `name` | text | Display label |
+| `handle` | text | Nullable; auto-generated for global select attributes |
+| `rank` | number | Default `0` |
+| `is_active` | boolean | Default `true` |
+| `product_option_value_id` | text | Nullable; mirror to the native `ProductOptionValue` |
+| `metadata` | json | Nullable |
+
+## Enums
+
+```ts
+enum AttributeType {
+  SINGLE_SELECT = "single_select",
+  MULTI_SELECT = "multi_select",
+  UNIT = "unit",
+  TOGGLE = "toggle",
+  TEXT = "text",
+}
+```
+
+## How each type is stored
+
+| Type | Variant axis? | Backing store |
+| --- | --- | --- |
+| `multi_select` (axis) | yes | Native Medusa `ProductOption` + option values; the product links a subset of values |
+| `multi_select` / `single_select` (non-axis) | no | Product ↔ value link rows |
+| `text` / `unit` | no | A value record is created for the entered text, then linked |
+| `toggle` | no | Two seeded fixed values (`true` / `false`); the matching one is linked |
+
+Only `multi_select` attributes may be variant axes. A global axis maps to a shared (`is_exclusive: false`) product option; an inline, product-scoped axis maps to an exclusive option.
+
+## Links
+
+| Link | Purpose |
+| --- | --- |
+| `product_category_attribute` | Restricts an attribute to categories (many-to-many) |
+| `product_attribute_value_link` | Product ↔ selected values (non-axis selections, and a mirror of axis selections) |
+| `scoped_attributes` (read-only) | Product → its product-scoped attributes via `product_id` |
+| Option mirror (read-only) | `ProductAttribute.product_option_id` → native `ProductOption` |
+| Option-value mirror (read-only) | `ProductAttributeValue.product_option_value_id` → native `ProductOptionValue` |
+
+## Service
+
+`ProductAttributeModuleService` extends `MedusaService` with auto-generated CRUD, plus:
+
+| Method | Behavior |
+| --- | --- |
+| `createProductAttributes(data)` | Auto-generates handles for global attributes; seeds `true`/`false` values for `toggle` attributes |
+| `updateProductAttributes(data)` | Rejects any attempt to change an attribute's `type` |
+| `listProductAttributes` / `listAndCountProductAttributes` | Attach `values` only for select/toggle types; other types return `values: []` |
+| `createProductAttributeValues(data)` | Auto-generates value handles for global select attributes |
+
+## Attaching attributes to products
+
+Attributes are applied to products through the batch endpoint rather than the module service directly:
+
+```
+POST /admin/products/:id/attributes/batch
+POST /vendor/products/:id/attributes/batch
+```
+
+The body is `{ add?, remove?, update? }`, applied in the order remove → add → update by the `createAndLinkProductAttributesToProductWorkflow`. Product create and update payloads also accept a unified `attributes[]` array.
+
+Product GET responses expose the attribute graph as native `options` (variant axes), `product_attribute_values` (each with its parent `attribute` and, for global selects, `all_values`), and `scoped_attributes`.
+
+## Related endpoints
+
+- `GET/POST /admin/product-attributes`, value sub-routes — catalog management
+- `GET /vendor/product-attributes` — category-filtered read access for sellers
+- `GET /store/product-attributes` — storefront filter facets
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Product Edit module" href="/rc/references/modules/product-edit" />
+  <Card title="Search module" href="/rc/references/modules/search" />
+</CardGroup>

package/content/references/modules/product-edit.mdx

@@ -0,0 +1,80 @@
+---
+title: "Product Edit module"
+description: "Data models and lifecycle for product change requests on master products."
+---
+
+The Product Edit module owns the **product change** — the request/approval record through which sellers propose edits to the shared catalog. Products in Mercur are master records that no seller owns; any seller may request a change to any product, and the operator confirms, declines, or lets the platform auto-confirm it.
+
+## The master products model
+
+A `product` row is a shared catalog entry — it has no owner column. Three rules follow:
+
+- **Selling eligibility** is a separate allowlist: the `product_seller` link. One or more rows restrict the product to those sellers; zero rows mean the product is unrestricted.
+- **Creator attribution** lives on the change record (`product_change.created_by` plus a `PRODUCT_ADD` action), and is used only for scoping vendor list views — a seller sees products they created, plus published products not restricted to other sellers.
+- **Edits are requests.** Vendor product update endpoints stage a change instead of writing directly; there is no ownership gate on requesting a change.
+
+## Data models
+
+### `ProductChange`
+
+Table `product_change`, ID prefix `prodch`.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `product_id` | text | Target product |
+| `status` | enum | `ProductChangeStatus`, default `pending` |
+| `created_by` | text | Nullable; requesting actor |
+| `internal_note` / `external_note` | text | Nullable |
+| `confirmed_by` / `confirmed_at` | text / dateTime | Nullable; audit trail |
+| `declined_by` / `declined_at` / `declined_reason` | text / dateTime / text | Nullable |
+| `canceled_by` / `canceled_at` | text / dateTime | Nullable |
+| `requires_action_by` / `requires_action_at` / `requires_action_reason` | text / dateTime / text | Nullable; "changes requested" state |
+| `metadata` | json | Nullable |
+
+Relations: `actions` (one-to-many, deleted with the change).
+
+### `ProductChangeAction`
+
+Table `product_change_action`, ID prefix `prodchact`. The ordered operations a change applies:
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `product_id` | text | |
+| `ordering` | autoincrement | Apply order |
+| `action` | text | Operation type (e.g. `PRODUCT_ADD`, update, variant, attribute operations) |
+| `details` | json | Default `{}`; the operation payload |
+| `applied` | boolean | Default `false` |
+| `internal_note` | text | Nullable |
+
+## Enums
+
+```ts
+enum ProductChangeStatus {
+  PENDING = "pending",
+  CONFIRMED = "confirmed",
+  DECLINED = "declined",
+  CANCELED = "canceled",
+}
+```
+
+## Links
+
+| Link | Purpose |
+| --- | --- |
+| `changes` (read-only) | Product → its change records via `product_id` |
+
+## Service
+
+`ProductChangeModuleService` extends `MedusaService` with auto-generated CRUD only — the lifecycle logic lives in workflows: `createProductChangeWorkflow`, `stageProductChangeWorkflow`, `confirmProductChangeWorkflow`, `autoConfirmProductChangeWorkflow`, `cancelProductChangeWorkflow`, `rejectProductChangeWorkflow`, and the `applyProductChangeActionsWorkflow` family that replays the staged actions onto the product. See [Workflows](/rc/references/workflows#product-edit).
+
+## Related endpoints
+
+- Vendor: `POST /vendor/products/:id` and variant/attribute sub-routes stage changes; `GET /vendor/products/:id/preview` shows the product with pending changes applied; `POST /vendor/products/:id/cancel` withdraws a request.
+- Admin: `GET /admin/products/:id/preview`, `POST /admin/products/:id/confirm`, `POST /admin/products/:id/reject`, `POST /admin/products/:id/request-changes`, plus `POST /admin/product-changes/:id/confirm` and `/cancel`.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Product Attribute module" href="/rc/references/modules/product-attribute" />
+  <Card title="Offer module" href="/rc/references/modules/offer" />
+</CardGroup>

package/content/references/modules/search.mdx

@@ -0,0 +1,112 @@
+---
+title: "Search module"
+description: "The provider-agnostic search module, its document shapes, and the provider contract."
+---
+
+The Search module is a **provider abstraction**: it owns no data models and wraps exactly one registered search provider behind three verbs — `index`, `remove`, `search`. Mercur ships a default in-process provider built on [Orama](https://oramasearch.com) that requires zero external infrastructure; operators can swap in Algolia, Meilisearch, or anything else by implementing the same contract.
+
+Both **products** (master catalog entries) and **offers** (per-seller listings with offer-scoped prices) are indexed.
+
+## Document shape
+
+```ts
+interface SearchDoc {
+  id: string
+  type: "product" | "offer"
+  title: string
+  description?: string
+  handle: string
+  thumbnail?: string
+  seller_handle?: string          // offers only
+  collection_id?: string
+  collection?: string
+  category_ids?: string[]
+  categories?: string[]
+  product_id?: string             // offers
+  variant_id?: string             // offers
+  sku?: string                    // offers
+  attribute_tokens: string[]      // facetable: "attr:<handle>:<value_id>"
+  attributes: Record<string, string> // stored label map
+  prices: Record<string, SearchDocPrice> // keyed by region_id, stored not indexed
+}
+```
+
+Prices are **stored, not searched**: each document carries a per-region price map (`calculated_amount`, `original_amount`, `currency_code`), and the provider projects `calculated_price` for the requested region at query time. Suspended sellers' offers and unpublished products are excluded at index time. Attributes flagged `is_filterable` are tokenized into `attribute_tokens` for faceting.
+
+## Query and results
+
+```ts
+interface SearchQueryBase {
+  q?: string
+  limit?: number
+  offset?: number
+  context?: Record<string, unknown>  // pricing/display context, not a filter
+  filters?: Record<string, unknown>  // provider-owned shape
+}
+
+interface SearchResults {
+  hits: SearchDoc[]
+  count: number
+  facets: { collections; categories; attributes } // pre-labelled by the provider
+}
+```
+
+`filters` is an open passthrough — each provider defines its own filter shape. The built-in Orama provider accepts:
+
+```ts
+filters?: {
+  type?: "product" | "offer"
+  collection_ids?: string[]
+  category_ids?: string[]
+  seller_handle?: string
+  attributes?: Record<string, string[]> // attribute handle -> selected value ids
+}
+```
+
+## Service
+
+`SearchModuleService` exposes:
+
+| Method | Behavior |
+| --- | --- |
+| `index(docs)` | Upserts documents into the provider index |
+| `remove(ids)` | Removes documents by ID |
+| `search(query)` | Runs a query against the provider |
+| `getProviderIdentifier()` | Returns the active provider's identifier |
+
+## Provider contract
+
+Implement `AbstractSearchProvider` (exported from the module) and register it via the module's `provider` option. Exactly one provider must be registered — the module throws at boot otherwise. If no provider is configured, the Orama provider registers automatically.
+
+```ts
+abstract class AbstractSearchProvider<TQuery extends SearchQueryBase> {
+  static identifier: string
+  abstract index(docs: SearchDoc[]): Promise<void>
+  abstract remove(ids: string[]): Promise<void>
+  abstract search(query: TQuery): Promise<SearchResults>
+}
+```
+
+<Warning>
+  The built-in Orama provider holds its index **in process memory**. It starts
+  empty, is rebuilt on boot via the reindex event, and does not share state
+  across processes. For multi-instance deployments, use an external provider.
+</Warning>
+
+## Index synchronization
+
+Sync is event-driven — there are no search workflows:
+
+- Subscribers react to product, offer, and seller changes (`search-product-changed`, `search-product-deleted`, `search-offer-changed`, `search-seller-changed`) and reindex or remove the affected documents.
+- A full rebuild runs when the `search.reindex` event (`SEARCH_REINDEX_EVENT`) is emitted; in worker mode the module emits it automatically on application start.
+
+## Related endpoints
+
+`POST /store/search` — the storefront query route. Body: `q`, `limit` (default 12, max 100), `offset`, `region_id` / `country_code` / `province` (pricing context), and the provider-owned `filters`. Responds with `{ hits, count, limit, offset, facets }`. Customer authentication is optional.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Search integrations" href="/rc/resources/integrations/search" />
+  <Card title="Store API" href="/rc/references/api/store" />
+</CardGroup>