@mercurjs/docs 2.2.1 → 2.3.0-canary.1

package/content/platform/payout/guides/start-provider-onboarding.mdx

@@ -0,0 +1,50 @@
+---
+title: "Start provider onboarding"
+sidebarTitle: "Start onboarding"
+description: "Kick off provider onboarding with createOnboardingWorkflow."
+---
+
+In this guide, you'll learn how to start provider onboarding for a payout
+account from server code. Onboarding is what moves an account from `PENDING`
+toward `ACTIVE`. For Stripe Connect, it produces the hosted link the seller uses
+to submit their details.
+
+## Run the workflow
+
+`createOnboardingWorkflow` asks the provider to produce onboarding data and
+stores it as an `Onboarding` record on the account.
+
+```ts title="src/api/custom/onboarding/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { createOnboardingWorkflow } from "@mercurjs/core/workflows"
+
+export async function POST(req: MedusaRequest, res: MedusaResponse) {
+  const { result } = await createOnboardingWorkflow(req.scope).run({
+    input: {
+      account_id: req.params.id,
+      context: {
+        return_url: "https://store.example.com/settings/payouts",
+      },
+    },
+  })
+
+  res.status(201).json({ onboarding: result })
+}
+```
+
+The provider-specific payload (for Stripe Connect, the onboarding URL) is stored
+in the record's `data` field for you to return to the seller.
+
+<Tip>
+  Running the workflow again on an account that already has an onboarding record
+  **updates** it in place instead of creating a second one. It is safe to call
+  whenever a seller needs a fresh link.
+</Tip>
+
+## Reaching `ACTIVE`
+
+Onboarding kicks off the flow, but the account only becomes `ACTIVE` when the
+provider confirms it via webhook. Handle that step in
+[Process a webhook](/platform/payout/guides/process-a-provider-webhook), and see
+[Account lifecycle](/platform/payout/concepts/account-lifecycle) for the full
+state model.

package/content/platform/payout/overview.mdx

@@ -0,0 +1,86 @@
+---
+title: "Payout"
+sidebarTitle: "Overview"
+description: "Onboard sellers to a payment provider and settle their earnings automatically."
+---
+
+Use Mercur to control how each seller is onboarded and settled, while the
+payment provider handles KYC.
+
+Settlement you control is the Payout domain. Once an order is placed and
+fulfilled, it splits each seller's share out to their own connected account, so
+funds are settled per seller rather than pooled. The seller's share is the order
+total minus commission. Onboarding is provider-driven, with the payment provider
+carrying KYC, and the domain ships with a pluggable provider interface and a
+**Stripe Connect** implementation out of the box. It also runs a fully automated
+capture-and-transfer pipeline driven by scheduled jobs and provider webhooks.
+
+<Note>
+  **Provider-agnostic.** The module talks to exactly one registered payout
+  provider through a single interface. Stripe Connect ships by default; any
+  other processor is a drop-in implementation of the same `IPayoutProvider`
+  contract.
+</Note>
+
+## Key features
+
+- **Pluggable provider interface:** one `IPayoutProvider` contract, with Stripe Connect included.
+- **Payout accounts and onboarding:** a per-seller account plus a provider onboarding record.
+- **Webhook-driven lifecycle:** account status (`PENDING` → `ACTIVE` ↔ `RESTRICTED` / `REJECTED`) tracks the provider.
+- **Automated pipeline:** a capture-check job, payment capture, a daily payout job, and transfer, with no manual steps.
+- **Commission-aware transfers:** each payout is the order total minus its commission lines.
+- **Tunable timing:** authorization window, seller-action window, capture buffer, and required fulfillment status.
+
+## Get started
+
+Learn how the domain fits together.
+
+<CardGroup cols={2}>
+  <Card title="Accounts & onboarding" icon="id-card" href="/platform/payout/concepts/accounts-and-onboarding">
+    The payout account, its onboarding record, and provider data.
+  </Card>
+  <Card title="Account lifecycle" icon="arrows-rotate" href="/platform/payout/concepts/account-lifecycle">
+    Statuses and the webhook-driven transitions between them.
+  </Card>
+  <Card title="The payout pipeline" icon="arrows-turn-right" href="/platform/payout/concepts/payout-pipeline">
+    Capture check, capture, daily payout, transfer, and the provider interface.
+  </Card>
+</CardGroup>
+
+## Examples
+
+Build against the Payout domain in your own code.
+
+<CardGroup cols={2}>
+  <Card title="Create a payout account" icon="plus" href="/platform/payout/guides/create-a-payout-account">
+    Run `createPayoutAccountWorkflow` for a seller.
+  </Card>
+  <Card title="Start onboarding" icon="link" href="/platform/payout/guides/start-provider-onboarding">
+    Kick off provider onboarding with `createOnboardingWorkflow`.
+  </Card>
+  <Card title="Process a webhook" icon="bell" href="/platform/payout/guides/process-a-provider-webhook">
+    Turn a provider webhook into account and payout status updates.
+  </Card>
+</CardGroup>
+
+## Resources
+
+Data models, workflows, service methods, and events for the Payout domain.
+
+<CardGroup cols={2}>
+  <Card title="Data models" icon="table" href="/platform/payout/reference/data-models">
+    The `PayoutAccount`, `Onboarding`, and `Payout` entities.
+  </Card>
+  <Card title="Links" icon="link" href="/platform/payout/reference/links">
+    How the Payout domain links to sellers and orders.
+  </Card>
+  <Card title="Workflows" icon="diagram-project" href="/platform/payout/reference/workflows">
+    Account, onboarding, payout, and webhook workflows.
+  </Card>
+  <Card title="Service" icon="gear" href="/platform/payout/reference/service">
+    Module service methods for working with records directly.
+  </Card>
+  <Card title="Events" icon="bell" href="/platform/payout/reference/events">
+    Events that drive the payout pipeline.
+  </Card>
+</CardGroup>

