@mercurjs/docs 2.2.0-canary.40

package/content/learn/payouts.mdx

@@ -0,0 +1,175 @@
+---
+title: "Payout"
+description: "How seller payouts work in Mercur — accounts, onboarding, payment capture, and the transfer pipeline."
+---
+
+The payout module handles the financial side of a marketplace — onboarding sellers to a payment provider, capturing authorized payments, and transferring funds to sellers after fulfillment.
+
+## Payout account
+
+Every seller that wants to receive funds needs a **PayoutAccount**. This account links a seller to an external payment provider (e.g. Stripe Connect).
+
+### Account lifecycle
+
+```
+PENDING → ACTIVE
+           ↓
+        RESTRICTED → ACTIVE (or REJECTED)
+```
+
+| Status | Description |
+|--------|-------------|
+| `PENDING` | Account created, awaiting provider onboarding |
+| `ACTIVE` | Fully onboarded, can receive payouts |
+| `RESTRICTED` | Provider has flagged the account (e.g. missing KYC) |
+| `REJECTED` | Provider rejected the account |
+
+### Onboarding
+
+When a payout account is created, an **Onboarding** record is attached to it. This stores provider-specific data needed for identity verification or account setup (e.g. Stripe Connect onboarding links).
+
+## The payout pipeline
+
+The payout flow is fully automated through two scheduled jobs and event-driven subscribers. No manual intervention is needed after configuration.
+
+### 1. Capture check (every 15 minutes)
+
+A scheduled job scans for orders that are ready for payment capture. For each order, it checks:
+
+- Payment is in `authorized` status
+- Seller has an `ACTIVE` payout account
+- Order meets the required fulfillment status (configurable, default: `fulfilled`)
+- No payout has been created yet
+
+When the capture deadline approaches (authorization window minus safety buffer), the job emits an `order.capture_requested` event. If the authorization has already expired, it emits `order.authorization_expired` instead.
+
+### 2. Payment capture (event-driven)
+
+A subscriber listens for `order.capture_requested` events and runs the Medusa `capturePaymentWorkflow` to capture the authorized payment. On success, the order is marked as captured. On failure, the order is flagged so it won't be retried.
+
+### 3. Daily payouts (once per day)
+
+A daily scheduled job (1 AM UTC) scans for captured orders that haven't been paid out yet. For each eligible order, it emits a `payout.requested` event.
+
+An order qualifies for payout when:
+- Payment has been captured (`metadata.captured = true`)
+- No existing payout transfer
+- Seller has an `ACTIVE` payout account
+
+### 4. Payout transfer (event-driven)
+
+A subscriber listens for `payout.requested` events and runs the `createPayoutWorkflow`:
+
+1. **Fetch order** — Loads the order with its seller, payout account, and commission lines
+2. **Calculate payout amount** — Subtracts commission from the order total:
+   ```
+   payout_amount = order.total - total_commission
+   ```
+3. **Create payout** — Calls the payment provider to initiate the transfer and creates a `Payout` record
+4. **Link payout** — Associates the payout with the seller
+
+### Payout statuses
+
+| Status | Description |
+|--------|-------------|
+| `PENDING` | Payout created, transfer initiated |
+| `PROCESSING` | Provider is processing the transfer |
+| `PAID` | Funds successfully transferred |
+| `FAILED` | Transfer failed |
+| `CANCELED` | Transfer was canceled |
+
+Payout statuses are updated via webhook events from the payment provider.
+
+### Webhook handling
+
+A subscriber listens for `payout.webhook_received` events and delegates to the `processPayoutForWebhookWorkflow`. The provider parses the raw webhook payload and returns an action:
+
+**Account events:**
+- `account.activated` → Status set to `ACTIVE`
+- `account.restricted` → Status set to `RESTRICTED`
+- `account.rejected` → Status set to `REJECTED`
+
+**Payout events:**
+- `payout.processing` → Status set to `PROCESSING`
+- `payout.paid` → Status set to `PAID`
+- `payout.failed` → Status set to `FAILED`
+- `payout.canceled` → Status set to `CANCELED`
+
+## Configuration
+
+The payout module accepts the following options in `medusa-config.ts`:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `disabled` | `false` | Disables both scheduled jobs |
+| `authorizationWindowMs` | 7 days | How long a payment authorization is valid |
+| `sellerActionWindowMs` | 72 hours | Time for seller to fulfill the order |
+| `captureSafetyBufferMs` | 24 hours | Safety margin before authorization expiry to trigger capture |
+| `requiredFulfillmentStatus` | `"fulfilled"` | Minimum fulfillment status before capture is allowed |
+
+## Data model overview
+
+```
+PayoutAccount
+├── Onboarding (one-to-one)
+└── Payout (one-to-many, per-order transfers)
+```
+
+## Configuration example
+
+```typescript
+// medusa-config.ts
+{
+  resolve: "./modules/payout",
+  options: {
+    // How long payment authorizations are valid
+    authorizationWindowMs: 7 * 24 * 60 * 60 * 1000, // 7 days
+
+    // Time for seller to fulfill before capture
+    sellerActionWindowMs: 72 * 60 * 60 * 1000, // 72 hours
+
+    // Safety margin before authorization expiry
+    captureSafetyBufferMs: 24 * 60 * 60 * 1000, // 24 hours
+
+    // Minimum fulfillment status before capture
+    requiredFulfillmentStatus: "fulfilled",
+  },
+}
+```
+
+## API examples
+
+### Get seller's payout account (Vendor API)
+
+```bash
+curl http://localhost:9000/vendor/payout-accounts/<account-id> \
+  -H "Authorization: Bearer <seller-token>"
+```
+
+### Create payout onboarding (Vendor API)
+
+Initiates provider onboarding (e.g. Stripe Connect account setup). The `data` and `context` fields are passed to the payout provider:
+
+```bash
+curl -X POST http://localhost:9000/vendor/payout-accounts/<account-id>/onboarding \
+  -H "Authorization: Bearer <seller-token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "context": {
+      "return_url": "https://my-store.com/settings/payouts"
+    }
+  }'
+```
+
+### List payouts (Admin API)
+
+```bash
+curl http://localhost:9000/admin/payouts \
+  -H "Authorization: Bearer <admin-token>"
+```
+
+## Provider abstraction
+
+The payout module is **provider-agnostic**. A `PayoutProviderService` acts as a bridge to the external payment processor. It delegates all external operations — creating accounts, processing payouts, parsing webhooks — to a pluggable provider implementation.
+
+The module expects exactly one payout provider to be registered. Provider-specific data is stored in the `data` JSON fields on accounts, payouts, and onboarding records.

