Skip to content

armgit / spree

Public Imported from GitHub
0

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.

Plan operator-configured seller onboarding requirements

Damian Legawiec6a46c7f53b91
diff --git a/CLAUDE.md b/CLAUDE.md
index bcefe902c2..2ff776bd7a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -13,6 +13,7 @@ Use `/project:create-plan` and `/project:update-plan` for plan management.
Active plans (6.0 target, work pending):
- `6.0-multi-vendor-marketplace.md` — Open-source the marketplace core (Seller, OrderGroup-based order splitting, commission engine with EU commission taxation, `SellerTransfer`/`SellerPayout` ledger + pluggable `PayoutProvider`) per spree/spree#13323. 6.0 headline feature; rebuilds the legacy Enterprise multi-seller module as native models on the Cart/Order split. Basic Stripe Connect payouts (Express onboarding + on-fulfillment transfers) ship OSS in the monorepo, alongside the Stripe core gateway pulled in from the standalone `spree_stripe` repo (payment-sessions classes only, likely `spree/core` — decisions.md 2026-07-15); Enterprise keeps refund clawbacks/netting, reconciliation, KYC ops, DAC7 payout reports, facilitator taxes + Shopify/WooCommerce seller apps. **Seller principal + surface (Decision 10, 2026-08-15):** seller staff are `Spree.admin_user_class` (no `SellerUser`; membership by `RoleUser.resource_type`, never `store_id`) on a dedicated `/api/v3/seller` branch — own `seller_api` JWT audience, own `Spree.seller_authentication_strategies` + `/seller/auth/*`, audience-stamped refresh tokens, every endpoint scope-fetched through `current_seller` (store derived from the seller); sellers never call the Admin API and admin controllers are never subclassed into the seller namespace.
+- `6.0-seller-onboarding-requirements.md` — Operator-configured seller onboarding checklist (design finalized 2026-08-18): `Spree::SellerRequirement` = store-scoped STI rows (`acts_as_list`, `active`/`required`, per-kind preferences) over developer-written kinds registered in `Spree.seller_requirements` (same `registers_subclasses_via` + `PreferenceSchema` types-discovery pattern as `DeliveryMethodRule`); three completion families — computed from seller data, attested by the seller, verified by the operator/a provider — the last two through one persisted `Spree::SellerRequirementSubmission` (`pending | accepted | rejected | waived`, optional private file attachment; generic `Attestation`/`OperatorReview`/`Document` kinds); evaluated on read by `Spree::Sellers::Requirements` into `SellerRequirementStatus` value objects (`complete | incomplete | pending | rejected`), never denormalized onto sellers. **Exactly two enforcement points:** `Sellers::SubmitForReview` (new; `onboarding → ready_for_review`, `auto_approve_sellers` store preference chains into Approve) and `Sellers::Approve` (refuses unless `override_requirements: true`, recorded on the event); post-approval drift is flagged, never enforced (`sellable?` unchanged, payouts gated by the provider). `Sellers::StartOnboarding` on invitation acceptance, `Sellers::ReopenOnboarding` for send-back. Admin API `/admin/seller_requirements` (+`/types`) under `write_sellers`, `include=onboarding` on sellers, submission accept/reject/waive; seller branch `GET /seller/onboarding`, `POST /seller/onboarding/submit_for_review`, `POST /seller/requirements/:id/submissions`. Defaults provisioned per store (`provision_defaults` + seed); empty = nothing required. **Constraints now:** no `Seller#onboarding_completed?`-style methods or step-done columns on `spree_sellers` — new admission checks are kinds (or `validate` hooks on the seller workflows), per-seller check state is a submission; nothing but the two workflows reads the checklist as a gate.
- `6.0-cart-order-split.md` — Cart/Order model separation, dual-FK owner everywhere (`cart_id`/`order_id` exactly-one, `#owner` as method — NOT polymorphic), idempotent copy-on-completion (`Order#cart_id` unique, order-before-payment), Order state machine removed (Checkout::Requirements for steps; payment/fulfillment statuses derived-then-persisted via one recompute service). **Shipped to 6-0-dev (feature/6-0-core-rewrite Waves 1+5):** Cart owns checkout end to end, machine + `spree_orders.state` gone, `Carts::Complete` three-phase pipeline live, `Orders::UpdateStatuses` sole status writer; only Wave 7 data migration (incomplete orders → carts) remains
- `6.0-admin-api.md` — Admin REST API conventions, auth, endpoint list (~300 endpoints)
- `6.0-admin-spa.md` — React admin architecture, extension points, table registry, i18n + server-error mapping
diff --git a/docs/plans/6.0-multi-vendor-marketplace.md b/docs/plans/6.0-multi-vendor-marketplace.md
index e041deeb3b..2012364adf 100644
--- a/docs/plans/6.0-multi-vendor-marketplace.md
+++ b/docs/plans/6.0-multi-vendor-marketplace.md
@@ -299,7 +299,7 @@ end
- *Capability* is the permission catalog — the same `read_*`/`write_*` vocabulary, through the same `ScopedAuthorization` key gate. Adopts the RBAC plan's settled direction: `Role#audience` (`staff` | `seller`); a **seller-grantable catalog subset** marked at `register_resource` (products, orders, fulfillments, stock, returns, exports/imports, analytics — never `settings`, `staff`, `api_keys`, commissions); the roles editor filters its grid by audience; assignment and invitation guards pair audience with resource type. Seller roles are defined by the operator (role names are globally unique — sellers assign their people to tiers, they do not define roles). Two seller-only catalog resources: `seller_profile` (own profile, branding, addresses, onboarding tasks) and read-only `payouts` (the seller's ledger view). `Spree::Ability` gains a `resource:` option (default the store) so the seller branch builds its ability from `role_users` where `resource: current_seller` — the "seller-side ability" the RBAC plan deferred here.
- The legacy `PermissionSets::SellerUser` baseline survives only as the **seeded default seller role's key set** (`write_products`, `write_orders`, `write_fulfillments`, `write_stock`, `write_returns`, `write_exports`, `write_seller_profile`, `read_payouts`). "No commission management / no channel publication / no self-approve / no stock-location create" are endpoints that do not exist on the seller branch, not ability rules. `#13323`'s "manage permissions (via code)" = seeds or the roles API, per the RBAC plan.
- `Spree::UserRoles` gains `has_many :sellers, through: :role_users, source: :resource, source_type: 'Spree::Seller'` beside `stores`; the seller branch's `/me` returns the seller memberships so a panel can pick its context. `AdminUserMethods#can_be_deleted?` reasons about `Store.current.users` — the seller branch needs its own "last owner of this seller" rule.
-- **Onboarding checklist — the registry is core, Enterprise contributes tasks.** Core ships a lightweight task registry (task key + completion check + required flag) and the core tasks: accept ToS, complete profile/branding, billing + returns addresses, at least one delivery method, at least one product. `submit_for_review` requires all required tasks complete (ports the legacy `onboarding_completed?` guard — without a checklist the guard has nothing to check, and sellers can't see what's missing). Extensions **register additional tasks** into the same registry: the monorepo Stripe gateway adds "connect your Stripe account" (Express onboarding); Enterprise adds KYC verification follow-through and Shopify/Woo store connection — the paid value is in *those tasks*, not in the tracker. The seller dashboard and the operator's onboarding-progress view (the n/m column in today's Enterprise) both render from the registry.
+- **Onboarding checklist — superseded 2026-08-18 by `6.0-seller-onboarding-requirements.md`.** The "lightweight task registry" below became an operator-configured model (`Spree::SellerRequirement` rows over registered kinds, persisted `SellerRequirementSubmission` for attested/verified checks, `Sellers::SubmitForReview` + `Approve` as the only gates); the paragraph is kept for the intent it records. Original text: **Onboarding checklist — the registry is core, Enterprise contributes tasks.** Core ships a lightweight task registry (task key + completion check + required flag) and the core tasks: accept ToS, complete profile/branding, billing + returns addresses, at least one delivery method, at least one product. `submit_for_review` requires all required tasks complete (ports the legacy `onboarding_completed?` guard — without a checklist the guard has nothing to check, and sellers can't see what's missing). Extensions **register additional tasks** into the same registry: the monorepo Stripe gateway adds "connect your Stripe account" (Express onboarding); Enterprise adds KYC verification follow-through and Shopify/Woo store connection — the paid value is in *those tasks*, not in the tracker. The seller dashboard and the operator's onboarding-progress view (the n/m column in today's Enterprise) both render from the registry.
- **Storefront visibility**: only `approved` sellers (and their products) are exposed; `holiday_mode_until` in the future hides the seller's products from sale (purchasability gate, not catalog deletion).
**Columns added to existing tables** (the complete list — everything else in this plan is new tables):
diff --git a/docs/plans/6.0-seller-onboarding-requirements.md b/docs/plans/6.0-seller-onboarding-requirements.md
new file mode 100644
index 0000000000..09964488f4
--- /dev/null
+++ b/docs/plans/6.0-seller-onboarding-requirements.md
@@ -0,0 +1,252 @@
+# Seller Onboarding Requirements
+
+**Status:** Phase 1-3 implemented (2026-08-18) — core models, kinds, evaluator, workflows, Admin API + SDK, and the operator dashboard. Remaining: the seller-facing `/api/v3/seller` endpoints (ride with the marketplace plan's seller branch), the payout-account kind (Phase 3b), the `DeliveryMethod` kind (Phase 3), and the developer guide
+**Target:** Spree 6.0
+**Depends on:** `6.0-multi-vendor-marketplace.md` (Phase 1 — `Spree::Seller`, lifecycle workflows, the `/api/v3/seller` branch), `6.0-service-workflows.md`, `6.0-admin-rbac.md`, `6.0-integrations-admin.md` (the `PreferenceSchema` types-discovery pattern)
+**Author:** Damian Legawiec
+**Last updated:** 2026-08-18
+
+## Summary
+
+A marketplace admits a seller only once that seller has done what the operator asks of it — accepted the terms, filled in a profile, given billing and returns addresses, connected a payout account, listed something, sometimes proven a business registration by hand. The previous marketplace module hard-coded that list as a Ruby method on the seller: the operator could not add, drop, reorder or relax a step, and a developer who needed a new check had to override the whole method. This plan replaces it with **`Spree::SellerRequirement`** — a store-owned, operator-configured checklist where each entry is an instance of a **requirement kind** (a Ruby class developers write and register), evaluated on demand into a status per seller, and enforced at exactly two points: a seller cannot submit for review, and an operator is warned before approving, while a required requirement is unmet. Kinds fall into three families — computed from the seller's own data, attested by the seller, or verified by the operator or an external provider — the latter two through one persisted `Spree::SellerRequirementSubmission` row. The marketplace plan already reserved the slot ("onboarding task registry + core tasks"); this plan is that registry, made configurable.
+
+## Key Decisions (do not deviate without discussion)
+
+1. **Requirements are operator-configured rows, not a code-only registry.** `Spree::SellerRequirement` is a store-scoped STI model (`SingleStoreResource`, `acts_as_list scope: :store`, `active`, `required`, per-kind preferences). Kinds are STI subclasses registered in `Spree.seller_requirements` and discovered through `registers_subclasses_via` + `PreferenceSchema`, exactly as `DeliveryMethodRule` and `PaymentMethod` kinds are. The operator picks a kind from the types list, configures it, orders it, and switches it on, off, required or optional — none of that is code. `Spree.store_setup_tasks` stays a code-only registry: the merchant's own Getting Started list has no operator above it to configure.
+2. **Evaluation is computed on read, through one evaluator, into value objects.** `Spree::Sellers::Requirements.new(seller)` walks the store's active requirements, drops the ones a kind says do not apply, and returns `Spree::SellerRequirementStatus` value objects (`complete | incomplete | pending | rejected`). Nothing about completion is denormalized onto `spree_sellers` — a column would go stale the moment a product is deleted, and the store setup checklist proved on-read is cheap enough for a detail view.
+3. **Three completion families, one optional persisted row.** A kind is *computed* (`satisfied?(seller)` reads seller data — addresses, products, terms), *attested* (the seller ticks it) or *verified* (an operator or a provider confirms it). The last two need somewhere to keep "who said what, when": `Spree::SellerRequirementSubmission` (`pending → accepted | rejected`, plus `waived` when the operator excuses one seller). Computed kinds never create one. The base class treats a latest `accepted`/`waived` submission as satisfied, so a kind that needs no custom logic — the generic `Attestation` and `OperatorReview` kinds — is a name and a description in the operator's own words.
+4. **Two enforcement points, no more.** `Spree::Sellers::SubmitForReview` refuses while a required, active, applicable requirement is not `complete`. `Spree::Sellers::Approve` refuses the same way unless called with `override_requirements: true` — the operator's deliberate "I know this seller" — recorded in the `seller.approved` event payload. Optional requirements never block anything; they are shown as recommended. Nothing else in core reads the checklist as a gate: `Seller#sellable?` stays `approved? && !on_holiday?`, and an approved seller who later drifts out of compliance (terms updated, payout account restricted) is *shown* as such, never automatically suspended — that is the account-health operations layer the marketplace plan keeps in Enterprise. Payouts are gated by the payout provider itself (a transfer needs a connected account), not by the checklist, so a payout-account kind informs the seller and the operator without becoming a second enforcement point.
+5. **Developers extend by writing a kind, or by a workflow hook — never by overriding the checklist.** A configurable kind (a subclass + registration + i18n name) appears in the operator's picker and is the right home for anything reusable — a payout account, an external store connection, a tax-id check. A one-off rule that has no operator-facing configuration goes on `sellers.submit_for_review.validate` / `sellers.approve.validate` (the workflows already declare `validate` hooks). There is no `onboarding_tasks_list` method to override and none will be added.
+6. **Automatic approval is a store preference, off by default.** `auto_approve_sellers` (boolean, on `Spree::Store`) makes `SubmitForReview` continue into `Approve` in the same call once every required requirement is complete. Born on the store per `6.0-store-scoped-configuration.md`; never a global.
+8. **Configuration is picked, never typed (2026-08-19).** Two rules for a kind's configuration form. A **fixed** answer that is the same for every marketplace is a constant the operator is *shown*, not a preference they fill in (`Document::ACCEPTED_CONTENT_TYPES`). A **reference** to other records is a join table plus an autocomplete, never keys or ids in a comma-separated box — the generic array editor is for short tokens, and its own comment says so. Both were free-text fields first, and both failed the same way: a typo produced no error and no match, which for `RequiredCustomFields` meant a compliance check silently satisfied by every seller. Kinds declare association-backed config through `additional_permitted_attributes`, the types endpoint reports it as `association_fields`, and the dashboard maps the field name to a picker — so a kind an extension adds gets a real picker by naming its field, and one the dashboard has never heard of still renders its preference schema.
+
+7. **The default set is provisioned per store, and empty means nothing is required.** `Spree::SellerRequirement.provision_defaults(store)` writes the six core rows in a fixed order; `Seeds::SellerRequirements` calls it for the seeded store. A store whose operator deletes every row has sellers who can submit for review immediately — that is a configuration, not a fallback path, so no code re-derives defaults at read time.
+
+## Design Details
+
+### Vocabulary
+
+| Term | Meaning |
+|---|---|
+| **Requirement kind** | A Ruby class (`Spree::SellerRequirements::AcceptTerms`) — the check logic plus a preference schema. Registered in `Spree.seller_requirements`. |
+| **Requirement** | A `Spree::SellerRequirement` row: one configured instance of a kind on one store, with a position and `active`/`required` flags. |
+| **Status** | `Spree::SellerRequirementStatus`, the evaluated result of one requirement for one seller — a value object, never persisted. |
+| **Submission** | `Spree::SellerRequirementSubmission`, the persisted record of a seller attesting, an operator verifying or waiving, or a provider reporting on one requirement for one seller. |
+| **Onboarding** | The seller's `onboarding` status plus the checklist evaluated for it. `GET /seller/onboarding` and the admin `onboarding` include both render the same evaluator output. |
+
+### `Spree::SellerRequirement`
+
+```ruby
+class Spree::SellerRequirement < Spree.base_class
+ include Spree::SingleStoreResource
+ include Spree::PreferenceSchema
+ include Spree::Metadata
+
+ has_prefix_id :selreq
+ acts_as_list scope: :store
+
+ belongs_to :store, class_name: 'Spree::Store', inverse_of: :seller_requirements
+ has_many :submissions, class_name: 'Spree::SellerRequirementSubmission', dependent: :destroy
+
+ attribute :active, :boolean, default: true
+ attribute :required, :boolean, default: true
+
+ validates :type, presence: true
+ validate :type_must_be_registered
+ # Most kinds make sense once per store; the generic free-text kinds
+ # (Attestation, OperatorReview) opt out with `allow_multiple?`.
+ validates :type, uniqueness: { scope: [:store_id, *spree_base_uniqueness_scope] }, unless: -> { self.class.allow_multiple? }
+ validates :name, presence: true, if: -> { self.class.allow_multiple? }
+
+ registers_subclasses_via { Spree.seller_requirements }
+
+ scope :active, -> { where(active: true) }
+ scope :required, -> { where(required: true) }
+
+ # Operator label; falls back to the kind's localized name.
+ def display_name = name.presence || self.class.human_name
+
+ # --- the extension contract -------------------------------------------
+
+ # Whether the check applies to this seller at all (e.g. a payout-account
+ # kind that only applies once the store has a payout provider).
+ def applicable?(_seller) = true
+
+ # Computed kinds override this. The default answers from the latest
+ # submission, which is what the attested/verified families need.
+ def satisfied?(seller) = latest_submission(seller)&.accepted_or_waived? || false
+
+ # `pending` when a submission is under review or a provider flow is in
+ # flight; `rejected` when the operator sent it back. Kinds override to
+ # read their own source (a provider account's state, for instance).
+ def status_for(seller)
+ return 'complete' if satisfied?(seller)
+ case latest_submission(seller)&.status
+ when 'pending' then 'pending'
+ when 'rejected' then 'rejected'
+ else 'incomplete'
+ end
+ end
+
+ # Somewhere for the seller to go — a hosted onboarding link, for
+ # example. Nil for kinds the seller completes inside their own panel.
+ def action_url(_seller) = nil
+
+ # Whether the seller can create a submission (attest / mark done). False
+ # for computed kinds, where "done" is derived and a submission is noise.
+ def self.accepts_submissions? = false
+ # Whether a seller's submission waits for the operator (`pending`) or is
+ # accepted on creation.
+ def self.reviewed_by_operator? = false
+ def self.allow_multiple? = false
+end
+```
+
+Columns (`spree_seller_requirements`): `store_id` (not null), `type` (not null), `name`, `description` (text; both are the operator's copy, shown to sellers), `position` (integer, not null, default 0), `active` (boolean, not null, default true), `required` (boolean, not null, default true), `preferences` (text), `metadata` (json/jsonb), timestamps. Index `(store_id, position)`. No `deleted_at`: a requirement the operator drops takes its submissions with it, and a seller's history of "did they accept the old terms" lives on the seller (`terms_accepted_at`) and in the events, not here.
+
+Kind i18n keys: `seller_requirement_types.<api_type>.name` / `.description`, mirroring `delivery_method_rule_types`.
+
+### Kinds shipped in core
+
+| Kind | Family | Complete when | Preferences |
+|---|---|---|---|
+| `AcceptTerms` | computed | `terms_accepted_at` present, and on/after `terms_effective_from` when set — bumping that date asks every seller again | `terms_effective_from` (date, nullable) |
+| `CompleteProfile` | computed | `name` present plus each ticked extra | `require_about`, `require_logo`, `require_cover_photo`, `require_contact_email` (booleans) |
+| `BillingAddress` | computed | `billing_address` persisted | — |
+| `ReturnsAddress` | computed | `returns_address` persisted | — |
+| `MinimumProducts` | computed | `seller.products.count >= minimum_count` | `minimum_count` (integer, default 1) |
+| `RequiredCustomFields` | computed | every chosen custom-field definition has a value on the seller | none — definitions are **joined rows** (`spree_seller_requirement_custom_fields`), picked from an autocomplete over `Spree::Seller` definitions. Never stored keys: a renamed definition keeps its id, a deleted one takes its row with it, and a stored `namespace.key` would survive both, match nothing, and count as satisfied for every seller — a compliance check failing open |
+| `Attestation` | attested | seller has an accepted submission | — (label + description are the row's `name`/`description`; `allow_multiple?`) |
+| `OperatorReview` | verified | latest submission `accepted` (or `waived`) | — (`allow_multiple?`, `reviewed_by_operator?`) — "we will verify your VAT number": the seller marks it done with a note/reference, the operator confirms |
+| `Document` | verified | latest submission `accepted` (or `waived`) and it carries a file | none — `Document::ACCEPTED_CONTENT_TYPES` is fixed (PDF, images, Word) and **told** to the operator, never asked: the answer is the same for every marketplace, and typing MIME types is a way to get `image/jpg` wrong and accept nothing. `allow_multiple?`, `reviewed_by_operator?`; one row per document the operator wants, each with its own name and description; the file lives on the submission |
+| `DeliveryMethod` | computed | at least one active seller-owned delivery method | — ; ships with the marketplace plan's Phase 3 (seller-owned delivery methods do not exist before that) |
+
+Provisioned by default (in this order): `AcceptTerms`, `CompleteProfile`, `BillingAddress`, `ReturnsAddress`, `MinimumProducts`, and `DeliveryMethod` once it exists. All `active`, all `required`. `RequiredCustomFields`, `Attestation`, `OperatorReview` and `Document` are never provisioned — they only mean something once the operator has written what they ask for.
+
+Kinds shipped by other gems, not core: the monorepo Stripe gateway (`spree/providers/stripe`) adds a **payout account** kind (`satisfied?` = connected account can receive transfers, `status_for` = `pending` while the provider still lists outstanding requirements, `action_url` = the hosted onboarding link, `applicable?` only when the store has that payout provider configured) — shipped with the marketplace plan's Phase 3b. Enterprise adds its KYC follow-through and external store connection kinds. Their paid value is in the kind; the checklist that renders them is this plan.
+
+### `Spree::SellerRequirementSubmission`
+
+```ruby
+class Spree::SellerRequirementSubmission < Spree.base_class
+ include Spree::HasStatus
+ include Spree::Metadata
+
+ has_prefix_id :selsub
+ publishes_lifecycle_events
+
+ belongs_to :seller, class_name: 'Spree::Seller', inverse_of: :requirement_submissions
+ belongs_to :requirement, class_name: 'Spree::SellerRequirement', inverse_of: :submissions
+ belongs_to :submitted_by, class_name: Spree.admin_user_class.to_s, optional: true
+ belongs_to :reviewed_by, class_name: Spree.admin_user_class.to_s, optional: true
+
+ has_status :pending, :accepted, :rejected, :waived
+
+ validate :requirement_belongs_to_sellers_store
+end
+```
+
+Columns: `seller_id`, `seller_requirement_id`, `status` (no default — the creating workflow sets it), `submitted_by_id`, `reviewed_by_id`, `reviewed_at`, `note` (text — the seller's), `review_note` (text — the operator's), `reference` (string — an external id, e.g. a provider account), `metadata`, timestamps. Plus `has_one_attached :file` on `Spree.private_storage_service_name` — the `Document` kind requires it, `OperatorReview` allows it, everything else ignores it; the file is served through signed URLs on the admin and seller branches only, never the store branch. Index `(seller_id, seller_requirement_id, created_at)`. The latest row per pair is the one that counts; older rows are the audit trail. Store is derived through the seller — never a header.
+
+Transitions are workflows, never callbacks: `Spree::SellerRequirementSubmissions::Create` (seller side; lands `pending` when the kind is `reviewed_by_operator?`, `accepted` otherwise), `::Accept`, `::Reject` (with `review_note`; if the seller is `ready_for_review`, continues into `Sellers::ReopenOnboarding` — something must be redone, so the seller goes back to onboarding with the note), `::Waive` (operator excuses one seller from one requirement; only meaningful for a required requirement, and visible as waived everywhere the checklist renders). Each declares `validate` + `after_*` hooks and publishes `seller_requirement_submission.{created,accepted,rejected,waived}`.
+
+### Evaluation
+
+```ruby
+Spree::Sellers::Requirements.new(seller)
+ .statuses # => [Spree::SellerRequirementStatus, ...] in position order, applicable ones only
+ .blocking # => statuses that are required and not complete
+ .met? # => blocking.empty?
+ .progress # => { done:, total:, percentage: } over required + optional
+```
+
+`Spree::SellerRequirementStatus` (`ActiveModel::Model` + `Attributes`, like `Spree::SetupTask`): `id` (the requirement's prefixed id), `kind` (api_type), `name`, `description`, `required`, `status`, `action_url`, `submission` (the latest, or nil). **The seller keeps track of its own progress (revised 2026-08-19):** `Spree::Seller#onboarding_requirements`, `#onboarding_progress` (`{ done, total, percentage }`), `#onboarding_percentage` and `#onboarding_complete?` — computed on read through the evaluator, memoized per instance and cleared on `reload`, mirroring `Store#setup_tasks`. Computed, never stored: a column would be wrong the moment a product was deleted or a document sent back. The admin seller serializer carries `onboarding_progress` and `onboarding_complete` on **every** row — list and profile — so the operator's list shows "n of m done" over a bar as the legacy admin did. It stays cheap because the store's checklist is one set of rows shared by every seller on a page (eager-loaded through `store: :seller_requirements`, and the evaluator reads the loaded association only when the caller preloaded it — never a cache it merely happens to find), submissions are read through the seller (one small association per row, never the store-wide set per requirement), and the seller memoizes its product count so the operator's column and the minimum-products kind share one `COUNT`. Measured: a 25-row list costs the same number of queries with the checklist as it did without it. The requirement rows themselves, with their submissions, stay on the heavier `GET /sellers/:id/onboarding` — a list needs the number, not the rows behind it. Workflows keep calling `Spree::Sellers::Requirements` directly, never the model readers, and never trust a preloaded association.
+
+### Seller lifecycle changes
+
+```text
+pending → invited → onboarding → ready_for_review → approved
+ ▲ │
+ └── reopen ────┘
+```
+
+- `Spree::Sellers::StartOnboarding` (new) — `invited → onboarding`; run by a subscriber on `invitation.accepted` when the invitation's resource is a seller (the marketplace plan's "acceptance fires `start_onboarding`"). Publishes `seller.onboarding_started`.
+- `Spree::Sellers::SubmitForReview` (new) — `onboarding → ready_for_review`. Steps: `ensure_submittable`, `ensure_requirements_met` (reads the evaluator; fails with `:requirements_incomplete` carrying the blocking statuses), `run_hooks :validate`, `mark_ready_for_review`, `run_hooks :after_submit`, event `seller.submitted_for_review`; when `store.preferred_auto_approve_sellers`, calls `Sellers::Approve` after its own transaction. Hooks: `validate`, `after_submit`.
+- `Spree::Sellers::ReopenOnboarding` (new) — `ready_for_review → onboarding` with an optional `note`; the operator's "please fix and resubmit". Publishes `seller.onboarding_reopened`.
+- `Spree::Sellers::Approve` (existing) gains `override_requirements: false` and the `ensure_requirements_met` step; when overridden the event payload and `seller.metadata` do not change — the override is recorded on the event only, since the requirements themselves keep answering truthfully.
+- `Spree::Seller` gains `has_many :requirement_submissions` and the memoized `onboarding_requirements`, `onboarding_complete?`, `onboarding_progress` readers. No new status values.
+
+### Emails
+
+`Spree::SellerMailer` (in `spree_emails`, driven by `Spree::SellerEmailSubscriber`) gains `onboarding_reopened` (to the seller, carrying the note) and `submission_rejected` (to the seller, carrying `review_note`); store staff get `seller_ready_for_review` on `seller.submitted_for_review`. All honor `store.preferred_send_seller_transactional_emails`.
+
+### Admin API
+
+- `GET/POST/PATCH/DELETE /api/v3/admin/seller_requirements` (+ `GET /seller_requirements/types` — kind list with `preference_schema`, `accepts_submissions`, `reviewed_by_operator`, `allow_multiple`; PATCH accepts `position`, `active`, `required`, `name`, `description`, `preferences`). Under the `sellers` permission catalog resource (`write_sellers`): who configures admission is who admits.
+- `onboarding_progress` + `onboarding_complete` on the admin seller serializer (every list row and the profile); `GET /api/v3/admin/sellers/:id/onboarding` — the evaluator output as `{ status, progress, requirements: [...] }` with each requirement's latest submission.
+- `GET /api/v3/admin/sellers/:id/requirement_submissions`, `PATCH .../requirement_submissions/:id/accept|reject|waive`, `POST .../requirement_submissions` (operator waiving up front is a `POST` with `status: waived` through the `Waive` workflow).
+- `PATCH /api/v3/admin/sellers/:id/approve` accepts `override_requirements`; `PATCH /sellers/:id/reopen_onboarding` accepts `note`.
+- Every lookup scope-fetches through `current_store.seller_requirements` / `current_store.sellers` — a requirement id from another store is a 404.
+
+### Seller API (`/api/v3/seller`, Decision 10 branch)
+
+- `GET /seller/onboarding` — `{ status, progress, requirements: [{ id, kind, name, description, required, status, action_url, submission }] }`; the panel's checklist and progress bar render from it and nothing else.
+- `POST /seller/onboarding/submit_for_review` → `SubmitForReview`; 422 with `details.requirements` naming the blocking ids.
+- `POST /seller/requirements/:id/submissions` (`note`, `reference`, `file` as a direct-upload signed blob id — the same path CSV imports use) → `SellerRequirementSubmissions::Create`; 422 when the kind does not `accepts_submissions?` or requires a file that is missing.
+- `PATCH /seller/profile` accepts `accept_terms: true` (sets `terms_accepted_at`) — the `AcceptTerms` kind reads it; there is no separate terms endpoint.
+- Authorized by `read_seller_profile` / `write_seller_profile`; scoped by `current_seller`.
+
+### Dashboard
+
+- **Settings → Marketplace → Seller requirements** (`/settings/seller-requirements`): a `<ResourceTable>` with drag reorder (`acts_as_list` ⇒ dnd-kit, per the dashboard rules), switches for active/required, an "Add requirement" picker over `/types`, and a sheet whose form is rendered from the kind's `preference_schema` (the same generic preference form the payment-method and integration pages use) plus `name`/`description`.
+- **Seller detail**: an *Onboarding* card — progress, the checklist with status badges, pending submissions with Accept / Reject (note) / Waive; a *Send back to onboarding* action; Approve shows a destructive-styled confirm listing the unmet required requirements when overriding.
+- **Sellers index**: an *Onboarding* column — "n of m done" over a progress bar, from the serializer's `onboarding_progress`, as the legacy admin's table showed it.
+- **Seller profile**: the *Onboarding progress* card is collapsible (open while something is outstanding, folded once complete), headed by "All done 🎉" or "n / m done", with the bar and the requirement list carrying Done / Pending / Under review / Sent back / Waived badges — the legacy `_onboarding_status` partial brought over, plus the operator's accept / send back / waive actions on rows that need them. The header also shows "n / m done" beside the status badge while the seller is still working through the list.
+- New i18n keys land in every locale file, per the dashboard rules.
+
+### Extension guide (docs)
+
+`docs/v6/developer/marketplace/seller-requirements.mdx`: writing a kind (subclass, `satisfied?`/`applicable?`/`status_for`/`action_url`, preferences, i18n, registration in `Spree.seller_requirements`), when to prefer a `validate` hook instead, and how a provider kind reports `pending` from a webhook (a submission with `reference` + status, updated by the provider's own subscriber).
+
+## Migration Path
+
+New OSS code — no in-place migration for existing stores. Steps, each shippable:
+
+1. **Core**: `Spree::SellerRequirement` + STI kinds, `Spree::SellerRequirementSubmission`, evaluator + value object, `Spree.seller_requirements` registry, the four submission workflows, `StartOnboarding` / `SubmitForReview` / `ReopenOnboarding`, the `Approve` change, `auto_approve_sellers` preference, `provision_defaults` + `Seeds::SellerRequirements`, events, mailer additions, factories, specs.
+2. **API**: admin controllers + `types`, the `onboarding` include on the admin seller serializer, seller-branch endpoints, serializers with typelizer output, integration specs → OpenAPI, SDK regeneration.
+3. **Dashboard**: settings page, seller detail card, index column, locales.
+4. **Providers**: the payout-account kind in `spree/providers/stripe` (with marketplace Phase 3b); `DeliveryMethod` kind with Phase 3.
+5. **Enterprise backfill** (Enterprise-side task): the legacy `preferred_shipping_rates_confirmed` becomes an accepted `Attestation` submission; the legacy `skip_global_onboarding_tasks` per-vendor flag becomes waived submissions; its Stripe check maps onto the payout-account kind.
+
+## Constraints on Current Work
+
+- Never add a hard-coded `onboarding_tasks_list`-style method or a boolean "step done" column on `spree_sellers` — a new admission check is a requirement kind (or a `validate` hook on the seller workflows), and per-seller check state is a `Spree::SellerRequirementSubmission`. The seller's `onboarding_*` readers exist, but they only *read* the evaluator; they never decide anything themselves.
+- Workflows evaluate through `Spree::Sellers::Requirements.new(seller)` — never the seller's memoized readers, and never with `preloaded: true` — so a gate always measures against the database, not a cached association.
+- `SellerOnboardingSubscriber` is registered in `Spree.subscribers` and runs synchronously; a subscriber that is not in that list never runs, and the only spec that proves registration is one that goes through the real event bus (`events: true`).
+- `Sellers::Approve` and `Sellers::SubmitForReview` are the only places that read the checklist as a gate. Storefront purchasability (`Seller#sellable?`), product visibility and payout runs never consult it.
+- Kinds keep their state where it already lives (addresses on the seller, accounts on the provider); the requirement row holds configuration only. A kind that must remember something per seller writes a submission, not a column.
+- Every requirement/submission lookup in a controller goes through `current_store` / `current_seller`; `Spree::StoreScopeGuard` covers both branches.
+- Copy shown to sellers (`name`, `description`) is the operator's; kind names come from i18n. No English in code.
+
+## Resolved Decisions
+
+- **Naming: `Spree::SellerRequirement`** (RESOLVED 2026-08-18). Not `SellerOnboardingRequirement` and not `SellerOnboardingTask`: a requirement keeps evaluating after approval (terms re-acceptance, a restricted payout account), so tying the name to the onboarding phase would be wrong the first time it is read outside it, and "task" reads as a to-do rather than something the operator enforces. The evaluated checklist endpoint keeps the word everyone looks for — `GET /seller/onboarding`.
+- **Persisted submissions ship in 6.0, file upload included** (RESOLVED 2026-08-18). The alternatives were computed kinds only, or submissions without the attachment. Manual verification and document collection are what most marketplaces do first; deferring the row would have left the checklist covering only the trivial checks and made the approve override the sole escape hatch. Accepted cost: one more table, four small workflows, private-storage signed URLs on two API branches.
+- **Approve carries an explicit `override_requirements` flag** (RESOLVED 2026-08-18). Strict refusal would force a configuration dance (waive per seller, or make the requirement optional and back) for the everyday "I know this seller" case; warn-only would let a seller through with no record of anyone choosing to. The flag is deliberate, confirmed in the dashboard with the unmet list shown, and recorded in the `seller.approved` payload.
+- **After approval, a failed required requirement is flagged, never enforced** (RESOLVED 2026-08-18). Rejected: a store preference that suspends non-compliant sellers from a scheduled job (needs a suspension-reason vocabulary and a job now), and folding the checklist into `sellable?` (every listing would evaluate the checklist and purchasability would depend on operator configuration edits). Enterprise account-health operations build on the same evaluator.
+
+## Open Questions
+
+Genuinely deferred — none blocks the design:
+
+1. **Application-time requirements.** The self-serve "become a seller" application (marketplace plan, Store API) collects fields before a seller exists in `onboarding`. Whether the operator configures *that* form from the same rows (a `RequiredCustomFields` requirement doubling as the application schema) or from a separate setting is decided when the application endpoint is designed. Unblocked by: the self-serve application design.
+2. **Per-segment requirement sets.** One checklist per store today. Different requirements per seller country or tier (an EU seller must upload a VAT certificate, a domestic one need not) can arrive as `applicable?` reading seller attributes inside a kind, or as a rule layer on the row. Unblocked by: a real marketplace asking for it — until then `applicable?` is enough.
+3. **Document expiry and periodic re-verification.** A `Document` submission has no validity window; re-asking (yearly insurance certificates) needs an `expires_at` on the submission plus a job that flips the status. Unblocked by: the Enterprise account-health design, which owns the scheduled side.
+
+## References
+
+- `docs/plans/6.0-multi-vendor-marketplace.md` — Seller identity & teams ("Onboarding checklist — the registry is core, Enterprise contributes tasks"), Seller API surface, Phase 1 / 3b.
+- `spree/core/app/models/spree/setup_tasks.rb` — the code-only checklist registry this plan deliberately does not reuse for sellers.
+- `spree/core/app/models/spree/delivery_method_rule.rb`, `spree/core/app/models/concerns/spree/preference_schema.rb` — the STI-kind + types-discovery pattern the requirement model follows.
+- `spree/core/app/workflows/spree/sellers/` — the lifecycle workflows this plan extends.
+- Legacy: `spree_multi_vendor` `Spree::Vendors::Onboarding` concern (the hard-coded list being replaced).
diff --git a/docs/plans/decisions.md b/docs/plans/decisions.md
index fe0d697df7..7fdc7bc0e4 100644
--- a/docs/plans/decisions.md
+++ b/docs/plans/decisions.md
@@ -3575,3 +3575,40 @@ existing tables (warning on instantiation; `default_refund_category` and
/ `type_id` stay as frozen columns — never written — so extensions
referencing the constants fail loudly and the fold step has its source. 6.1
drops the two tables, the two columns and the shells.
+
+## 2026-08-18 — Seller onboarding is an operator-configured requirement checklist, not a code-defined task list
+
+The previous marketplace module decided what a seller must do before approval
+in one Ruby method on the seller. Nothing in that shape lets an operator add,
+drop, reorder or relax a step, and a developer adding a check had to override
+the whole list. Spree 6.0 makes the checklist data: `Spree::SellerRequirement`
+rows owned by the store, each an instance of a registered **requirement kind**
+(an STI class with a preference schema, discovered through the same
+`registers_subclasses_via` + `PreferenceSchema` types endpoint that delivery
+method rules and payment methods use), with `position`, `active` and
+`required`. Kinds complete in three ways — computed from seller data, attested
+by the seller, or verified by the operator or a provider — and the last two
+share one persisted `Spree::SellerRequirementSubmission` row (`pending |
+accepted | rejected | waived`, optional private file). Evaluation happens on
+read through `Spree::Sellers::Requirements`; nothing is denormalized onto
+`spree_sellers`.
+
+**Enforcement is deliberately narrow:** `Sellers::SubmitForReview` refuses
+while a required requirement is unmet, `Sellers::Approve` refuses unless the
+operator passes `override_requirements: true` (recorded on the event), and
+that is all. `Seller#sellable?` does not read the checklist; a payout account
+gates payouts through its provider, not through the checklist; an approved
+seller who later fails a requirement is shown as such, never suspended by
+core. Automatic approval is a store preference (`auto_approve_sellers`, off).
+
+**Why:** the operator, not the developer, owns admission policy, and the
+requirements that matter most in practice — documents, manual business checks,
+payout-account status — are per-seller facts with a reviewer, which a computed
+boolean cannot carry. Two gates keep the checklist an admission tool rather than
+a hidden purchasability rule.
+
+**Consequences:** the marketplace plan's "onboarding task registry" paragraph
+is superseded; `Spree.store_setup_tasks` stays code-only for the merchant's own
+Getting Started list. Never add `Seller#onboarding_completed?`-style predicates
+or step-done columns; a new admission check is a kind or a `validate` hook on
+the seller workflows. Plan: `6.0-seller-onboarding-requirements.md`.