Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Recorded the seller ledger UI plan and its two decisions
Damian Legawiec8aee6ac27c70
diff --git a/docs/plans/6.0-admin-api.md b/docs/plans/6.0-admin-api.mdindex 46fd77eef9..f5fceeaaad 100644--- a/docs/plans/6.0-admin-api.md+++ b/docs/plans/6.0-admin-api.md@@ -713,6 +713,7 @@ Per `6.0-multi-vendor-marketplace.md`. Seller prefix is `sel_` (matches the lega- [x] `GET /api/v3/admin/seller_transfers` — read-only earnings ledger (filter by seller/payout/status; `read_payouts`)- [x] `GET /api/v3/admin/seller_payouts` / `GET /:id`- [x] `PATCH /api/v3/admin/seller_payouts/:id/complete` — manual settlement (system provider; `write_payouts`)+- [x] `GET /api/v3/admin/sellers/:id/balances` — earned / paid / owed / in-flight, one row per currency (`read_payouts`)- [x] `GET /api/v3/admin/order_groups` / `GET /:id` — the multi-order transaction container (read-only; `read_orders`)API key scopes: `read_sellers` / `write_sellers`, `read_commissions` / `write_commissions`, `read_payouts` / `write_payouts`.diff --git a/docs/plans/6.0-multi-vendor-marketplace.md b/docs/plans/6.0-multi-vendor-marketplace.mdindex 2a77283908..9943812080 100644--- a/docs/plans/6.0-multi-vendor-marketplace.md+++ b/docs/plans/6.0-multi-vendor-marketplace.md@@ -754,7 +754,7 @@ This is **new OSS code**, not a rename of existing core — there is no in-place- **Phase 3a — fund ledger. IMPLEMENTED 2026-08-22.** The two-level `SellerTransfer` (on-fulfillment) + `SellerPayout` (scheduled sweep) + `PayoutProvider::System` + `seller.balance(currency)`, sequenced after the split because the transfer basis needs child orders to exist. **What shipped and why it took the shape it did:** a seller earns on **fulfilment**, not payment — `SellerTransferSubscriber` answers `order.fulfilled` (only; the legacy `order.shipped` is deliberately not subscribed) and `SellerTransfers::Create` writes `order.total − commission_lines.sum(:total)`, less `additional_tax_total` when the seller is `platform`-remitted, floored at zero. Its guards are the interesting part: an order with **no** fulfillments reads as `fully_fulfilled?` (vacuously true), so the emptiness is checked explicitly, and a seller whose provider `requires_payout_account?` but who holds none is skipped rather than credited money nothing can send. A refund writes a **reversal row** (`kind: 'refund_reversal'`, linked by `reversed_from`) bounded by `reversible_amount`, so a twice-refunded order can never claw back more than was credited; the earning row is never edited. A partial unique index on `(order_id) WHERE kind = 'earning'` makes double-crediting a database error rather than a race (MySQL takes a `CASE WHEN` generated column instead). `SellerPayouts::Sweep` claims unsettled transfers **by stamping them inside one transaction**, so two concurrent runs cannot batch the same earning, and restates its own amount if it claimed fewer rows than it counted; it refuses a batch below the seller's minimum or one a reversal has pushed negative. `SellerPayouts::Complete` is the only thing that debits a balance, because a settlement is a claim about the outside world — an operator says the bank transfer went out, or a provider's webhook says the money landed. Admin API: read-only `/admin/seller_transfers` and `/admin/seller_payouts` plus `PATCH /seller_payouts/:id/complete`, under a new `payouts` permission resource (separate from `commissions` — they are opposite directions of the same relationship, and a finance operator often needs one without the other; closed to the seller audience).- **Note for the second splitting consumer (recorded 2026-08-20).** `Carts::SplitBySeller` is seller-specific in exactly **three lines** — the `seller_id` stamped on the adopted order and on each sibling, and the `line_items.where(seller_id:)` that selects a partition's rows. Everything else (group construction, number suffixing, parcel division and its delivery-cost apportionment, typed-line re-homing, order-level fee proration, the `resum_only` re-total) is partition-agnostic. When split-by-location or B2B split-by-company-location lands, the move is to lift those three lines into a registered splitter (`Spree.order_splitters`, following `Spree.stock_splitters`/`Spree.adjusters`) and rename the rest to `Orders::Split`, **not** to copy the file. Deliberately not done now, per the standing rule that a flow generalizes when it has a second consumer rather than speculatively — but the analysis is recorded so the second consumer does not have to redo it.- **Phase 3b — OSS Stripe Connect provider. IMPLEMENTED 2026-08-22** in `spree/providers/stripe`. `SpreeStripe::PayoutProvider` transfers on fulfilment naming the customer's own charge as `source_transaction` (so the money settles with that charge rather than out of the platform's balance — a marketplace should not have to float its sellers), with an idempotency key derived from the ledger row. `pay!` deliberately **sends nothing**: money on a connected account is settled to the seller's bank by Stripe on that account's own schedule, so a payout is confirmed by webhook exactly as the built-in provider's is confirmed by an operator. `reverse!` is ledger-only in OSS. **Connect settings live on the Stripe payment method, not in an integration of their own** — it is the same Stripe account either way, and a transfer signed with a different key than the charge cannot name that charge as its funding source, so a second copy of the credentials could only drift out of agreement with the first. **Two webhook endpoints, and this is not a detail.** Stripe's `connect` flag is a *scope selector*, not an additive one: an endpoint receives events from the platform's own account **or** from its connected accounts, never both. Adding `account.updated` to the payment endpoint would not widen it — it would switch it over, and the payment webhooks would silently stop arriving. So a marketplace registers a second endpoint with its own signing secret, served by a new provider-agnostic `POST /api/v3/webhooks/payouts/:payment_method_id` route beside the payments one, and it is registered only once the store actually has sellers. `account.updated` writes `payouts_enabled_at` — and **clears it** when Stripe withdraws the capability, since a seller whose documents expire stops being payable and the ledger must stop crediting them. Not yet built: the Express onboarding UI (`create_connect_account_link` exists and is specced; the seller-facing screen belongs with the onboarding work) and payout-schedule mapping onto the connected account.- - **Phase 4 — Dashboards.** **The order surfaces landed early with Phase 3 (2026-08-21)**, since a split checkout is unreadable without them: the orders table gained optional `seller` and `order_group` columns (both `default: false`, so a store selling only its own goods never sees them) with Ransack filters behind them, and the order page gained a marketplace card naming the seller — linked to their profile — and, when the order was one of several, the purchase it belonged to with a link back to the list filtered to its siblings. The card renders nothing on an ordinary order. Deliberately **no order-group screen of its own**: the group is the shared payment and the identity of the purchase, and what an operator acts on is always an order, so the group appears as a filter and a link rather than a page. `orders.seller_id`/`order_group_id` joined the Ransack allowlist (without which a filter silently matches nothing); the serializer carries **ids only**, with the seller's name coming from `?expand=seller` requested by the column while it is visible — a denormalized `seller_name` was tried and dropped as a second copy of something the association already answers. The order group is deliberately **not** expandable from an order: its serializer renders the orders it holds, so expanding it from one of them would render that order inside itself, and a client wanting the group has `/order_groups/:id`. Remaining: (a) Operator marketplace screens in `@spree/dashboard`: Sellers list/detail (lifecycle actions, branding, commission + payout settings, ledger-derived lifetime revenue/commission), Commission Rates settings page, Payouts review queue (owed balances, itemized payouts, mark-paid), OrderGroup rendering on order screens, and a "needs attention" queue on the dashboard home (sellers `ready_for_review` + pending seller products — a lightweight unified review inbox). (b) Seller panel: compose `@spree/dashboard-ui` + `@spree/dashboard-core` into a seller-scoped panel (per `6.0-admin-spa.md` — the package split exists precisely for this) talking to the Seller API branch (own login page + `seller_api` tokens; `PermissionProvider` fed by `/seller/me`). Seller roles come from the operator's roles editor filtered to the seller audience; the operator's Sellers detail screen assigns them. Surfaces the seller's products, orders + fulfillment actions, and the balance + transfer/payout ledger (earned/settled) read-only for OSS.+ - **Phase 4 — Dashboards.** **The ledger surfaces landed 2026-09-09 — see `6.0-seller-ledger-ui.md`**, which owns the seller panel's balance/earnings/payouts screens, the payment share on a seller's order, and the operator's transfers list, payouts review queue with mark-paid, seller balance card and grouped-order payments card. It also adds the `seller_earnings` permission key; a seller reads their own ledger through that, never through `payouts`. **The order surfaces landed early with Phase 3 (2026-08-21)**, since a split checkout is unreadable without them: the orders table gained optional `seller` and `order_group` columns (both `default: false`, so a store selling only its own goods never sees them) with Ransack filters behind them, and the order page gained a marketplace card naming the seller — linked to their profile — and, when the order was one of several, the purchase it belonged to with a link back to the list filtered to its siblings. The card renders nothing on an ordinary order. Deliberately **no order-group screen of its own**: the group is the shared payment and the identity of the purchase, and what an operator acts on is always an order, so the group appears as a filter and a link rather than a page. `orders.seller_id`/`order_group_id` joined the Ransack allowlist (without which a filter silently matches nothing); the serializer carries **ids only**, with the seller's name coming from `?expand=seller` requested by the column while it is visible — a denormalized `seller_name` was tried and dropped as a second copy of something the association already answers. The order group is deliberately **not** expandable from an order: its serializer renders the orders it holds, so expanding it from one of them would render that order inside itself, and a client wanting the group has `/order_groups/:id`. Remaining: a "needs attention" queue on the dashboard home (sellers `ready_for_review` + pending seller products — a lightweight unified review inbox). Everything else in this phase has shipped: the operator's Sellers list/detail with lifecycle actions, branding and settlement settings, the Commission Rates settings page, and — per `6.0-seller-ledger-ui.md` (2026-09-09) — the payouts review queue with owed balances, itemized settlements and mark-paid, the seller balance card, and the seller panel's own balance/earnings/payouts screens. The seller panel itself is composed from `@spree/dashboard-ui` + `@spree/dashboard-core` against the Seller API branch, with roles assigned from the operator's Sellers detail screen.**Phases 1–2 have no dependency on the Cart/Order split** — they can be built (even shipped behind a preview flag in a 5.x release) while the split refactor lands, de-risking the 6.0 timeline.diff --git a/docs/plans/6.0-seller-ledger-ui.md b/docs/plans/6.0-seller-ledger-ui.mdnew file mode 100644index 0000000000..7fc765543a--- /dev/null+++ b/docs/plans/6.0-seller-ledger-ui.md@@ -0,0 +1,169 @@+# Seller Ledger UI — payment splits, transfers and payouts in both panels++**Status:** Implemented (2026-09-09) — backend, both SDKs, both panels, specs and E2E all in+**Target:** Spree 6.0+**Depends on:** `6.0-multi-vendor-marketplace.md` (Decision 5 — `PaymentSplit`; Decision 9 — the two-level ledger; Decision 10 — the seller branch; Phases 3, 3a, 3b — all shipped), `6.0-seller-order-management.md` (the seller order page this extends, and its money constraints), `6.0-admin-spa.md` (panel composition)+**Author:** Damian Legawiec+**Last updated:** 2026-09-09++## Summary++The marketplace's money model is complete on the backend — one customer payment recorded per child order as a `PaymentSplit`, a `SellerTransfer` credited to the seller when their order ships, a `SellerPayout` sweeping those transfers to the seller's bank, and Stripe Connect executing both — but nobody can see any of it. A seller's order page shows what the sale came to and what the marketplace charged them, and nothing about what was paid or what they earned; the seller panel has no earnings or payouts screens at all. The operator dashboard has the ledger endpoints in the SDK and consumes none of them: no transfers list, no payouts queue, no balance on a seller's page, and on an order that came out of a split checkout the payments card is empty, because the payment hangs off the group. This plan closes the marketplace plan's Phase 4 ledger items: the read-only balance, transfer and payout ledger in the seller panel, the payment share on a seller's order, and the operator's transfers list, payouts review queue with mark-paid, balance card and grouped-order payments.++## Key Decisions (do not deviate without discussion)++### 1. The seller sees their own share of the payment, never the payment (RESOLVED 2026-09-09)++Reaffirms the marketplace plan (Decision 10: "the seller sees its `payment_split`, never the group's `Payment`") and the seller order plan (`Seller::OrderSerializer` "does **not** gain `payments`"). The seller order serializer gains `payment_splits`, serialized by a `Seller::PaymentSplitSerializer` that carries the split's amounts and nothing about the payment behind it — no method, no gateway status, no source. A seller reconciling their statement needs "how much of my order was captured, refunded and is still refundable"; how the buyer paid the marketplace stays the marketplace's.++An order placed with a single seller does not split and has no `PaymentSplit` rows: the panel's payment card then shows only what the order already serializes — `payment_status`, `payment_total`, `amount_due` — and no per-payment rows. This is deliberate. Exposing the order's own `Payment` on that path would mean two shapes for one card, and would reopen the payments question the seller order plan closed. If a seller-facing payment row is ever wanted for ungrouped orders, it is a `Seller::PaymentSerializer` with the split's field list, never a subclass of the store or admin one.++### 2. The seller ledger gets its own read-only key, `seller_earnings` (RESOLVED 2026-09-09)++`Spree::SellerTransfer` and `Spree::SellerPayout` are subjects of the operator's `payouts` resource, which is closed to the seller audience by design (the catalog comment: a seller reads their own earnings through their own branch, scope-fetched, never through a key that could reach the whole ledger). The seller branch therefore gates its balance, transfer and payout endpoints on a new catalog resource:++```ruby+register_resource(:seller_earnings, group: :access, subjects: -> { [:seller_earnings] },+ write: false, audiences: %i[seller])+```++A symbol subject, exactly like `seller_profile` and for the same reason: the model classes belong to `payouts`, and claiming them twice would make `resource_for_subject` answer by registration order. Controllers declare `scoped_resource :seller_earnings` and override `authorize_resource!` to authorize the symbol (the `PoliciesController` pattern); which rows a seller may read is `current_seller` scope-fetching, never an ability rule.++Chosen over reusing `seller_profile` because a seller's owner must be able to give a packing teammate orders and fulfilments without showing them the money — settlement configuration is profile, but the ledger is the seller's books. A seller admin role is born with `grantable_keys(:seller)` at creation, so every seller created from here on holds the key; sellers are new in 6.0 and nothing older needs catching up, so there is no backfill (2026-09-09). A development database seeded before this key needs its seller role re-created or the key added by hand.++### 3. Operator ledger screens live under Sellers; the seller panel gets Earnings and Payouts (RESOLVED 2026-09-09)++Operator: `/sellers/transfers` and `/sellers/payouts` (+ `/sellers/payouts/:id`) as children of the existing Sellers nav entry, gated on `Subject.SellerTransfer` / `Subject.SellerPayout`. They are about sellers, the way returns and exchanges sit under Orders; a store selling only its own goods never sees the entry. The existing `settings/payouts` page (store defaults and provider choice) is untouched.++Seller panel: two top-level entries between Orders and Profile — **Earnings** (`/earnings`: the balance per currency, then the transfer list) and **Payouts** (`/payouts`, `/payouts/:id`: settlements, each itemizing the transfers it covers). Two entries rather than one because they answer different questions on different days: "what did I earn on that order" and "did last week's payout go out". Both gated on the `seller_earnings` subject.++### 4. Balance is a value object computed from the ledger, per currency, on both branches++`Spree::SellerBalance` (`ActiveModel::Model` + `ActiveModel::Attributes`, per the project's no-`Struct` rule) is one seller's position in one currency: `earned` (Σ completed transfers, reversals included), `paid` (Σ completed payouts), `balance` (earned − paid — what the marketplace still owes, the same figure `Seller#balance(currency)` already answers), and `pending` (Σ transfers still `pending`/`processing`/`unresolved` — money in flight with the provider, shown so a seller does not read a shipped order as unpaid). `Seller#balances` answers one per currency the seller has ever earned or been paid in, so a multi-currency marketplace never collapses two ledgers into one number.++Served by `GET /api/v3/seller/balances` and `GET /api/v3/admin/sellers/:id/balances`. Deliberately **not** a marketplace-wide "owed by seller" endpoint: the payouts list filtered to `owed` is the operator's queue, and the sweep is what turns a balance into something to act on.++### 5. A grouped order's payments card shows the group's payments, read-only, with this order's share (RESOLVED 2026-09-09)++On an order that came out of a split checkout, `order.payments` is empty and the operator's payments card renders "no payments" — which is wrong, not merely incomplete. The card fetches the order group (`GET /admin/order_groups/:id`, which already serializes `payments`) and the order's `payment_splits` (a new `expand`), and renders each payment with an extra column: this order's authorized / captured / refunded share. Capture and void are **not** offered on a grouped child: those act on the group's payment, i.e. on every sibling's money, and belong on a surface that says so. `Admin::OrderSerializer#payments` keeps its meaning (the order's own rows), so the nested `orders/:id/payments` controller and everything reading `order.payments` are unchanged.++### 6. Read and write stay where they are++Nothing here creates, edits or moves money. Transfers and payouts are written by fulfilment and the sweep; the one write in scope is the existing `PATCH /admin/seller_payouts/:id/complete` (the built-in provider's "the bank transfer went out"), which the operator's payouts pages now expose with a reference field. The seller branch is read-only end to end — a seller sees `unresolved` and `failed` rows with their status and the marketplace's contact is how they follow up.++## Design Details++### Backend++**Core**++- `seller_earnings` catalog resource.+- `Spree::SellerBalance` — `spree/core/app/models/spree/seller_balance.rb`. Attributes `seller`, `currency`, `earned`, `paid`, `balance`, `pending` (decimals), `display_*` via `Spree::Money`. `SellerBalance.for(seller, currency)` computes from `seller.seller_transfers` / `seller.seller_payouts` in four grouped sums; `Seller#balances` maps it over `currencies = transfers.distinct.pluck(:currency) | payouts.distinct.pluck(:currency)`. `Seller#balance(currency)` stays as the canonical single figure (the payout sweep reads it).+- `Spree::SellerTransfer.whitelisted_ransackable_attributes` += `seller_id order_id payout_id`; `Spree::SellerPayout.whitelisted_ransackable_attributes` += `seller_id`. Without these a `q[order_id_eq]` filter silently matches nothing (the lesson recorded in the marketplace plan's Phase 4 note). The base controller already decodes prefixed ids in `*_id_eq` predicates.+- `Spree::PaymentSplit`: `claimed_amount` joins `money_methods` so every amount has a `display_` twin; `net_captured_amount` and `refundable_amount` get display twins the same way.++**Seller API** (`/api/v3/seller`, all read-only, all `scoped_resource :seller_earnings` with the `PoliciesController`-style authorization override, all rooted in `current_seller`):++- `GET /balances` — `Seller::BalancesController < Seller::BaseController` (a computed collection, no model; renders `current_seller.balances`).+- `GET /transfers`, `GET /transfers/:id` — `Seller::TransfersController < Seller::ResourceController`, `seller_association :seller_transfers`, `collection_includes [:order, :payout]`.+- `GET /payouts`, `GET /payouts/:id` — `Seller::PayoutsController`, `seller_association :seller_payouts`, with the same page-wide `transfer_counts` the admin controller builds.+- Serializers, all from `V3::BaseSerializer` (never a subclass of the admin ones — the seller order plan's constraint):+ - `Seller::TransferSerializer`: `id kind status currency amount display_amount provider reference order_id order_number payout_id reversed_from_id created_at updated_at`. No `metadata` (provider internals), no `refund_id` (refunds are not a seller resource), no `seller_id`/`seller_name` (there is one seller in play).+ - `Seller::PayoutSerializer`: `id status currency amount display_amount provider reference period_start period_end transfers_count created_at updated_at`.+ - `Seller::BalanceSerializer`: `currency earned paid balance pending` + `display_` twins. `id` is `nil` — the base serializer renders `id` only for objects answering `prefixed_id`; the SDK type marks it absent.+ - `Seller::PaymentSplitSerializer`: `id currency authorized_amount captured_amount refunded_amount claimed_amount net_captured_amount refundable_amount` + `display_` twins, `created_at`. `Seller::OrderSerializer` gains `many :payment_splits`, always rendered (an order page fetches one order; a list never embeds them because the seller orders index uses the same serializer — so the relation is gated `if: proc { expand?('payment_splits') }`, and the panel's order query asks for it).+- Routes: `resources :balances, only: [:index]`, `resources :transfers, only: [:index, :show]`, `resources :payouts, only: [:index, :show]` in the seller block, next to `orders`.++**Admin API**:++- `Admin::PaymentSplitSerializer`: the seller field list plus `payment_id`, `payment_number`, `order_id`, `order_number`, `updated_at`. Registered as `admin_payment_split_serializer`.+- `Admin::OrderSerializer` gains `many :payment_splits, if: expand?('payment_splits')`; `Admin::PaymentSerializer` gains the same, so a group's payment can itemize its shares.+- `GET /admin/sellers/:id/balances` — `Admin::Sellers::BalancesController`, `scoped_resource :payouts`, seller fetched through `current_store.sellers`. `Admin::SellerBalanceSerializer` adds `seller_id` to the seller shape.+- `Admin::OrdersController#show` `expand` allowlist admits `payment_splits`; `Admin::OrderGroupsController#show` keeps serializing `payments` (already does).++**Permissions**: the `seller_earnings` resource (Decision 2). Seller endpoints authorize `:seller_earnings`; admin balances sit under `payouts`; payment splits ride on `orders` (the order expand) and `payments` (`PaymentSplit` is already a `payments` subject). The seller panel gates the Earnings and Payouts entries and the order page's earnings card on the `seller_earnings` subject; the payment card rides on the order itself.++**OpenAPI**: integration specs under `spree/api/spec/integration/spree/api/v3/seller/{balances,transfers,payouts}_spec.rb` and `admin/sellers/balances_spec.rb`; `swaggerize` regenerates `seller.yaml` and `admin.yaml`. Typelizer emits `Balance`, `Transfer`, `Payout`, `PaymentSplit` into `@spree/seller-sdk` and `PaymentSplit`, `SellerBalance` into `@spree/admin-sdk`.++### SDKs++- `@spree/seller-sdk`: `balances.list()`, `transfers.list(params)` / `get(id)`, `payouts.list(params)` / `get(id)`; `orders.get` accepts `expand`.+- `@spree/admin-sdk`: `sellers.balances(id)`, `orderGroups.get(id)` (the endpoint exists, the client never wrapped it), `orders.get` already takes `expand`.++### Seller panel (`@spree/seller-dashboard`)++```+nav/default.ts → earnings (130), payouts (140), subject 'seller_earnings'+routes/_authenticated/$sellerId/earnings/index.tsx+routes/_authenticated/$sellerId/payouts/index.tsx+routes/_authenticated/$sellerId/payouts/$payoutId.tsx+pages/earnings.tsx → BalanceSummary + ResourceTable<Transfer> ('seller-transfers')+pages/payouts.tsx → ResourceTable<Payout> ('seller-payouts')+pages/payout.tsx → header (status, amount, reference, period) + the transfers it settled+components/finance/balance-summary.tsx → one card per currency: balance owed, pending; empty state before the first sale+components/orders/order-payment-card.tsx → payment status, paid, due; split rows when the order is grouped+components/orders/order-earnings-card.tsx → this order's transfers: kind, status, amount, payout link; nothing until fulfilled+tables/seller-transfers.tsx, tables/seller-payouts.tsx+hooks/use-balances.ts, use-transfers.ts, use-payouts.ts+```++The order page mounts the payment card after the summary card and the earnings card after it, both in the main column. The transfers table filters by `status`, `kind` and `created_at`; the payouts table by `status` and `created_at`. Rows open the payout page; a transfer row links to its order. `unresolved` joins `statusToneMap` (warning) in `@spree/dashboard-ui`, since both panels render it.++### Operator dashboard (`@spree/dashboard`)++```+nav/default.ts → sellers gains children: sellers.transfers, sellers.payouts+routes/_authenticated/$storeId/sellers/transfers.tsx → ResourceTable<SellerTransfer>+routes/_authenticated/$storeId/sellers/payouts/index.tsx → ResourceTable<SellerPayout>, row action "Mark as paid"+routes/_authenticated/$storeId/sellers/payouts/$payoutId.tsx → header + complete + its transfers+tables/seller-transfers.tsx → filters: seller (resource), status, kind, provider, created_at; links to order/seller/payout+tables/seller-payouts.tsx → filters: seller (resource), status, provider, created_at; default quick filter "owed"+components/spree/sellers/seller-balance-card.tsx → sidebar of the seller page, per currency, links to both lists filtered by seller+components/spree/sellers/payout-complete-dialog.tsx → reference input; shown only for owed payouts+components/spree/orders/order-payments-card.tsx → grouped branch: group payments + this order's share, no actions+components/spree/orders/order-seller-transfers-card.tsx → the earning and its reversals for a seller's order+hooks/use-seller-ledger.ts → useSellerBalances, usePayout, useCompletePayout, useOrderGroup+```++"Mark as paid" confirms through the dialog (the reference is the confirmation — no second confirm on top). It is offered for `pending`, `processing` and `unresolved` payouts, matching `SellerPayouts::Complete`'s compare-and-swap. Every new key lands in all six dashboard locales; the seller panel ships `en.json` only, as today.++### E2E++`packages/dashboard/e2e/seller-ledger.spec.ts`: seed a seller with a completed transfer and an owed payout through the API fixtures, open the payouts queue, mark it paid with a reference, assert the status badge and the reference on the detail page. Seller-panel coverage stays at controller + integration specs until that package has an e2e stack.++## Migration Path++No schema change; everything was additive. Shipped in this order:++1. **Core + Admin API.** `Spree::SellerBalance`, `Seller#balances`, the `seller_earnings` catalog resource, Ransack allowlist additions (`seller_id` on both ledger models, plus `order_id`/`payout_id` on transfers), `PaymentSplit` display methods for `claimed_amount`, `net_captured_amount` and `refundable_amount`, the admin payment-split and seller-balance serializers, `payment_splits` expands on the admin order and payment serializers, and `GET /admin/sellers/:id/balances`.+2. **Seller API.** `BalancesController`, `TransfersController`, `PayoutsController`, four serializers, routes, and `payment_splits` on the seller order serializer behind an expand.+3. **SDKs.** Typelizer regeneration, `balances`/`transfers`/`payouts` on the seller client with `orders.get` taking an expand, `sellers.balances` and a new `orderGroups` resource on the admin client.+4. **Seller panel.** The payment and earnings cards on the order page, then Earnings, then Payouts and the payout detail page.+5. **Operator dashboard.** The grouped-payments branch on the payments card, the seller-transfers card on the order page, the balance card on the seller page, the two ledger lists, the payout page, the mark-as-paid dialog, nav children, and locale keys in all six languages.++`ReadRow` was extracted out of the seller panel's profile page into `components/read-row.tsx` rather than copied a third time.++**Sample data.** `spree:sellers:sample_data` gained a fund ledger, so the new screens have something to render in a fresh development environment: five sales, a completed payout carrying its bank reference, one still owed for the mark-as-paid flow, an earning not yet swept into either, and a refund reversal. The reversal is deliberately left unsettled — a refund after its sale was already paid out belongs to the next period rather than to a closed settlement, which is the behaviour the ledger models. Written directly rather than through fulfilment and the sweep: reaching those would mean placing and shipping real orders, and the screens read the rows either way. Idempotent, and development/test only like the rest of that task.++## Constraints on Current Work++- **A seller serializer for money carries amounts, never provenance.** `Seller::PaymentSplitSerializer` must not grow `payment_id`, a method name, a gateway status or a source; `Seller::TransferSerializer` must not grow `metadata` or `refund_id`. Anything that identifies the marketplace's payment or the buyer's instrument is the admin serializer's.+- **Seller ledger endpoints authorize `:seller_earnings`** and root in `current_seller`. Do not add `payouts` or `payments` to the seller audience to make `authorize!` on the model class pass — that is the leak the catalog comment warns about.+- **A seller role holds the keys it was created with.** Adding a seller-audience key to the catalog reaches new roles only; that is acceptable while sellers are new in 6.0, and a key added after 6.0 ships is a different conversation.+- **Nothing on either panel offers capture, void or refund on a grouped child's payment** until a surface exists that names every sibling the action touches.+- **Filters go through the allowlist.** A new `q[<column>_eq]` on the ledger needs the column in `whitelisted_ransackable_attributes`; an association name alone does not make its foreign key filterable.+- **`Seller#balance(currency)` stays the single figure the sweep reads.** `SellerBalance` presents it; it must not compute a different number.++## Open Questions++None. The four questions the draft raised (the seller permission key, ungrouped-order payments, operator navigation, and the grouped child's payments card) were settled on 2026-09-09 and are recorded in Key Decisions 2, 1, 3 and 5.++Deferred, not open: a seller-facing payment row on ungrouped orders (Decision 1 names the shape if wanted), and capture/void on a grouped child's payment (Decision 5 — needs a surface that names every sibling).++## References++- `docs/plans/6.0-multi-vendor-marketplace.md` — Decisions 5, 9, 10; Phases 3, 3a, 3b, 4.+- `docs/plans/6.0-seller-order-management.md` — the seller order page and its money constraints.+- `docs/plans/6.0-admin-api.md` — Marketplace endpoint group.+- `spree/api/app/controllers/spree/api/v3/seller/policies_controller.rb` — the `seller_profile` authorization pattern.+- `spree/api/app/controllers/spree/api/v3/admin/seller_payouts_controller.rb` — `complete` and the page-wide transfer count.diff --git a/docs/plans/6.0-seller-order-management.md b/docs/plans/6.0-seller-order-management.mdindex 1c473c0f4c..37a526a3b5 100644--- a/docs/plans/6.0-seller-order-management.md+++ b/docs/plans/6.0-seller-order-management.md@@ -201,6 +201,7 @@ No data migration: everything here is additive, and no existing column, route or## References- `docs/plans/6.0-multi-vendor-marketplace.md` — Decision 10 (the seller branch), Decision 13 (seller delivery), Phase 3/3a (split + ledger). **Amended by Decision 1 above.**+- `docs/plans/6.0-seller-ledger-ui.md` — the money surfaces this plan left out. It adds the payment card (this order's share of the basket's payment, amounts only) and the earnings card to the order page, so the "Payments — no" row in the card table above means *the group's `Payment`*, not the child's share.- `docs/plans/6.0-returns-exchanges-claims.md` — the three models and their fifteen workflows.- `docs/plans/6.0-fulfillment-and-delivery.md` — fulfillment status model, partial fulfillment, tracking axis.- Legacy Enterprise module, `SpreeMultiVendor::PermissionSets::VendorUser` — the source of truth for what a vendor could already do.diff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex e633fd3c1e..0c4ae36bc8 100644--- a/docs/plans/decisions.md+++ b/docs/plans/decisions.md@@ -5133,3 +5133,45 @@ parcel.`Stock::Package#default_package_type`, never `store.default_package_type`;seller-facing reads go through `available_to_seller(seller)`, seller writesthrough `seller.package_types`.++## 2026-09-09 — A seller's own books get their own permission key, and a grouped order's payments are read where they were taken++Making the marketplace fund ledger visible (`docs/plans/6.0-seller-ledger-ui.md`)+forced two questions that outlive the screens themselves.++**The seller ledger is `seller_earnings`, not `seller_profile`.** The obvious+move was to reuse the profile key, the way `PoliciesController` does for a+class the operator's `settings` owns. It was rejected: settlement+*configuration* is the seller's profile, but what they have earned is their+books, and a seller's owner must be able to hand a packing teammate the orders+without also handing them the money. So a new read-only, seller-audience+catalog resource with a symbol subject — the ledger classes stay subjects of+the operator's `payouts` key, and claiming them twice would make+`resource_for_subject` answer by registration order. The cost is real and was+accepted knowingly: **a role holds the keys it was created with and is never+re-read**, so a key added to the catalog reaches new roles only. That is+harmless here because sellers are new in 6.0 and no older role exists — but a+seller-audience key added after 6.0 ships needs a backfill task, and the+question to ask before adding one is always "which existing roles does this+silently not reach?"++**A grouped child order's payments are the group's, read-only, with the+child's share beside them.** `order.payments` is empty on an order from a+split checkout, so the operator's payments card rendered "no payments" on an+order that was paid in full — wrong, not merely incomplete. The fix reads the+group's payments and the order's `payment_splits` and shows both, and it+deliberately **does not** re-point `Admin::OrderSerializer#payments` at+`settlement_payments`: that would change what `order.payments` means for every+consumer, and capture/void through `orders/:id/payments` would then act on+every sibling's money without saying so. Capture, void and add are hidden on a+grouped child for the same reason — they belong on a surface that names every+order they touch.++**Constraints now:** a seller-facing money serializer carries amounts, never+provenance (no payment id, method, gateway status or source — `Seller::+PaymentSplitSerializer` and `Seller::TransferSerializer` are the reference);+seller ledger endpoints authorize `:seller_earnings` and root in+`current_seller`, never by opening `payouts` or `payments` to the seller+audience; and a new `q[<column>_eq]` filter on either ledger model needs that+column in `whitelisted_ransackable_attributes` — a whitelisted association+name does not make its foreign key filterable.