@mercurjs/docs 2.3.8-canary.2 → 2.3.8-canary.4

package/content/platform/order-group/reference/service.mdx

@@ -1,50 +1,74 @@
 ---
-title: "Service reference"
+title: "Order group service methods"
 sidebarTitle: "Service"
-description: "The Seller module service and its methods for working with order group records directly."
+description: "Seller module service methods for OrderGroup records, the filters they accept, and how they compute totals."
 ---
 
-Order groups are owned by the **Seller module**, so you resolve the same service
-you'd use for stores. Resolve it from the Medusa container to read and write
-`OrderGroup` records directly, without going through a workflow. Use it inside
-custom services, subscribers, or scheduled jobs.
+Order group records live in the Seller module, so you read and write them through the Seller module service. Use it in subscribers, scheduled jobs, and custom steps when you need group rows without child orders. For child orders and their statuses, use the [read workflows](/platform/order-group/reference/workflows) instead.
+
+## Resolve the service
+
+Resolve the Seller module from the Medusa container with `MercurModules.SELLER`. There is no `ORDER_GROUP` module key.
 
 ```ts
 import { MercurModules } from "@mercurjs/types"
 
 const sellerModuleService = container.resolve(MercurModules.SELLER)
 
-const [orderGroups, count] = await sellerModuleService.listAndCountOrderGroups({
-  customer_id: "cus_123",
-})
+const [groups, count] = await sellerModuleService.listAndCountOrderGroups(
+  { customer_id: "cus_01JD8Q1234567" },
+  { take: 20 }
+)
 ```
 
-<Note>
-  There is no `ORDER_GROUP` module key. The `OrderGroup` model is registered on
-  the Seller module, so its service methods live on `MercurModules.SELLER`.
-</Note>
+The call returns the customer’s 20 newest groups and the total number of groups that match.
 
-## Generated methods
+## Read methods
 
-The `OrderGroup` model gets the standard set of auto-generated methods:
+The Seller module overrides the generated read methods for `OrderGroup`. All three run one SQL query through `OrderGroupRepository`, which fills `seller_count` and `total`:
 
-| Method | Description |
+| Method | Returns |
 | --- | --- |
-| `createOrderGroups(data)` | Create one or more order groups |
-| `retrieveOrderGroup(id, config?)` | Retrieve a group by id (with computed `seller_count` / `total`) |
-| `listOrderGroups(filters?, config?)` | List groups matching filters |
-| `listAndCountOrderGroups(filters?, config?)` | List groups with a total count |
-| `updateOrderGroups(data)` | Update one or more groups |
-| `deleteOrderGroups(ids)` | Delete one or more groups |
-
-The list, count, and retrieve methods run through the module's order-group
-repository, which aggregates each group's child orders to fill in the computed
-`seller_count` and `total`. Supported filters include `id`, `customer_id`,
-`seller_id`, `status`, `sales_channel_id`, `created_at`, `updated_at`, and `q`.
+| `listOrderGroups(filters?, config?, sharedContext?)` | `Promise<OrderGroupDTO[]>` |
+| `listAndCountOrderGroups(filters?, config?, sharedContext?)` | `Promise<[OrderGroupDTO[], number]>` |
+| `retrieveOrderGroup(id, config?, sharedContext?)` | `Promise<OrderGroupDTO>` |
+
+From `config`, the repository reads `take`, `skip`, and `order` only. It ignores `select` and `relations` and always returns every column plus the two computed fields.
 
 <Warning>
-  Prefer [workflows](/platform/order-group/reference/workflows) for reads that
-  need aggregated child-order status, and for the checkout split. The service
-  returns the group row and its computed totals but does **not** expand child
-  orders' payment/fulfillment status, emit events, or run compensation.
+  `retrieveOrderGroup` doesn’t throw when no group has the id: it resolves to `undefined`. Check the value before you use it, or use `getOrderGroupDetailWorkflow`, which throws `NOT_FOUND`.
 </Warning>
