@mercurjs/docs 2.2.1 → 2.3.0-canary.1

package/content/resources/integrations/search.mdx

@@ -1,122 +0,0 @@
----
-title: "Search"
-description: "Mercur's provider-agnostic search module — zero-infrastructure Orama by default, swappable for Algolia, Meilisearch, or your own provider."
----
-
-Mercur ships a **Search module** in `@mercurjs/core`, modeled on Medusa's pluggable-provider pattern (like the `file` and `notification` modules). The module owns a stable contract — `index`, `remove`, `search` — and delegates storage to exactly one active **provider**. Out of the box that provider is [Orama](https://docs.orama.com): an in-process, in-memory index that needs zero external infrastructure.
-
-<Warning>
-  The search module is a release-candidate feature and its surface may still evolve before the stable release.
-</Warning>
-
-<Info>
-  **Everything above the provider is provider-agnostic.** Subscribers index and remove documents on product, offer, and seller events; the store route calls `search.search(query)`; boot reindexing is event-driven. Swapping Orama for Algolia or Meilisearch means changing one provider registration — no changes to subscribers, the store route, or your storefront.
-</Info>
-
-## What gets indexed
-
-Products **and offers** are searchable. Offers are indexed as **per-offer documents** — one hit per vendor listing — each carrying the offer's scoped price, so search results price identically to `GET /store/offers`. Index updates are driven by subscribers on product, offer, and seller events; you never call `index()` from application code.
-
-## Searching from the storefront
-
-The Store API exposes one endpoint:
-
-```bash
-curl -X POST "http://localhost:9000/store/search" \
-  -H "x-publishable-api-key: <key>" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "q": "t-shirt",
-    "limit": 12,
-    "offset": 0,
-    "region_id": "reg_123"
-  }'
-```
-
-| Field | Description |
-|-------|-------------|
-| `q` | Search query (defaults to `""` — browse mode) |
-| `limit` / `offset` | Pagination (limit 1–100, default 12) |
-| `region_id`, `country_code`, `province` | Pricing context — the provider projects the matching price onto each hit's `calculated_price` |
-| `filters` | Passed straight to the active provider, which owns its shape |
-
-The response returns `hits`, `count`, and `facets`.
-
-## The default provider: Orama
-
-The bundled `search-orama` provider keeps the index in RAM inside the API process. That means:
-
-- **Zero setup** — no accounts, keys, or services. Search works on a fresh project.
-- **Boot reindex** — an in-memory index is empty after a restart, so the module emits a reindex event on application start and a subscriber rebuilds the index from the database.
-
-<Note>
-  In-memory search fits development and small-to-medium catalogs. For large catalogs or multi-instance deployments, use a persistent provider — the index then lives in the external service and the boot reindex is unnecessary.
-</Note>
-
-## Swapping in Algolia or Meilisearch
-
-Ready-made provider integrations ship as blocks:
-
-```bash
-bunx @mercurjs/cli@latest add algolia
-# or
-bunx @mercurjs/cli@latest add meilisearch
-```
-
-| Provider | Hosting | Best for |
-|----------|---------|----------|
-| Orama (default) | In-process | Zero-infra development and smaller catalogs |
-| Algolia | Managed SaaS | Fastest setup, hosted relevance tuning |
-| Meilisearch | Self-hosted or cloud | Full control, open source |
-
-Each block installs the provider source and prints the configuration steps (API keys, module options). Follow the block's post-install docs to register the provider and set environment variables.
-
-## Writing your own provider
-
-A provider extends `AbstractSearchProvider` from `@mercurjs/core` and implements three methods:
-
-```typescript
-import { AbstractSearchProvider } from "@mercurjs/core/modules/search"
-import { SearchDoc, SearchQueryBase, SearchResults } from "@mercurjs/types"
-
-export class MySearchProvider extends AbstractSearchProvider {
-  static identifier = "my-search"
-
-  async index(docs: SearchDoc[]): Promise<void> { /* upsert documents */ }
-  async remove(ids: string[]): Promise<void> { /* delete by id */ }
-  async search(query: SearchQueryBase): Promise<SearchResults> { /* query + facets */ }
-}
-```
-
-Because subscribers and the store route only talk to the module contract, your provider slots in without touching anything else. Use the Algolia or Meilisearch block source as a working reference.
-
-## Verify
-
-1. Start a fresh project and `POST /store/search` with an empty `q` — published products return without any search service configured (that's Orama).
-2. Publish a product and search for its title — it appears without a manual reindex (subscribers indexed it).
-3. Restart the API and search again — results still return (the boot reindex rebuilt the in-memory index).
-
-## FAQ
-
-<AccordionGroup>
-  <Accordion title="Can I run two providers at once, e.g. Orama locally and Algolia in production?">
-    Only one provider is active at a time — the module has no multi-provider machinery. But because the provider is chosen by configuration, you can register different providers per environment (default Orama in development, Algolia in production) without touching any other code.
-  </Accordion>
-  <Accordion title="Do I ever need to trigger a reindex manually?">
-    Normally no — subscribers keep the index current, and in-memory providers rebuild on boot. A manual full reindex is only interesting after bulk data changes outside normal flows (e.g. direct DB imports); persistent providers ignore the boot event entirely.
-  </Accordion>
-  <Accordion title="Why does each offer appear as its own search hit?">
-    Because pricing and availability are per offer, not per product. One hit per vendor listing lets results carry the correct `calculated_price` for each seller — the same numbers as `GET /store/offers` — instead of an ambiguous product-level price.
-  </Accordion>
-</AccordionGroup>
-
-## Next steps
-
-<CardGroup cols={2}>
-  <Card title="Offers" href="/rc/learn/offers">
-    Why offers are indexed per seller with scoped prices.
-  </Card>
-  <Card title="Add a feature with a block" href="/rc/resources/tutorials/add-a-block">
-    How provider blocks are installed and configured.
-  </Card>
-</CardGroup>

package/content/resources/tutorials/configure-commissions.mdx

@@ -1,127 +0,0 @@
----
-title: "Configure commissions"
-description: "Set the global commission, add scoped rules for categories and sellers, and confirm the right rate lands on an order."
----
-
-Commissions are how your marketplace earns. Mercur matches a **commission rate** to every order line item through rules, with one **global commission** as the catch-all. In this tutorial you'll set up a realistic three-tier configuration and verify which rate wins on a real order.
-
-<Info>
-  **The most specific rate wins.** Rules combine with AND across dimensions and OR within a dimension, and among matching rates the one scoping the most dimensions applies. You never order rates by priority — specificity is the priority. The full algorithm is in [Commission](/rc/learn/commissions).
-</Info>
-
-## What you'll build
-
-- A global commission of 15% that also commissions shipping.
-- A 12% rate for the Electronics category.
-- An 8% rate for Electronics sold by one specific premium seller.
-
-An electronics order from the premium seller should produce commission lines at 8% — not 12%, not 15%.
-
-## Set up the rates
-
-<Steps>
-  <Step title="Set the global commission">
-    Every marketplace needs exactly one default rate — the fallback when nothing more specific matches. Create it with `is_default`:
-
-    ```bash
-    curl -X POST http://localhost:9000/admin/commission-rates \
-      -H "Authorization: Bearer <admin-token>" \
-      -H "Content-Type: application/json" \
-      -d '{
-        "name": "Global Commission",
-        "code": "global",
-        "type": "percentage",
-        "value": 15,
-        "is_default": true,
-        "include_shipping": true
-      }'
-    ```
-
-    <Note>
-      `include_shipping` only has an effect on the global commission — shipping methods are always commissioned from the global rate, never from scoped rates. In the Admin Panel this lives on the Global Commission card under **Settings → Commissions**.
-    </Note>
-  </Step>
-  <Step title="Add a category-scoped rate">
-    A rate becomes scoped by attaching **rules**. Each rule names a dimension (`reference`) and a value (`reference_id`):
-
-    ```bash
-    curl -X POST http://localhost:9000/admin/commission-rates \
-      -H "Authorization: Bearer <admin-token>" \
-      -H "Content-Type: application/json" \
-      -d '{
-        "name": "Electronics Commission",
-        "code": "electronics",
-        "type": "percentage",
-        "value": 12,
-        "rules": [
-          { "reference": "product_category", "reference_id": "pcat_electronics" }
-        ]
-      }'
-    ```
-
-    Available dimensions: `product`, `product_type`, `product_collection`, `product_category`, and `seller`.
-  </Step>
-  <Step title="Add a two-dimension rate for the premium seller">
-    Combining a `seller` rule with a `product_category` rule means *both* must match — this rate applies only to that seller's electronics:
-
-    ```bash
-    curl -X POST http://localhost:9000/admin/commission-rates \
-      -H "Authorization: Bearer <admin-token>" \
-      -H "Content-Type: application/json" \
-      -d '{
-        "name": "Premium seller electronics",
-        "code": "premium-electronics",
-        "type": "percentage",
-        "value": 8,
-        "rules": [
-          { "reference": "seller", "reference_id": "slr_premium" },
-          { "reference": "product_category", "reference_id": "pcat_electronics" }
-        ]
-      }'
-    ```
-
-    Because it scopes two dimensions, it beats the one-dimension Electronics rate whenever both match — regardless of which rate was created first.
-  </Step>
-  <Step title="Place a test order">
-    Commission lines are calculated when an order is placed — rates are never applied retroactively. Place an order containing an electronics item from the premium seller (via your storefront or the Store API), then inspect the order's commission lines.
-  </Step>
-</Steps>
-
-## Verify
-
-1. List the rates and confirm all three exist and are enabled:
-   ```bash
-   curl http://localhost:9000/admin/commission-rates \
-     -H "Authorization: Bearer <admin-token>"
-   ```
-2. On the placed order, each electronics line item from the premium seller has a commission line with `code: "premium-electronics"` and `rate: 8`.
-3. The order's shipping method has a commission line from the **global** rate (because `include_shipping` is on).
-4. Change a rate now and confirm the existing order's commission lines are untouched — `CommissionLine` records are a permanent audit trail.
-
-## FAQ
-
-<AccordionGroup>
-  <Accordion title="How do I charge a flat fee instead of a percentage?">
-    Use `"type": "fixed"` with per-currency `values`: `[{ "currency_code": "usd", "amount": 2 }, { "currency_code": "eur", "amount": 1.8 }]`. The scalar `value` is the fallback for currencies without an entry.
-  </Accordion>
-  <Accordion title="What happens when two rates tie on specificity?">
-    Ties break deterministically to the **oldest rate**. But if you find yourself relying on tie-breaking, prefer making one rate more specific — it reads better in the Admin Panel and survives audits.
-  </Accordion>
-  <Accordion title="Do rate changes affect existing orders?">
-    No. Commission is snapshotted into `CommissionLine` records at order placement. Changing or disabling a rate only affects future orders — the lines on past orders are a permanent audit trail that payouts read from.
-  </Accordion>
-  <Accordion title="Can a rate match multiple values in one dimension?">
-    Yes — rules within the same dimension are OR'd. A rate with two `product_category` rules matches items in either category, and still counts as one dimension for specificity.
-  </Accordion>
-</AccordionGroup>
-
-## Next steps
-
-<CardGroup cols={2}>
-  <Card title="Commission" href="/rc/learn/commissions">
-    The full matching algorithm, calculation pipeline, and data model.
-  </Card>
-  <Card title="Set up seller payouts" href="/rc/resources/tutorials/seller-payouts-stripe">
-    Where commission is deducted — the settlement side of the marketplace.
-  </Card>
-</CardGroup>

package/content/resources/tutorials/first-marketplace.mdx

@@ -1,45 +0,0 @@
----
-title: "Build your first marketplace"
-description: "Go end-to-end: create a project, approve a seller, list a product, place a split order, and watch a payout settle."
----
-
-<Note>
-  This tutorial is being written. The outline below is the intended structure.
-</Note>
-
-<Info>
-  **One order, three perspectives.** The same purchase looks different on every surface: the customer sees one checkout, the operator sees an order group with per-seller child orders, and each seller sees only their slice. Keeping those three views straight is the core mental model of a Mercur marketplace — this tutorial walks all three.
-</Info>
-
-## What you'll build
-
-A working marketplace with one approved seller, one product, and one split order that settles into a payout. Prerequisites listed up front.
-
-<Steps>
-  <Step title="Create the project">
-    Condensed link back to [Installation](/rc/learn/installation).
-  </Step>
-  <Step title="Approve a seller">
-    From the Admin Panel.
-  </Step>
-  <Step title="List a product">
-    From the Vendor Panel.
-  </Step>
-  <Step title="Place a split order">
-    From the storefront or Store API.
-  </Step>
-  <Step title="See the payout">
-    From the Vendor Panel.
-  </Step>
-</Steps>
-
-## Verify
-
-A checklist of what "done" looks like — the observable end state to confirm every step worked.
-
-## Next steps
-
-<CardGroup cols={2}>
-  <Card title="Add a feature with a block" href="/rc/resources/tutorials/add-a-block" />
-  <Card title="Configure commissions" href="/rc/resources/tutorials/configure-commissions" />
-</CardGroup>

package/content/resources/tutorials/handle-product-requests.mdx

@@ -1,80 +0,0 @@
----
-title: "Handle product requests"
-description: "Walk a vendor's product submission and a follow-up edit through the operator review pipeline — confirm, decline, or send back."
----
-
-Because Mercur's catalog is [shared](/rc/learn/products), vendors never mutate products directly. New products and edits arrive as **product changes** — reviewable requests the operator confirms, declines, or sends back for revision. This tutorial plays both roles: the vendor submitting, and the operator reviewing.
-
-<Info>
-  **Nothing touches the live product while a change is pending.** A `ProductChange` bundles ordered actions (`UPDATE`, `VARIANT_ADD`, `ATTRIBUTE_UPDATE`, …) that are applied only on confirmation. Declining or canceling leaves the product exactly as it was — and confirmed changes are never deleted, so the same records double as the product's audit trail.
-</Info>
-
-## What you'll build
-
-One complete review cycle: a vendor submits a new product, the operator requests a revision, the vendor resubmits, the operator publishes. Then a smaller edit request on the now-live product.
-
-## Review outcomes
-
-The review queue on the admin product detail offers three outcomes:
-
-| Action | Effect |
-|--------|--------|
-| **Confirm** | The product is published into the shared catalog |
-| **Reject** | Status becomes `rejected`; the product stays out of the catalog |
-| **Request changes** | The submission returns to the vendor with a reason (`requires_action_by` / `requires_action_reason`) |
-
-## Run the review cycle
-
-<Steps>
-  <Step title="Submit a product as the vendor">
-    In the Vendor Portal, create a product. Vendor-created products enter the catalog with status **`proposed`** — visible only to their creator, not to other sellers or the storefront.
-
-    Behind the scenes the platform records a `ProductChange` with a `PRODUCT_ADD` action and `created_by` set to the submitting member. That attribution is what keeps the seller's unpublished submissions in their own product list.
-  </Step>
-  <Step title="Request changes as the operator">
-    In the Admin Panel, open the product and choose **Request changes** with a note — say, "add product dimensions". Use the external note for the vendor-visible message; internal notes stay operator-only.
-  </Step>
-  <Step title="Revise and resubmit as the vendor">
-    Back in the Vendor Portal, the product page shows the revision request and the operator's note. The vendor updates the product and resubmits. As the operator, **Confirm** this time — the product's status flips to `published` and it enters the shared catalog for every eligible seller.
-  </Step>
-  <Step title="Request an edit on the live product">
-    Now that the product is published, edits also flow through review. As the vendor, change the product's description. This creates a new `ProductChange` in `pending` with an `UPDATE` action — the live product is unchanged until the operator confirms. Confirm it and watch the description update.
-  </Step>
-</Steps>
-
-<Note>
-  Any seller may propose changes to any published product — the shared catalog is collaborative. Selling-eligibility restrictions limit who may *sell* a product, not who may *suggest improvements* to it.
-</Note>
-
-## Verify
-
-1. After step 1, the product is `proposed`: visible in the submitting vendor's list, absent from other vendors' lists and the Store API.
-2. After **Request changes**, the vendor sees the revision note; the change is flagged `requires action`.
-3. After the final **Confirm** in step 3, the product is `published` and appears in the Store API.
-4. During step 4, the storefront still shows the old description while the change is `pending` — and the new one after confirmation.
-5. The product's change history lists every change with who requested it, who reviewed it, and when.
-
-## FAQ
-
-<AccordionGroup>
-  <Accordion title="Do all edits require operator review?">
-    No — some low-risk edits are **auto-confirmed**: they still create a change record for the audit trail but apply immediately without waiting. Structural changes (variants, attributes, status) go through review.
-  </Accordion>
-  <Accordion title="Can the vendor withdraw a pending request?">
-    Yes — a pending change can be **canceled** by its requester, recorded with the same audit fields (`canceled_by`, timestamp). Once confirmed or declined, the outcome is final; a new change is needed for further edits.
-  </Accordion>
-  <Accordion title="What's the difference between rejecting and requesting changes?">
-    **Reject** is terminal for a submission — the product is marked `rejected` and stays out of the catalog. **Request changes** keeps the change alive and hands it back to the vendor with a reason; it's the "revise and resubmit" path.
-  </Accordion>
-</AccordionGroup>
-
-## Next steps
-
-<CardGroup cols={2}>
-  <Card title="Product Requests & Approvals" href="/rc/learn/product-requests">
-    The full ProductChange data model, actions, and lifecycle.
-  </Card>
-  <Card title="Master products & offers" href="/rc/resources/tutorials/master-products-and-offers">
-    What happens after publication — sellers listing against the shared record.
-  </Card>
-</CardGroup>

package/content/resources/tutorials/import-export-products.mdx

@@ -1,96 +0,0 @@
----
-title: "Import and export products via CSV"
-description: "Install the product-import-export block and give vendors CSV import and export drawers on their product list."
----
-
-Bulk catalog operations belong to vendors, not the operator — a seller migrating from another platform needs to bring hundreds of listings with them. The `product-import-export` block adds CSV import and export to the Vendor Portal: API routes, workflows built on Medusa's product CSV steps, and drawer UIs wired into the product list.
-
-<Info>
-  **This block is also a masterclass in Mercur's extension model.** It ships backend workflows and routes into your API package, and it adds Import/Export actions to the vendor products area through the panel extension surface. After installing, read its source; you own every file.
-</Info>
-
-## What you'll build
-
-A vendor product list with **Import** and **Export** header buttons, a working CSV round-trip, and the block's source code in your project.
-
-## Install and wire the block
-
-<Steps>
-  <Step title="Install the block">
-    ```bash
-    bunx @mercurjs/cli@latest add product-import-export
-    ```
-
-    The CLI copies the block's files into the directories mapped by your `blocks.json` aliases — workflows and routes into the API package, pages and hooks into the vendor app.
-  </Step>
-  <Step title="Install its dependencies">
-    The block uses Medusa's CSV flows and `multer` for uploads. Install them in the **API workspace**, not the project root:
-
-    ```bash
-    cd packages/api
-    bun add @medusajs/core-flows multer @types/multer
-    ```
-  </Step>
-  <Step title="Register the middleware">
-    The import route needs its upload middleware. Add it to your API's `middlewares.ts`:
-
-    ```typescript packages/api/src/api/middlewares.ts
-    import { defineMiddlewares } from '@medusajs/medusa'
-    import { productImportExportMiddlewares } from './vendor/products/middlewares'
-
-    export default defineMiddlewares({
-      routes: [...productImportExportMiddlewares],
-    })
-    ```
-  </Step>
-  <Step title="Regenerate types">
-    The block added `POST /vendor/products/import` and `GET /vendor/products/export`. Regenerate the route map so the vendor app's typed client knows about them:
-
-    ```bash
-    bunx @mercurjs/cli@latest codegen
-    ```
-
-    <Note>
-      No new modules and no migrations — the block reuses Medusa's built-in product CSV steps, so there's nothing to add to `medusa-config.ts` for this one. Always read a block's post-install output: each block declares its own setup steps.
-    </Note>
-  </Step>
-  <Step title="Run a round-trip">
-    Start the project and open the Vendor Portal's **Products** page — the header now shows Import and Export next to Create.
-
-    1. **Export** — opens the drawer at `/products/export` and downloads the seller's current products as CSV.
-    2. Edit the CSV: tweak a title, add a row.
-    3. **Import** — the drawer at `/products/import` accepts the file, validates rows, and shows an import summary before applying.
-  </Step>
-</Steps>
-
-## Verify
-
-1. The Products header shows Import and Export buttons; the rest of the page (search, filters, pagination) behaves exactly as before.
-2. The exported CSV contains the seller's products — and only theirs; the workflow scopes to the authenticated seller.
-3. After importing the edited CSV, the changed title appears in the product list.
-4. The block's source lives in your repo (e.g. `packages/api/src/workflows/import-seller-products.ts`, `apps/vendor/src/routes/products/page.tsx`) — run `bunx @mercurjs/cli@latest diff product-import-export` to compare against the registry later.
-
-## FAQ
-
-<AccordionGroup>
-  <Accordion title="Can I customize the CSV columns or validation?">
-    Yes — the block is source code in your repo. The import workflow (`import-seller-products.ts`) and its validation step are yours to edit; the drawer UI under `routes/products/import/` includes the CSV template helper you can extend.
-  </Accordion>
-  <Accordion title="I already customized my /products page — will the block overwrite it?">
-    The block ships its own `routes/products/page.tsx`. If you already have one, the CLI asks before overwriting (or use `--overwrite` explicitly). Merge by hand in that case: keep your composition and add the block's Import/Export buttons to your `HeaderActions`.
-  </Accordion>
-  <Accordion title="Does import respect the product approval flow?">
-    Imported products enter through the same vendor create path as manual submissions — so they follow the [product-request pipeline](/rc/resources/tutorials/handle-product-requests) and land as `proposed` for operator review, not as instantly published records.
-  </Accordion>
-</AccordionGroup>
-
-## Next steps
-
-<CardGroup cols={2}>
-  <Card title="Add a widget" href="/rc/resources/tutorials/add-a-widget">
-    Inject a component at a built-in zone with `defineWidgetConfig`.
-  </Card>
-  <Card title="Build your own block" href="/rc/resources/tutorials/build-a-block">
-    Package a feature like this one and publish it to your own registry.
-  </Card>
-</CardGroup>

package/content/resources/tutorials/seller-payouts-stripe.mdx

@@ -1,89 +0,0 @@
----
-title: "Set up seller payouts"
-description: "Take a seller from zero to paid: Stripe Connect onboarding, an order through fulfillment, capture, and the automated payout."
----
-
-Payouts are the last mile of a marketplace — the marketplace collects the customer's payment, deducts its commission, and transfers the remainder to the seller. In Mercur that pipeline is **fully automated**: once a seller is onboarded and an order is fulfilled, scheduled jobs and subscribers handle capture and transfer without any manual step. This tutorial follows one order through the entire pipeline.
-
-<Info>
-  **Nothing pays out until the seller's account is `ACTIVE`.** Every stage of the pipeline checks the payout account status. A seller who skips onboarding can sell, but their orders sit uncaptured until the authorization window forces the issue — which is exactly why surfacing onboarding status in the vendor portal matters.
-</Info>
-
-## What you'll build
-
-A working payout loop: a seller with an active Stripe Connect account, one fulfilled order, a captured payment, and a payout record that settles via webhook.
-
-## Prerequisites
-
-Stripe Connect must be configured first — provider registration, API keys, and **both** webhooks (payment and payout). Follow the [Stripe Connect integration guide](/rc/resources/integrations/stripe-connect) up to and including "Set up webhooks", then come back here. For local development, keep `stripe listen` forwarding running.
-
-## Run the pipeline
-
-<Steps>
-  <Step title="Onboard the seller">
-    In the Vendor Portal, the seller opens **Settings → Payouts** and starts onboarding. Under the hood this creates a `PayoutAccount` (status `PENDING`) and an `Onboarding` record holding the Stripe onboarding link:
-
-    ```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": "http://localhost:7001/settings/payouts" } }'
-    ```
-
-    The seller completes Stripe's hosted flow (identity, bank account) — in test mode, Stripe's test data completes it in a minute. When Stripe activates the account, the payout webhook delivers an `account.activated` event and Mercur flips the account to `ACTIVE`. No polling — the webhook is the source of truth.
-  </Step>
-  <Step title="Place and fulfill an order">
-    Place an order for one of the seller's listings, then in the Vendor Portal fulfill it. Fulfillment matters: by default, capture requires the order to reach `fulfilled` status (configurable via the payout module's `requiredFulfillmentStatus` option).
-  </Step>
-  <Step title="Watch the capture">
-    A scheduled job runs every 15 minutes looking for orders that are ready: payment `authorized`, seller `ACTIVE`, fulfillment status met, no payout yet. When the capture deadline approaches it emits `order.capture_requested`, and a subscriber captures the payment.
-
-    To move faster while testing, wait for the next 15-minute tick after fulfillment.
-
-    <Warning>
-      Payment authorizations expire — 7 days by default (`authorizationWindowMs`). Sellers who don't fulfill within the window (`sellerActionWindowMs`, 72h default) risk the capture buffer kicking in or the authorization expiring entirely. Tune these in the payout module options with your fulfillment SLAs in mind.
-    </Warning>
-  </Step>
-  <Step title="The payout lands">
-    Once per day (1 AM UTC) a job scans captured orders without payouts and emits `payout.requested` per order. The `createPayoutWorkflow` then:
-
-    1. Loads the order with its commission lines.
-    2. Calculates `payout_amount = order.total − total_commission`.
-    3. Calls Stripe to create the transfer and records a `Payout` (status `PENDING`).
-
-    Stripe's webhook then walks the payout through `PROCESSING` → `PAID` (or `FAILED`).
-  </Step>
-</Steps>
-
-## Verify
-
-1. **Account**: `GET /vendor/payout-accounts/<id>` returns `status: "ACTIVE"` after onboarding.
-2. **Capture**: after fulfillment plus one job tick, the order's payment shows as captured.
-3. **Payout**: `GET /admin/payouts` lists a payout for the order, with `amount` equal to the order total minus the commission lines from your [commission configuration](/rc/resources/tutorials/configure-commissions).
-4. **Vendor view**: the seller sees the payout and its status in the Vendor Portal's payout history.
-5. **Stripe**: the transfer appears on the connected account in the Stripe test dashboard.
-
-## FAQ
-
-<AccordionGroup>
-  <Accordion title="What if the seller never completes onboarding?">
-    Their orders stay uncaptured. The capture job skips orders whose seller isn't `ACTIVE`, and once the authorization window lapses the payment expires (an `order.authorization_expired` event fires). Surface the onboarding status prominently and chase incomplete sellers early.
-  </Accordion>
-  <Accordion title="Why hasn't a payout appeared even though the order is captured?">
-    The payout job runs once per day at 1 AM UTC — a captured order waits for the next daily tick. Also check that no payout already exists for the order and that the seller's account is still `ACTIVE` (a `RESTRICTED` account pauses payouts until the provider clears it).
-  </Accordion>
-  <Accordion title="What do the payout statuses mean?">
-    `PENDING` — transfer initiated; `PROCESSING` — the provider is moving funds; `PAID` — settled; `FAILED` / `CANCELED` — the transfer didn't complete. All transitions after `PENDING` come from provider webhook events, so a stuck status usually means the payout webhook isn't reaching your API.
-  </Accordion>
-</AccordionGroup>
-
-## Next steps
-
-<CardGroup cols={2}>
-  <Card title="Payout" href="/rc/learn/payouts">
-    The full pipeline reference — statuses, jobs, webhook events, module options.
-  </Card>
-  <Card title="Stripe Connect" href="/rc/resources/integrations/stripe-connect">
-    Provider configuration, transfers vs payouts, refunds, and EU considerations.
-  </Card>
-</CardGroup>