package/content/platform/payout/reference/data-models.mdx

@@ -0,0 +1,61 @@
+---
+title: "Data models"
+sidebarTitle: "Data models"
+description: "The data models owned by the Payout domain."
+---
+
+The Payout domain is owned by the **Payout module**. This reference lists its
+data models and their fields. For the full module overview, see the
+[Payout overview](/platform/payout/overview).
+
+## PayoutAccount
+
+Table `payout_account`, id prefix `pacc`. A seller's connection to the payment
+provider. This is the record funds are transferred to.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `id` | text | Primary key |
+| `status` | enum | `PayoutAccountStatus`, default `pending` |
+| `data` | json | Provider-specific account data |
+| `context` | json | Nullable; per-request provider hints |
+
+Relations: `onboarding` (one-to-one, nullable), `payouts` (one-to-many).
+
+## Onboarding
+
+Table `onboarding`, id prefix `onb`. Provider setup state for a payout account
+(for Stripe Connect, the onboarding link).
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `id` | text | Primary key |
+| `data` | json | Nullable; provider onboarding data |
+| `context` | json | Nullable; per-request provider hints |
+| `account_id` | text | Belongs to a `PayoutAccount` |
+
+<Note>
+  `Onboarding` is one-to-one with `PayoutAccount`. Re-running the onboarding
+  workflow updates the existing record rather than creating a second one.
+</Note>
+
+## Payout
+
+Table `payout`, id prefix `pout`. A single transfer of a seller's earnings for
+one order.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `id` | text | Primary key |
+| `display_id` | number | Auto-incrementing, human-readable |
+| `currency_code` | text | The payout's currency |
+| `amount` | bigNumber | Order total minus commission |
+| `data` | json | Nullable; provider transfer data |
+| `status` | enum | `PayoutStatus`, default `pending` |
+| `account_id` | text | Belongs to a `PayoutAccount` |
+
+## Enums
+
+**`PayoutAccountStatus`:** `pending`, `active`, `restricted`, `rejected`.
+
+**`PayoutStatus`:** `pending`, `processing`, `paid`, `failed`, `canceled`.

package/content/platform/payout/reference/events.mdx