package/content/learn/product-requests.mdx

@@ -0,0 +1,82 @@
+---
+title: "Product Requests & Approvals"
+description: "How vendor product submissions and edits are reviewed — the ProductChange pipeline that keeps a shared catalog under operator control."
+---
+
+Because the catalog is [shared](/rc/learn/products), vendors don't mutate products directly. New products and edits flow through a review pipeline built on **product changes** — structured requests the operator can confirm, decline, or send back for revision. The same records double as the product's audit trail.
+
+There are two flows:
+
+## 1. New-product approval
+
+A vendor-created product enters the catalog with status `proposed` and is visible only to its creator. The operator reviews it from the Admin Panel:
+
+- **Confirm** — the product is published into the shared catalog.
+- **Reject** — the product is marked `rejected` and stays out of the catalog.
+- **Request changes** — the submission is sent back to the vendor with a note for revision.
+
+## 2. Edit change-requests
+
+Edits to existing products — detail updates, variant additions/updates/removals, attribute changes — are captured as a **ProductChange**: a reviewable bundle of one or more ordered actions.
+
+### ProductChange
+
+| Field | Description |
+|-------|-------------|
+| `product_id` | The product the change targets |
+| `status` | `pending` → `confirmed` / `declined` / `canceled` |
+| `created_by` | Who requested the change |
+| `confirmed_by` / `confirmed_at` | Review outcome audit fields (same pattern for declined/canceled) |
+| `declined_reason` | Why a change was declined |
+| `requires_action_by` / `requires_action_reason` | Set when the operator asks the vendor to revise |
+| `internal_note` / `external_note` | Operator-only vs vendor-visible notes |
+
+### ProductChangeAction
+
+Each change groups ordered **actions** — the atomic operations applied to the live product when the change is confirmed:
+
+| Action | Effect |
+|--------|--------|
+| `UPDATE` | Update product details |
+| `VARIANT_ADD` / `VARIANT_UPDATE` / `VARIANT_REMOVE` | Variant operations |
+| `ATTRIBUTE_ADD` / `ATTRIBUTE_UPDATE` / `ATTRIBUTE_REMOVE` | Attribute operations |
+| `STATUS_CHANGE` | Status transitions (publish, reject) |
+| `PRODUCT_ADD` / `PRODUCT_DELETE` | Creation and deletion markers |
+
+Each action carries its payload in a `details` JSON field and an `applied` flag. Actions are applied in order on confirmation — nothing touches the live product while the change is `pending`.
+
+## Lifecycle
+
+```
+             ┌────────────> confirmed ── actions applied to product
+             │
+pending ─────┼────────────> declined  ── with a reason
+             │
+             └────────────> canceled  ── withdrawn by the requester
+```
+
+The operator can also flag a pending change as **requires action**, handing it back to the vendor with a reason before a final decision.
+
+Some low-risk edits are **auto-confirmed** — they still create a change record for the audit trail, but apply immediately without waiting for review.
+
+## Audit trail
+
+Confirmed changes are never deleted. The product's change history answers "who changed what, when, and who approved it" — including the original creation (`PRODUCT_ADD`), which is also what scopes a vendor's list to their own unpublished submissions.
+
+## Where it appears
+
+| Surface | Capability |
+|---------|-----------|
+| Admin Panel | Review queue on the product detail — confirm, reject, or request changes on submissions and pending edits |
+| Vendor Portal | Shows the seller's own pending edits and revision requests on their product pages |
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Products" href="/rc/learn/products">
+    The master-catalog model this pipeline protects.
+  </Card>
+  <Card title="Product Attributes" href="/rc/learn/attributes">
+    Attribute edits that flow through this pipeline.
+  </Card>
+</CardGroup>