+
+## Write methods
+
+The write methods are the ones `MedusaService` generates for the model:
+
+| Method | Description |
+| --- | --- |
+| `createOrderGroups(data)` | Creates one group from a `CreateOrderGroupDTO`, or several from an array |
+| `updateOrderGroups(data)` | Updates groups from `UpdateOrderGroupDTO` objects |
+| `deleteOrderGroups(ids)` | Deletes groups by id |
+| `softDeleteOrderGroups(ids)` | Sets `deleted_at` on groups |
+| `restoreOrderGroups(ids)` | Clears `deleted_at` on groups |
+
+Creating a group doesn’t create orders or links. Checkout does that in `completeCartWithSplitOrdersWorkflow`, so prefer the workflow over calling `createOrderGroups` yourself.
+
+## Filters and sorting
+
+The repository builds its own SQL and reads only the top-level keys below. It ignores every other key, including `$and` and `$or`.
+
+| Filter | Matches |
+| --- | --- |
+| `id` | Group id, as a string or an array |
+| `customer_id` | Customer id, as a string or an array |
+| `cart_id` | Cart id, as a string or an array |
+| `seller_id` | Groups with at least one child order from the seller |
+| `status` | Groups with at least one child order in the status |
+| `payment_status` | Groups with at least one child order in the derived payment status |
+| `sales_channel_id` | Groups with at least one child order in the sales channel |
+| `created_at`, `updated_at` | A date or an operator map: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$nin`, `$like`, `$ilike` |
+| `q` | Group id or customer id containing the text, or a display id such as `#G98`, `G98`, or `98` on the group or a child order |
+
+The order-level filters only choose which groups match. `seller_count` and `total` still cover every order in each matching group. Pass `id` as a plain string or array: an `{ $in: [...] }` map isn’t read.
+
+`config.order` sorts by `display_id`, `created_at`, or `updated_at`, with `ASC` or `DESC`. Other keys are ignored. Without a valid key, groups come back by `created_at` descending.

package/content/platform/order-group/reference/workflows.mdx

@@ -1,39 +1,98 @@
 ---
-title: "Workflows"
+title: "Order group workflows"
 sidebarTitle: "Workflows"
-description: "Order group workflows, service methods, and events."
+description: "Input, output, hooks, steps, and events of the checkout split and the order group read workflows."
 ---
 
-This reference lists the workflows, service methods, and events for the Order
-Group domain. Import workflows from `@mercurjs/core/workflows` and run them
-against the Medusa container.
+Three workflows and one step make up the order group surface: the checkout split that creates groups, and two read workflows that return groups with derived child order statuses. Import them from `@mercurjs/core/workflows` and run them with the Medusa container.
 
-## Checkout workflow
+```ts
+import {
+  completeCartWithSplitOrdersWorkflow,
+  createOrderGroupStep,
+  getOrderGroupDetailWorkflow,
+  getOrderGroupsListWorkflow,
+} from "@mercurjs/core/workflows"
+```
 
-| Workflow | Input | Purpose |
+## completeCartWithSplitOrdersWorkflow
+
+Completes a cart by creating one order per seller under a new order group. Workflow id `complete-cart-with-split-orders`. Mercur’s cart completion route and `processPaymentWorkflow` both run it.
+
+| Input | Type | Description |
 | --- | --- | --- |
-| `completeCartWithSplitOrdersWorkflow` | `{ cart_id }` | Split a multi-seller cart into per-seller orders and create the parent `OrderGroup`. Returns `{ order_group_id }`. Idempotent per cart. |
+| `cart_id` | `string` | The cart to complete |
+
+It returns `{ order_group_id: string }`. If a group with the same `cart_id` already exists, the workflow skips the split and returns that group’s id.
 
-## Read workflows
+The workflow stores its execution (`store: true`) and keeps it for 3 days. It holds a lock on the cart id with a 30-second wait timeout and a 2-minute time to live, so concurrent completions of one cart run one at a time.
 
-| Workflow | Input | Purpose |
+### Hooks
+
+| Hook | Receives | Use it to |
 | --- | --- | --- |