@@ -0,0 +1,48 @@
+---
+title: "Event reference"
+sidebarTitle: "Events"
+description: "Events that drive the payout pipeline, for subscribers and side effects."
+---
+
+The Payout domain is event-driven. Scheduled jobs emit events, and subscribers
+react to them to capture payments and transfer funds. Subscribe to these events
+to run your own side effects, such as notifications, ledger syncing, or follow-up
+workflows, instead of polling.
+
+```ts title="src/subscribers/payout-requested.ts"
+import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+
+export default async function payoutRequestedHandler({
+  event,
+  container,
+}: SubscriberArgs<{ order_id: string }>) {
+  const orderId = event.data.order_id
+  // ...notify the seller, write to an external ledger, etc.
+}
+
+export const config: SubscriberConfig = {
+  event: "payout.requested",
+}
+```
+
+## Pipeline events
+
+| Event | Emitted when | Handled by |
+| --- | --- | --- |
+| `order.capture_requested` | Capture check finds an order ready to capture | The payment-capture subscriber runs `capturePaymentWorkflow` |
+| `order.authorization_expired` | Capture check finds an authorization that already expired | Order is flagged so it isn't retried |
+| `payout.requested` | Daily job finds a captured order not yet paid out | The transfer subscriber runs `createPayoutWorkflow` |
+
+## Webhook events
+
+| Event | Emitted when | Handled by |
+| --- | --- | --- |
+| `payout.webhook_received` | A provider webhook arrives | The `payout-webhook` subscriber runs `processPayoutForWebhookWorkflow` |
+
+<Note>
+  `order.capture_requested`, `order.authorization_expired`, and
+  `payout.requested` are defined on the `PayoutEvents` enum in `@mercurjs/types`.
+  The webhook subscriber resolves `payout.webhook_received` to a provider action
+  before updating status. See
+  [Account lifecycle](/platform/payout/concepts/account-lifecycle).
+</Note>

package/content/platform/payout/reference/links.mdx

@@ -0,0 +1,36 @@
+---
+title: "Links to other modules"
+sidebarTitle: "Links"
+description: "How the Payout domain links to sellers and orders across the marketplace."
+---
+
+Modules in Mercur never reference each other directly. They connect through
+**module links**. The Payout module links to the Seller and Order modules. Once a
+link is defined, you retrieve related records with `query.graph` using the link
+alias.
+
+```ts
+const { data: sellers } = await query.graph({
+  entity: "seller",
+  fields: ["id", "name", "payout_account.*", "payouts.*"],
+})
+```
+
+## Sellers
+
+| Linked module | Relationship |
+| --- | --- |
+| **Seller** (account) | A store has **one** payout account (`seller` ↔ `payout_account`). |
+| **Seller** (payouts) | A store has **many** payouts (`seller` ↔ `payout`, list). |
+
+## Orders
+
+| Linked module | Relationship |
+| --- | --- |
+| **Order** | An order has **many** payouts (`order` ↔ `payout`, list). |
+
+<Note>
+  A payout is linked to both the order it settles and the seller it pays. The
+  account link is one-to-one, while the seller-payouts and order-payouts links
+  are lists.
+</Note>

package/content/platform/payout/reference/service.mdx