package/content/learn/products.mdx

@@ -0,0 +1,79 @@
+---
+title: "Products"
+description: "Mercur products are master products — a single shared catalog for the whole marketplace, with selling eligibility instead of ownership."
+---
+
+Products in Mercur are **master products**: a single shared catalog of product records that the whole marketplace draws from. A product is **not** owned by the seller who created it — creating a product adds a candidate to the shared catalog, and sellers sell against that catalog through [offers](/rc/learn/offers).
+
+This is the model used by large marketplaces: one canonical product record ("iPhone 15 Pro, 256 GB, Black"), many sellers listing against it.
+
+## No product ownership
+
+There is no owner column on a product. What looks like ownership in other platforms is split into three independent mechanisms:
+
+| Mechanism | What it controls | What it does *not* control |
+|-----------|-----------------|----------------------------|
+| Selling eligibility (`product_seller` link) | Which sellers may sell the product and see it while restricted | Who can edit the product |
+| Creator attribution | Which unpublished products appear in a seller's own list | Any rights over the product after publication |
+| Status lifecycle | Who can see the product at all | Which seller it "belongs" to |
+
+### Selling eligibility
+
+The `product_seller` link is an **allowlist**, analogous to Medusa's `product_sales_channel` link:
+
+- **Restricted** — a product assigned to one or more sellers is visible and sellable only for those sellers.
+- **Unrestricted** — a product with no seller assignments is available to every seller on the marketplace (subject to its status).
+
+Assignments are managed by the operator; creating a product does not assign it to the creator.
+
+### Creator attribution
+
+When a product is created, the platform records who created it as part of the product's [change history](/rc/learn/product-requests). This attribution has exactly one purpose: scoping vendor lists so a seller sees their own not-yet-published submissions without seeing other sellers' pending work.
+
+## Status lifecycle
+
+```
+DRAFT ──> PROPOSED ──> PUBLISHED
+              │
+              └──────> REJECTED
+```
+
+| Status | Meaning |
+|--------|---------|
+| `draft` | Work in progress, not submitted |
+| `proposed` | Submitted for review — visible only to its creator until published |
+| `published` | Live in the shared catalog |
+| `rejected` | Declined by the operator |
+
+Vendor-created products default to **`proposed`**. The operator reviews the submission and publishes or rejects it — see [Product Requests & Approvals](/rc/learn/product-requests).
+
+## Visibility rules
+
+| Surface | What is visible |
+|---------|----------------|
+| Vendor | Products the seller created (any status) plus published products not restricted to other sellers |
+| Admin | Every product, regardless of status or eligibility |
+| Store | Published products of visible sellers |
+
+The vendor rule in practice: a seller's product list is their own submissions **or** the shared published catalog, minus products allowlisted exclusively to other sellers.
+
+## Editing shared products
+
+Because the catalog is shared, edits are collaborative: **any seller may request a change to any product** — updating details, adding or removing variants, changing attributes. Edits flow through the [change-request pipeline](/rc/learn/product-requests) rather than mutating the product directly, so the operator stays in control of the shared record.
+
+Eligibility restrictions limit who may *sell* a product; they do not limit who may *propose changes* to it.
+
+## What sellers actually sell
+
+A master product defines *what the item is*. It carries no seller price and no seller stock. To sell it, a seller creates an **offer** — their own SKU, price, inventory, and shipping profile bound to the product. This separation is what allows many sellers to compete on the same catalog entry.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Offers" href="/rc/learn/offers">
+    How sellers list, price, and stock products from the shared catalog.
+  </Card>
+  <Card title="Product Requests & Approvals" href="/rc/learn/product-requests">
+    How new products and edits are reviewed by the operator.
+  </Card>
+</CardGroup>