-| `getOrderGroupDetailWorkflow` | `{ order_group_id, fields }` | Load one group with its child orders and derived per-order payment/fulfillment status |
-| `getOrderGroupsListWorkflow` | `{ fields, variables?, sellerId? }` | List groups with a count; `sellerId` scopes each group's child orders to a seller |
+| `validate` | `{ input, cart }` | Throw to stop the checkout before anything is created |
+| `setOrderStatus` | `{ cart }` | Return `{ status?, status_by_seller_id? }` to set each child order’s initial status; the default is `pending` |
+
+`SetOrderStatusHookResult` is exported with the workflow. `status_by_seller_id` is keyed by seller id and takes precedence over `status`.
+
+### Steps
+
+The workflow runs these steps in order. Steps 3 to 6 run only when no group exists for the cart:
+
+1. `acquireLockStep` on the cart id, then a query for an existing group and the cart.
+2. `validateCartPaymentsStep`, then the `validate` and `setOrderStatus` hooks.
+3. `validateSellerCartItemsStep` and `validateSellerCartShippingStep`.
+4. `createOrderGroupStep` and `createOrdersStep`, in parallel.
+5. `createRemoteLinkStep`, `mirrorLineItemOfferLinksToOrderStep`, `updateCartsStep` to set `completed_at`, `reserveInventoryStep`, `registerUsageStep`, and two `emitEventStep` calls.
+6. `authorizePaymentSessionStep`, then `splitCapturedCartPaymentWorkflow` and `refreshOrderCommissionLinesWorkflow` as steps.
+7. `releaseLockStep` on the cart id.
+
+### Events
+
+| Event | Payload |
+| --- | --- |
+| `order.placed` | `{ id }`, once per child order |
+| `order_group.created` | `{ id }` of the new group |
+
+## getOrderGroupDetailWorkflow
+
+Retrieves one order group with its child orders and sets `payment_status` and `fulfillment_status` on each order. Workflow id `get-order-group-detail`. Its input type is `GetOrderGroupDetailWorkflowInput`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `order_group_id` | `string` | The group to retrieve |
+| `fields` | `string[]` | Fields to return, in `query.graph` syntax |
+
+It returns the group. The workflow always adds `id`, `orders.id`, `orders.status`, `orders.version`, `orders.currency_code`, and `orders.items.*` to your fields, plus the payment collection and fulfillment fields it needs for the statuses. It throws `NOT_FOUND` when no group has the id.
+
+The workflow removes some data it loaded for itself before it returns:
+
+- **`orders.payment_collections`**: kept only when a requested field contains `payment_collections`
+- **`orders.fulfillments`**: kept only when a requested field contains `fulfillments`
+- **`orders.cart`**: kept only when a requested field starts with `orders.cart`
+
+## getOrderGroupsListWorkflow
+
+Lists order groups with their child orders and derived statuses. Workflow id `get-order-groups-list`. Its input type is `GetOrderGroupsListWorkflowInput`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `fields` | `string[]` | Fields to return, in `query.graph` syntax |
+| `variables` | `object`, optional | Filters plus `skip`, `take`, and `order` |
+| `sellerId` | `string \| string[]`, optional | Removes other sellers’ orders from each returned group |
+
+It returns `{ rows, metadata }`, where `metadata` holds `count`, `skip`, and `take`. It adds the same child order fields as the detail workflow and removes the same data, and adds `orders.seller.id` when you pass `sellerId`.
+
+`sellerId` trims orders but doesn’t filter groups. Pass `variables.seller_id` as well to return only groups where the seller has an order. The filter keys are listed in [Filters and sorting](/platform/order-group/reference/service#filters-and-sorting).
 
-<Note>
-  The read workflows always expand the group's child `orders`. Heavy relations
-  (`payment_collections`, `fulfillments`) are only kept in the response when you
-  request a matching field, and are used to derive each order's `payment_status`
-  and `fulfillment_status`.
-</Note>
+## createOrderGroupStep
 
-## Step
+Creates one `OrderGroup` record. Step id `create-order-group`.
 
-| Step | Input | Purpose |
+| Input | Type | Description |
 | --- | --- | --- |
-| `createOrderGroupStep` | `{ customer_id?, cart_id }` | Create the `OrderGroup` record (used inside the checkout workflow, with a compensating delete) |
+| `cart_id` | `string` | The completed cart |
+| `customer_id` | `string \| null`, optional | The customer on the cart |
 
-To work with records directly instead of through a workflow, see the
-[Service reference](/platform/order-group/reference/service). To run side effects
-when a group is created, see the [Event reference](/platform/order-group/reference/events).
+It returns the created group. On rollback, it deletes the group with `deleteOrderGroups`. Use it in your own workflow only when you also create and link the child orders yourself.

package/content/platform/payout/concepts/account-lifecycle.mdx

@@ -1,75 +1,72 @@
 ---
-title: "Account lifecycle"
+title: "Payout account and payout statuses"
 sidebarTitle: "Account lifecycle"
-description: "Payout account statuses and the webhook-driven transitions between them."
+description: "The statuses a payout account and a payout move through, and the provider webhooks that move them."
 ---
 
-In this document, you'll learn about the payout account lifecycle and how its
-status stays in sync with the provider.
-
-## Status
-
-A payout account's state is held in the `status` field of the `PayoutAccount`
-model, typed by the `PayoutAccountStatus` enum. An account moves through four
-statuses.
-
-```
-                ┌──────────┐
-                │ PENDING   │
-                └────┬─────┘
-                     │ account.activated
-                     ▼
-   ┌────────────┐   ┌────────┐
-   │ RESTRICTED  │◄─►│ ACTIVE  │
-   └────────────┘   └───┬────┘
-                        │ account.rejected
-                        ▼
-                  ┌──────────┐
-                  │ REJECTED  │
-                  └──────────┘
-```
-
-| Status | Meaning |
-| --- | --- |
-| `PENDING` | Account created, provider onboarding not yet complete. |
-| `ACTIVE` | Fully onboarded. Can receive payouts. |
-| `RESTRICTED` | Provider flagged the account, for example missing KYC. No payouts. |
-| `REJECTED` | Provider permanently disabled the account. |
+A payout account’s status says whether the seller can receive money, and a payout’s status says where one transfer stands. Neither is set by an operator. The provider decides, sends a webhook, and `processPayoutForWebhookWorkflow` writes the new status. Read this page to know when `createPayoutWorkflow` will accept an account, and what each webhook does.
+
+## Account statuses
+
+An account’s state is the `status` field on `PayoutAccount`, typed by the `PayoutAccountStatus` enum from `@mercurjs/types`. It defaults to `pending`, and the provider’s `createPayoutAccount` response can overwrite it.
+
+| Status | Value | Meaning |
+| --- | --- | --- |
+| `PENDING` | `pending` | Created, setup not finished |
+| `ACTIVE` | `active` | Can receive payouts |
+| `RESTRICTED` | `restricted` | Missing information or a compliance issue |
+| `REJECTED` | `rejected` | Permanently disabled by the provider |
+
+Only `active` matters to the rest of the module. `createPayouts` throws `Account 'pacc_…' is not active` for any other status, so a payout never starts on a pending, restricted, or rejected account.
+
+## Webhooks set the account status
+
+The provider owns the account status, and a webhook carries each change. The provider’s `getWebhookActionAndData` turns a raw webhook into an action and the `pacc` id it applies to. `processPayoutForWebhookWorkflow` then runs the matching step.
+
+<img className="block dark:hidden" src="/images/figures/payout-account-lifecycle-light.svg" alt="A Stripe account.updated webhook behind the process-payout-for-webhook workflow. The workflow maps account.activated to the activate-payout-account step and the Active status, account.restricted to Restricted, account.rejected to Rejected, and not_supported to no change." />
+<img className="hidden dark:block" src="/images/figures/payout-account-lifecycle-dark.svg" alt="A Stripe account.updated webhook behind the process-payout-for-webhook workflow. The workflow maps account.activated to the activate-payout-account step and the Active status, account.restricted to Restricted, account.rejected to Rejected, and not_supported to no change." />
+
+The workflow doesn’t check the current status before it writes. Any action can move an account from any status, so the provider’s view always wins:
+
+| Action | Step | New status |
+| --- | --- | --- |
+| `account.activated` | `activate-payout-account` | `active` |
+| `account.restricted` | `restrict-payout-account` | `restricted` |
+| `account.rejected` | `reject-payout-account` | `rejected` |
+| `not_supported` | none | unchanged |
+
+Each step is `updatePayoutAccountStep`, renamed with `.config({ name })`. It saves the previous status and restores it if the workflow rolls back.
+
+## How Stripe Connect maps account updates
+
+The Stripe Connect provider handles only Stripe’s `account.updated` event, and it reads the `pacc` id from the Stripe account’s `metadata.account_id`. It picks the action in this order:
+
+1. `account.rejected` when `requirements.disabled_reason` starts with `rejected.`
+2. `account.activated` when every enabled `accountValidation` check passes
+3. `account.restricted` in every other case
+
+The default checks are `detailsSubmitted`, `chargesEnabled`, `payoutsEnabled`, and `noOutstandingRequirements`, all `true`, with no `requiredCapabilities`.
 
 <Note>
-  Payouts are only created against an `ACTIVE` account. The module rejects a
-  payout for an account in any other status.
+  With Stripe Connect, an account can skip `pending` and go to `restricted` first. Stripe sends `account.updated` while the seller is still onboarding, and an account with outstanding requirements maps to `account.restricted`. It becomes `active` on a later update.
 </Note>
 
-## Webhook-driven transitions
-
-Unlike the store lifecycle, payout account transitions are **not** operator
-actions. They follow the provider. The provider sends a webhook, a subscriber
-resolves it to an action, and `processPayoutForWebhookWorkflow` updates the
-status.
-
-| Webhook action | Resulting status |
-| --- | --- |
-| `account.activated` | `ACTIVE` |
-| `account.restricted` | `RESTRICTED` |
-| `account.rejected` | `REJECTED` |
-
-```ts
-// Inside processPayoutForWebhookWorkflow
-when({ input }, ({ input }) => input.action === "account.activated")
-  .then(() =>
-    updatePayoutAccountStep({ id: input.data!.id, status: PayoutAccountStatus.ACTIVE })
-  )
-```
-
-<Tip>
-  A `RESTRICTED` account is not terminal. Once the seller resolves the
-  provider's requirements, the provider emits `account.activated` again and the
-  account returns to `ACTIVE`. `REJECTED` is the only permanent state.
-</Tip>
-
-## Payout status
-
-An individual transfer carries its own `PayoutStatus` (`PENDING` → `PROCESSING`
-→ `PAID`, or `FAILED` / `CANCELED`). Provider webhooks advance it through the
-same workflow. See [The payout pipeline](/platform/payout/concepts/payout-pipeline).
+## Payout statuses
+
+Each payout carries its own `PayoutStatus`. The module creates the row as `pending`, then stores the status the provider’s `createPayout` returns.
+
+| Status | Value | Set by |
+| --- | --- | --- |
+| `PENDING` | `pending` | Row creation |
+| `PROCESSING` | `processing` | A `payout.processing` webhook |
+| `PAID` | `paid` | The provider response or a `payout.paid` webhook |
+| `FAILED` | `failed` | A `payout.failed` webhook |
+| `CANCELED` | `canceled` | A `payout.canceled` webhook |
+
+The Stripe Connect provider returns `paid` as soon as Stripe creates the transfer, and it maps no Stripe event to a `payout.*` action. The `payout.*` branches exist for providers that settle asynchronously.
+
+## Related
+
+- [Process a provider webhook](/platform/payout/guides/process-a-provider-webhook) to see the webhook path end to end
+- [The payout pipeline](/platform/payout/concepts/payout-pipeline) for what happens once an account is active
+- [Workflows reference](/platform/payout/reference/workflows) for every step name

package/content/platform/payout/concepts/accounts-and-onboarding.mdx

@@ -1,70 +1,80 @@
 ---
-title: "Accounts & onboarding"
+title: "Payout accounts and onboarding"
 sidebarTitle: "Accounts & onboarding"
-description: "The payout account, its onboarding record, and provider-specific data."
+description: "How a seller connects to the payout provider, and where provider data such as account ids and onboarding links lives."
 ---
 
-In this document, you'll learn how a seller connects to a payment provider and
-where provider-specific data lives.
+A payout account is a seller’s connection to the payout provider, and onboarding is the provider-side setup the seller completes before money can reach them. You need both before you can pay a seller. Mercur stores the provider’s own data on each record without reading it, so the same records work for any provider.
 
-## Payout account
+## The payout account
 
-A payout account is the seller's connection to the payment provider. It is the
-record funds are transferred to. A payout account is represented by the
-`PayoutAccount` data model (table `payout_account`, id prefix `pacc`). It is
-created for a seller through `createPayoutAccountWorkflow`, which also links the
-account to the store.
+A payout account is the record a payout is sent to. It’s the `PayoutAccount` data model (table `payout_account`, id prefix `pacc`), and the `seller_payout_account` link ties it to exactly one seller.
+
+You create one with `createPayoutAccountWorkflow`. The workflow checks the seller has no account yet, asks the module to create the account, and links it to the seller:
 
 ```ts
+import { createPayoutAccountWorkflow } from "@mercurjs/core/workflows"
+
 const { result } = await createPayoutAccountWorkflow(container).run({
   input: {
-    seller_id: "sel_123",
-    context: { /* forwarded to the provider */ },
-    data: { /* forwarded to the provider */ },
+    seller_id: "sel_01JD8Q1234567",
+    data: { country: "US" },
   },
 })
 ```
 
-Creating an account is a two-step operation. The module first persists the
-`PayoutAccount`. It then calls the provider to create the connected account and
-stores what the provider returns in the account's `data` field. A seller has
-**exactly one** payout account.
+Inside the module, `createPayoutAccount` runs 3 writes in order:
+
+1. Create the `PayoutAccount` row with your `data` and `context`
+2. Call the provider’s `createPayoutAccount` with `data.account_id` set to the new `pacc` id and `context.idempotency_key` defaulting to the same id
+3. Overwrite the row’s `data` and `status` with what the provider returns
+
+If the provider call throws, the module deletes the new row and rethrows. The Stripe Connect provider returns `pending` and the full Stripe account object. The built-in `system` provider returns `active` and an empty object.
 
 <Note>
-  A store can only have **one** payout account. `createPayoutAccountWorkflow`
-  validates that the seller doesn't already have one before creating it.
+  A seller can have only one payout account. `validateSellerPayoutAccountStep` queries `seller_payout_account` and fails with `Seller already has a payout account` when a row exists.
 </Note>
 
 ## Onboarding
 
-Before an account can receive funds, the seller usually has to complete
-provider-side setup, such as identity verification, bank details, or KYC. That
-state is held in the `Onboarding` data model (table `onboarding`, id prefix
-`onb`). The record is a one-to-one satellite of the payout account.
+Onboarding is the provider’s setup flow: identity checks, bank details, and anything else the provider needs. Its state lives in the `Onboarding` data model (table `onboarding`, id prefix `onb`), a one-to-one child of the payout account.
+
+`createOnboardingWorkflow` takes an `account_id` and calls the provider’s `createOnboarding`. The module merges the account’s stored `data` with the `data` you pass, so the provider sees both. With Stripe Connect, the account’s `data.id` is the Stripe account id, and you pass `refresh_url` and `return_url`:
 
 ```ts
-await createOnboardingWorkflow(container).run({
+import { createOnboardingWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await createOnboardingWorkflow(container).run({
   input: {
-    account_id: "pacc_123",
-    context: { return_url: "https://store.example.com/settings/payouts" },
+    account_id: "pacc_01JD8Q1234567",
+    data: {
+      refresh_url: "https://vendor.example.com/payouts/refresh",
+      return_url: "https://vendor.example.com/payouts",
+    },
   },
 })
 ```
 
-The workflow asks the provider to produce onboarding data (for Stripe Connect,
-an onboarding link) and stores it on the record. Running it again on an account
-that already has an onboarding record **updates** it rather than creating a
-second one.
+The result’s `data` holds what the provider returned. For Stripe Connect, that’s an account link object, and `data.url` is the hosted onboarding page. The workflow is safe to re-run:
+
+- **First run**: creates the `Onboarding` record
+- **Later runs**: update the same record with new provider data, which you need when a Stripe link expires
+
+## Provider data and context
+
+Every payout record has a `data` JSON field, and accounts and onboarding records also have `context`. They play different roles:
+
+- **`data`**: the provider’s durable payload, such as the Stripe account, the account link, or the transfer
+- **`context`**: per-call hints for the provider, today only `idempotency_key`
+
+The module never interprets `data`. It passes it to the provider and stores what comes back. When you switch providers, the records keep the same shape.
 
-## Provider data
+<Warning>
+  A payout account’s `data` holds the raw provider object. For Stripe Connect, that’s the full `Stripe.Account`, so select only the fields you need before you return it from a public route.
+</Warning>
 
-The `data` JSON field on `PayoutAccount`, `Onboarding`, and `Payout` is where
-provider-specific values live, such as the Stripe account id, onboarding URLs, or
-transfer references. The module never interprets these fields. It forwards them
-to and from the provider.
+## Related
 
-<Tip>
-  `context` carries per-request hints such as an `idempotency_key` or a
-  `return_url`, while `data` carries the durable provider payload. Both are
-  passed straight through the `IPayoutProvider` interface.
-</Tip>
+- [Account lifecycle](/platform/payout/concepts/account-lifecycle) for the statuses an account moves through after onboarding
+- [Create a payout account](/platform/payout/guides/create-a-payout-account) for a full route example
+- [Start provider onboarding](/platform/payout/guides/start-provider-onboarding) for the onboarding route