@@ -0,0 +1,53 @@
+---
+title: "Service reference"
+sidebarTitle: "Service"
+description: "The Payout module service: methods for working with records directly."
+---
+
+The Payout 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 payoutModuleService = container.resolve(MercurModules.PAYOUT)
+
+const [payouts, count] = await payoutModuleService.listAndCountPayouts({
+  status: "paid",
+})
+```
+
+## Generated methods
+
+Each data model gets a standard set of auto-generated methods. For `Payout`:
+
+| Method | Description |
+| --- | --- |
+| `retrievePayout(id, config?)` | Retrieve a payout by id |
+| `listPayouts(filters?, config?)` | List payouts matching filters |
+| `listAndCountPayouts(filters?, config?)` | List payouts with a total count |
+| `updatePayouts(data)` | Update one or more payouts |
+| `deletePayouts(ids)` | Delete one or more payouts |
+
+The same set exists for `PayoutAccount` and `Onboarding` (e.g.
+`retrievePayoutAccount`, `listPayoutAccounts`, `updateOnboardings`).
+
+## Provider-integrated methods
+
+These overrides call the configured provider as part of the operation. Prefer
+them over the raw generated creates.
+
+| Method | Description |
+| --- | --- |
+| `createPayoutAccount(input)` | Create the account and the provider's connected account |
+| `createOnboarding(input)` | Create or update onboarding via the provider |
+| `createPayouts(input)` | Initiate a transfer through the provider (account must be `ACTIVE`) |
+| `getWebhookActionAndData(input)` | Ask the provider to parse a raw webhook payload |
+| `getOptions()` | Read the module's configured options (with defaults applied) |
+
+<Warning>
+  Prefer [workflows](/platform/payout/reference/workflows) for anything that
+  touches the provider or links records. The generated `updatePayouts` /
+  `updatePayoutAccounts` write status directly and do **not** call the provider.
+</Warning>

package/content/platform/payout/reference/workflows.mdx

@@ -0,0 +1,32 @@
+---
+title: "Workflows"
+sidebarTitle: "Workflows"
+description: "Payout account, onboarding, payout, and webhook workflows."
+---
+
+This reference lists the workflows for the Payout domain. Import them from
+`@mercurjs/core/workflows` and run them against the Medusa container.
+
+## Account & onboarding workflows
+
+| Workflow | Input | Purpose |
+| --- | --- | --- |
+| `createPayoutAccountWorkflow` | `{ seller_id, data?, context? }` | Create a payout account, call the provider, link it to the store |
+| `createOnboardingWorkflow` | `{ account_id, data?, context? }` | Create or update the account's onboarding record via the provider |
+
+## Payout workflows
+
+| Workflow | Input | Purpose |
+| --- | --- | --- |
+| `createPayoutWorkflow` | `{ order_id }` | Compute the seller's share (total − commission) and initiate a transfer |
+| `processPayoutForWebhookWorkflow` | `PayoutWebhookResult` | Apply a provider webhook to account or payout status |
+
+<Note>
+  `createPayoutWorkflow` reads the order with its seller, payout account, and
+  commission lines, then uses the order id as the transfer's idempotency key so
+  a re-run never double-pays.
+</Note>
+
+To work with records directly instead of through a workflow, see the
+[Service reference](/platform/payout/reference/service). For the events that
+drive these workflows, see the [Event reference](/platform/payout/reference/events).

package/content/platform/product-edit/concepts/change-actions.mdx

@@ -0,0 +1,66 @@
+---
+title: "Change actions"
+sidebarTitle: "Change actions"
+description: "The typed actions that make up a change and the details they carry."
+---
+
+In this document, you'll learn how the individual operations inside a change are
+modeled.
+
+## Product change action
+
+Each operation inside a change is a `ProductChangeAction` (table
+`product_change_action`, id prefix `prodchact`). An action belongs to a parent
+`ProductChange`, targets a `product_id`, and names the operation in its `action`
+field. The operation's payload lives in the `details` JSON, and an `applied`
+boolean records whether it has already been written to the product.
+
+```ts
+const action = {
+  product_id: "prod_123",
+  action: "UPDATE",
+  details: { field: "title", value: "New title" },
+}
+```
+
+Actions carry an autoincrementing `ordering` so a change with several operations
+applies them deterministically.
+
+## Action types
+
+The `action` field is one of the `ProductChangeActionType` values. Each type
+reads a different shape out of `details`:
+
+| Action | `details` shape | Applies |
+| --- | --- | --- |
+| `UPDATE` | `{ field, value }` | A single product field update |
+| `STATUS_CHANGE` | `{ status }` | A product status change |
+| `VARIANT_ADD` | `{ variant }` | Create a variant |
+| `VARIANT_UPDATE` | `{ variant_id, fields }` | Update a variant (scalars + image links) |
+| `VARIANT_REMOVE` | `{ variant_id }` | Delete a variant |
+| `ATTRIBUTE_ADD` | `{ attribute }` | Attach a product attribute |
+| `ATTRIBUTE_UPDATE` | `{ update }` | Change an attached attribute |
+| `ATTRIBUTE_REMOVE` | `{ attribute_id }` | Detach an attribute |
+| `PRODUCT_ADD` | None | Record a product creation in the trail |
+| `PRODUCT_DELETE` | None | Delete the product |
+| `CHANGE_REQUESTED` | `{ message }` | Record an operator revision request |
+
+<Note>
+  `CHANGE_REQUESTED` mutates nothing. It's an audit-only marker for a revision
+  request. The operator's message rides on both the action's `details.message`
+  and the parent change's `external_note`. See
+  [Status & auto-confirm](/platform/product-edit/concepts/status-and-auto-confirm).
+</Note>
+
+## How actions apply
+
+When a change is confirmed, its **not-yet-applied** actions are bucketed by type
+and dispatched to the matching Medusa workflows in one pass: product updates,
+variant creates/updates/deletes, and the attribute batch. Each action is then
+flipped to `applied: true` so a re-run never applies it twice.
+
+<Tip>
+  Audit-trail changes (publish approvals, revision requests) are stored with
+  their actions already `applied`, so confirming them is a no-op on the product
+  itself. They exist purely as history.
+</Tip>

package/content/platform/product-edit/concepts/change-pipeline.mdx

@@ -0,0 +1,69 @@
+---
+title: "The change pipeline"
+sidebarTitle: "The change pipeline"
+description: "The ProductChange record, its immutability, and the audit trail."
+---
+
+In this document, you'll learn how a product edit is captured and why the
+pipeline is built on immutable records.
+
+## Product change
+
+A product change is a single reviewable edit to one product, represented by the
+`ProductChange` data model (table `product_change`, id prefix `prodch`). It
+references the target product through `product_id`, carries the `status` of the
+review, and records who created and resolved it (`created_by`, `confirmed_by`,
+`declined_by`, `canceled_by`) with matching timestamps.
+
+```ts
+const productChangeModuleService = container.resolve(MercurModules.PRODUCT_EDIT)
+
+const change = await productChangeModuleService.retrieveProductChange(id, {
+  relations: ["actions"],
+})
+```
+
+A change owns one or more `ProductChangeAction` records (`actions`). The change
+is the reviewable unit; the actions are the individual operations it will apply.
+See [Change actions](/platform/product-edit/concepts/change-actions).
+
+<Note>
+  A product can have **only one active (pending) change at a time**. Staging a
+  new change while one is still pending is rejected. The vendor resolves or
+  cancels the open change first.
+</Note>
+
+## Immutability & the audit trail
+
+A change is never rewritten in place. It is created, its actions are appended,
+and it is resolved by moving `status` forward and stamping the actor and time.
+Because nothing is overwritten, the set of `ProductChange` rows on a product is a
+durable history of who changed what and who approved it.
+
+Some events aren't vendor edits at all, such as a publish approval or a revision
+request. They still belong in the history. Those are recorded as changes created
+already `confirmed`, so the audit trail captures them without waiting on review.
+
+```ts
+await recordProductAuditChangeWorkflow(container).run({
+  input: {
+    actor_id: "user_123",
+    changes: [
+      {
+        product_id: "prod_123",
+        external_note: "Approved for publish",
+        actions: [
+          { product_id: "prod_123", action: "STATUS_CHANGE", details: { status: "published" } },
+        ],
+      },
+    ],
+  },
+})
+```
+
+<Tip>
+  Read a product's full history through the read-only `product.changes` link
+  (see the [Links reference](/platform/product-edit/reference/links)) rather than
+  querying the module directly. The link keeps the audit trail attached to the
+  product.
+</Tip>

package/content/platform/product-edit/concepts/status-and-auto-confirm.mdx

@@ -0,0 +1,66 @@
+---
+title: "Status & auto-confirm"
+sidebarTitle: "Status & auto-confirm"
+description: "The change status lifecycle, revision requests, and auto-confirm."
+---
+
+In this document, you'll learn about the states a change moves through and when
+it resolves without operator review.
+
+## Status
+
+A change's state is held in the `status` field of the `ProductChange` model,
+typed by the `ProductChangeStatus` enum. A change moves through four statuses:
+
+```
+                ┌───────────┐
+                │  pending   │
+                └─────┬─────┘
+          ┌───────────┼───────────┐
+    confirm          decline     cancel
+          ▼           ▼           ▼
+   ┌───────────┐ ┌──────────┐ ┌──────────┐
+   │ confirmed │ │ declined │ │ canceled │
+   └───────────┘ └──────────┘ └──────────┘
+```
+
+| Status | Meaning |
+| --- | --- |
+| `pending` | Awaiting operator review. The default for a staged edit |
+| `confirmed` | Approved; its actions are applied to the product |
+| `declined` | Rejected by the operator; nothing is applied |
+| `canceled` | Withdrawn (e.g. by the vendor) before review |
+
+<Note>
+  Only a `pending` change can be confirmed, declined, or canceled. The
+  resolution workflows validate the current status first, so a change is
+  resolved exactly once.
+</Note>
+
+## Revision requests
+
+When an operator wants a submission reworked rather than approved or rejected,
+they **request a revision**. This is recorded as a `CHANGE_REQUESTED` audit
+action (a `confirmed` audit change) carrying the operator's message, and it emits
+`product.change-requested`. The product stays with the vendor to revise and
+resubmit. A revision request is a signal in the audit trail, not a fourth
+resolution of the pending change.
+
+## Auto-confirm
+
+Staging a change runs `autoConfirmProductChangeWorkflow`. Whether it confirms
+immediately depends on the marketplace's review setting:
+
+- **Review off:** the change is confirmed and applied in the same run, so
+  low-friction edits don't wait for an operator.
+- **Review on:** the change stays `pending` for an operator to resolve.
+
+You can also force auto-confirm for a specific change (for example a
+trusted-source import) via the `auto_confirm` flag on the staging workflow,
+regardless of the review setting.
+
+<Tip>
+  Auto-confirm reuses the exact same `confirmProductChangeWorkflow` as a manual
+  approval, so an auto-confirmed change is applied and audited identically to one
+  an operator approves by hand.
+</Tip>

package/content/platform/product-edit/guides/confirm-or-decline-a-change.mdx

@@ -0,0 +1,76 @@
+---
+title: "Confirm or decline a change"
+sidebarTitle: "Confirm or decline"
+description: "Resolve a pending product change from server code."
+---
+
+In this guide, you'll learn how to resolve a pending change from your own server
+code. Each resolution has a dedicated workflow so the side effects (applying
+actions, events, compensation) run consistently.
+
+## Confirm a change
+
+`confirmProductChangeWorkflow` marks the changes `confirmed`, applies their
+pending actions to the product, and emits `product-change.confirmed`.
+
+```ts title="src/api/custom/confirm/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { confirmProductChangeWorkflow } from "@mercurjs/core/workflows"
+
+export async function POST(req: MedusaRequest, res: MedusaResponse) {
+  await confirmProductChangeWorkflow(req.scope).run({
+    input: {
+      ids: [req.params.id],
+      confirmed_by: req.auth_context?.actor_id,
+    },
+  })
+
+  res.sendStatus(200)
+}
+```
+
+<Note>
+  Confirmation only applies actions that aren't already `applied`, so re-running
+  it never writes the same edit twice.
+</Note>
+
+## Decline a change
+
+`rejectProductChangeWorkflow` moves a `pending` change to `declined` without
+touching the product, and emits `product-change.declined`.
+
+```ts
+import { rejectProductChangeWorkflow } from "@mercurjs/core/workflows"
+
+await rejectProductChangeWorkflow(container).run({
+  input: {
+    id: "prodch_123",
+    declined_by: "user_123",
+    declined_reason: "Images don't meet guidelines",
+  },
+})
+```
+
+## Cancel a change
+
+When the change should be withdrawn rather than judged (for example the vendor
+retracting their own submission), use `cancelProductChangeWorkflow`:
+
+```ts
+import { cancelProductChangeWorkflow } from "@mercurjs/core/workflows"
+
+await cancelProductChangeWorkflow(container).run({
+  input: { id: "prodch_123", canceled_by: "user_123" },
+})
+```
+
+<Warning>
+  Confirm, decline, and cancel all require the change to be `pending`. Resolving
+  an already-resolved change fails validation. A change is resolved exactly once.
+</Warning>
+
+## React to resolutions
+
+To run your own side effects when a change resolves, subscribe to the events
+these workflows emit rather than polling. See the
+[Event reference](/platform/product-edit/reference/events).