package/content/learn/registry.mdx

@@ -0,0 +1,155 @@
+---
+title: "Registry"
+description: "Create, build, and host your own block registry."
+---
+
+A registry is a collection of blocks that can be installed into any Mercur project using the CLI. The official Mercur registry (`@mercurjs`) provides all the built-in marketplace blocks. You can also create and host your own.
+
+## How it works
+
+A registry is a set of JSON files — one per block — served over HTTP. When you run `bunx @mercurjs/cli@rc add`, the CLI fetches the block's JSON, resolves its dependencies, and copies the source files into your project.
+
+```
+registry/
+├── registry.json          # Registry definition with all blocks
+├── src/
+│   └── my-block/          # Block source files
+│       ├── modules/
+│       ├── workflows/
+│       └── api/
+└── r/                     # Built output (generated)
+    ├── registry.json
+    └── my-block.json      # Block JSON with embedded file contents
+```
+
+## registry.json
+
+The `registry.json` file defines your registry and all its blocks:
+
+```json registry.json
+{
+  "$schema": "https://registry.mercurjs.com/registry.json",
+  "name": "@my-org",
+  "homepage": "https://my-org.com",
+  "items": [
+    {
+      "name": "reviews",
+      "description": "Product and seller reviews with ratings.",
+      "dependencies": [],
+      "registryDependencies": [],
+      "docs": "## Configuration\n\nAdd the review module to your `medusa-config.ts`...",
+      "files": [
+        {
+          "path": "reviews/modules/reviews/index.ts",
+          "type": "registry:module"
+        },
+        {
+          "path": "reviews/workflows/review/workflows/create-review.ts",
+          "type": "registry:workflow"
+        },
+        {
+          "path": "reviews/api/store/reviews/route.ts",
+          "type": "registry:api"
+        }
+      ],
+      "categories": ["module", "workflow", "api"]
+    }
+  ]
+}
+```
+
+### Block properties
+
+| Property               | Description                                                    |
+| ---------------------- | -------------------------------------------------------------- |
+| `name`                 | Block identifier used in `bunx @mercurjs/cli@rc add`               |
+| `description`          | Short description shown in search results                      |
+| `dependencies`         | NPM packages to install                                        |
+| `registryDependencies` | Other blocks this block depends on (e.g. `@mercurjs/wishlist`) |
+| `docs`                 | Markdown shown to the user after installation                  |
+| `files`                | List of source files with their paths and types                |
+| `categories`           | Tags for search and filtering                                  |
+
+### File types
+
+Each file in a block has a `type` that determines where it gets placed in the target project:
+
+| Type                | Target alias |
+| ------------------- | ------------ |
+| `registry:module`   | `modules`    |
+| `registry:workflow` | `workflows`  |
+| `registry:api`      | `api`        |
+| `registry:link`     | `links`      |
+| `registry:vendor`   | `vendor`     |
+| `registry:admin`    | `admin`      |
+| `registry:lib`      | `lib`        |
+
+These map to the aliases defined in the consumer's `blocks.json`.
+
+## Building
+
+Build your registry into distributable JSON files:
+
+```bash
+bunx @mercurjs/cli@rc build
+```
+
+This reads `registry.json`, resolves all imports for each block, embeds the file contents, and outputs one JSON file per block to the `r/` directory.
+
+| Option                | Description                       |
+| --------------------- | --------------------------------- |
+| `-o, --output <path>` | Output directory (default: `./r`) |
+| `-v, --verbose`       | Show detailed output              |
+
+The build step also automatically resolves NPM dependencies from your source imports — you don't need to list every transitive dependency manually.
+
+## Hosting
+
+Serve the built `r/` directory over HTTP. Any static hosting works — GitHub Pages, Vercel, Netlify, S3, or your own server. The only requirement is that `{name}.json` files are accessible at a public URL.
+
+## Using custom registries
+
+Add your registry to `blocks.json` in any Mercur project:
+
+```json blocks.json
+{
+  "registries": {
+    "@my-org": "https://my-registry.com/r/{name}.json"
+  }
+}
+```
+
+Use `{name}` as a placeholder for block names. Then install blocks from it:
+
+```bash
+bunx @mercurjs/cli@rc add @my-org/reviews
+```
+
+### Authentication
+
+For private registries, you can use headers with environment variables:
+
+```json blocks.json
+{
+  "registries": {
+    "@my-org": {
+      "url": "https://api.my-org.com/r/{name}.json",
+      "headers": {
+        "Authorization": "Bearer ${REGISTRY_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+## Dependencies between blocks
+
+Blocks can depend on other blocks using `registryDependencies`. When a user installs your block, the CLI automatically resolves and installs all dependencies in the correct order.
+
+```json
+{
+  "name": "order-tracking",
+  "registryDependencies": ["@mercurjs/wishlist"],
+  "files": [...]
+}
+```

package/content/learn/seller-members.mdx

@@ -0,0 +1,62 @@
+---
+title: "Seller Members"
+description: "Multi-user seller accounts — member data, team management, store switching, and access rules."
+---
+
+A **seller member** represents a user who has access to a seller account. Mercur supports **multi-user seller accounts** — multiple people can manage the same store — and **multi-seller users** — a single person can belong to more than one store. This page covers how members relate to sellers, how access is structured, and the rules governing team management.
+
+## Concept
+
+The relationship between users and sellers is **many-to-many**. A seller account can have several members (e.g. an owner, a warehouse manager, and a support agent), and a single user can be a member of multiple seller accounts (e.g. a consultant managing stores for different brands).
+
+Each membership is a distinct association between a user and a seller account.
+
+## Member Data
+
+Each member record holds the following information:
+
+
+| Field    | Description                                                  |
+| -------- | ------------------------------------------------------------ |
+| `email`  | The member's email address, used for login and notifications |
+| `locale` | Preferred language/locale for the vendor portal UI           |
+| `status` | Whether the member is active or deactivated                  |
+
+
+The member's identity is tied to their **email address**. Email addresses must be unique across all members within a single seller account but the same email can appear on different seller accounts.
+
+## Member-Seller Association
+
+When a member is added to a seller account, the association includes:
+
+- A reference to the **seller account**
+- A reference to the **member**
+
+Removing the association revokes the member's access to that seller account entirely.
+
+## Store Switcher
+
+For users who belong to multiple seller accounts, the vendor portal provides a **store switcher**. Each store context is fully isolated — when a member switches stores, they see only the data (products, orders, payouts) belonging to that seller account.
+
+This isolation ensures that access to one store never leaks information from another, even when the same person manages both.
+
+## Adding Members
+
+Members can be added to a seller account by:
+
+- **Operators** — via the admin dashboard, an operator can add members to any seller account
+- **Seller admins** — members with admin access can invite new members to their own seller account
+
+When a new member is added, they receive an invitation to set up their access. If the email already belongs to an existing user in the system, the new seller association is linked to their existing account.
+
+## Removing Members
+
+Removing a member **deletes the association** between the user and the seller account. The user's account continues to exist — they simply lose access to that particular store.
+
+Both **operators** and **seller admins** can remove members, subject to the constraint that a seller account must always retain at least one admin member.
+
+## Business Rules
+
+- A seller account must have **at least one member** with admin access at all times
+- **Email addresses** must be unique within a single seller account
+- Members are managed through the [seller account lifecycle](/rc/learn/sellers) — if a seller is terminated, all member associations are effectively void

package/content/learn/sellers.mdx

@@ -0,0 +1,118 @@
+---
+title: "Seller"
+description: "The central marketplace actor — seller profile, lifecycle, registration flows, and business rules."
+---
+
+A **seller** is the central actor in a Mercur marketplace. Every product listing, order, payout, and storefront presence traces back to a seller account. This page covers the seller data model, lifecycle, and the business rules that govern how sellers operate on the platform.
+
+## Seller Profile
+
+Each seller account holds the following core fields:
+
+
+| Field           | Description                                                                   |
+| --------------- | ----------------------------------------------------------------------------- |
+| `name`          | Display name shown to customers on the storefront (unique)                    |
+| `handle`        | URL-friendly identifier for the seller (unique)                               |
+| `email`         | Primary contact email for the seller account (unique)                         |
+| `description`   | Free-text seller description, typically shown on the seller's storefront page |
+| `logo`          | Seller logo or avatar                                                         |
+| `banner`        | Banner image for the seller's storefront page                                 |
+| `website_url`   | Seller's external website                                                     |
+| `currency_code` | The single currency in which this seller operates                             |
+| `is_premium`    | Operator-designated premium seller flag (see below)                           |
+| `status_reason` | Optional explanation for the current status (e.g. reason for suspension)      |
+| `external_id`   | Identifier in an external system (unique, optional)                           |
+| `metadata`      | Arbitrary JSON metadata                                                       |
+
+
+### Single Currency Per Account
+
+Every seller account is locked to **one currency**. Prices and payouts all use this currency. This constraint keeps financial reporting simple and eliminates exchange-rate ambiguity in payouts.
+
+If a seller needs to trade in multiple currencies, the recommended pattern is to create **separate seller accounts** — one per currency. Each account operates independently with its own products, orders, and payouts.
+
+### Professional Sellers
+
+A seller can optionally have associated **professional details**. If present, the seller is treated as a registered business; if absent, the seller is an individual.
+
+## Address and Payment Information
+
+Sellers can store one or more **addresses** (warehouse, return, business) and **payment details** used for payout processing. These are managed as sub-resources of the seller account and are referenced by workflows such as fulfillment and payout settlement.
+
+## Seller Lifecycle
+
+A seller account moves through **four statuses** over its lifetime:
+
+```
+                ┌──────────────────┐
+                │  pending_approval │
+                └────────┬─────────┘
+                         │ approve
+                         ▼
+  ┌──────────┐      ┌────────┐
+  │ suspended │◄────►│  open  │
+  └──────────┘      └───┬────┘
+                        │ terminate
+                        ▼
+                  ┌────────────┐
+                  │ terminated  │
+                  └────────────┘
+```
+
+### Status Definitions
+
+- **`pending_approval`** — The seller has registered but has not yet been reviewed by the platform operator.
+- **`open`** — The seller is active and may list products, receive orders, and collect payouts.
+- **`suspended`** — The seller's operations are temporarily frozen. Products remain in the catalog but cannot be purchased.
+- **`terminated`** — The seller account is permanently closed. This status is irreversible.
+
+### Status Transition Rules
+
+
+| From               | To           | Who               | Conditions                                                |
+| ------------------ | ------------ | ----------------- | --------------------------------------------------------- |
+| `pending_approval` | `open`       | Operator          | Operator reviews and approves the application             |
+| `open`             | `suspended`  | Operator          | Policy violation, compliance hold, or operator discretion |
+| `suspended`        | `open`       | Operator          | Issue resolved, seller reinstated                         |
+| `open`             | `terminated` | Operator / Seller | All prerequisites met (see below)                         |
+| `suspended`        | `terminated` | Operator          | All prerequisites met (see below)                         |
+
+
+## Scheduled Closures
+
+Sellers can schedule **temporary closures** without changing their account status. Two date fields control this:
+
+- `closed_from` — The date the closure begins
+- `closed_to` — The date the closure ends
+
+During a scheduled closure the seller's storefront shows as unavailable and new orders cannot be placed, but the account remains in `open` status. This is designed for holidays, seasonal breaks, or planned downtime. Once `closed_to` passes, the seller automatically resumes normal operation.
+
+Scheduled closures are **not a status** — they overlay on top of the current status and do not affect status transition rules.
+
+## Premium Sellers
+
+The `is_premium` flag is set **exclusively by the platform operator**. Sellers cannot designate themselves as premium. This flag is used for storefront features such as:
+
+- Featured placement in search results or category pages
+- Visual badges or highlights on the seller's profile
+- Priority in marketplace curation
+
+The specific storefront behavior tied to premium status is determined by the frontend implementation.
+
+## Registration Flows
+
+There are **two methods** for creating a seller account:
+
+1. **Operator-created** — The platform operator creates the seller account directly via the admin dashboard. The account can be set to `open` immediately, bypassing `pending_approval`.
+2. **Self-registration** — The seller registers through the public-facing registration flow. The account enters `pending_approval` status and waits for operator review.
+
+## Business Rules Summary
+
+- A seller account operates in **exactly one currency**
+- The presence of `professional_details` determines whether the seller is a registered business
+- Only the **operator** can approve, suspend, or reinstate sellers
+- **Termination** is irreversible and requires all orders and payouts to be resolved
+- Scheduled closures are **date-driven** and do not change account status
+- **Premium** designation is operator-only and influences storefront presentation
+- Every seller account must have at least one [member](/rc/learn/seller-members) with an admin role