@spree/docs 0.1.183 → 0.1.185

package/dist/developer/core-concepts/sellers.md

@@ -0,0 +1,210 @@
+---
+title: Sellers
+description: Running a marketplace — vendors with their own catalog and panel, orders split per seller, and commission on every sale.
+---
+
+## Overview
+
+A marketplace sells things it doesn't own. Vendors list their own products, the marketplace takes a cut, and a shopper buying from three vendors at once expects one basket and one payment — not three checkouts.
+
+A **seller** is a vendor on your marketplace: their own products, their own staff, their own orders, and their own panel to work in.
+
+```mermaid
+flowchart TB
+    Customer["One customer, one payment"] --> Group["Order group"]
+    Group --> O1["Order — Seller A"]
+    Group --> O2["Order — Seller B"]
+    O1 --> F1["Seller A ships"]
+    O2 --> F2["Seller B ships"]
+
+    style Group fill:#e3f2fd,stroke:#0077ff
+```
+
+> **INFO:** This is all open source. Sellers, product review, order splitting, commissions and the seller panel ship in the box — you don't need a commercial licence to run a marketplace on Spree.
+
+## The seller lifecycle
+
+A seller isn't simply created and switched on. Bringing a vendor onto a marketplace is a process with a decision at the end of it, and the status reflects where they are in it.
+
+```mermaid
+stateDiagram-v2
+    [*] --> pending
+    pending --> invited : marketplace invites them
+    invited --> onboarding : they accept
+    onboarding --> ready_for_review : they finish the checklist
+    ready_for_review --> approved : marketplace approves
+    ready_for_review --> rejected : sent back
+    rejected --> onboarding : they try again
+    approved --> suspended : paused
+    suspended --> approved : reinstated
+```
+
+| Status | Meaning |
+|---|---|
+| `pending` | Created, nothing sent yet |
+| `invited` | Invitation sent, not yet accepted |
+| `onboarding` | Working through the requirements |
+| `ready_for_review` | Waiting on the marketplace |
+| `approved` | Live — can sell |
+| `rejected` | Sent back, with a reason |
+| `suspended` | Paused, temporarily |
+| `canceled` | Gone |
+
+Only an **approved** seller can sell, and even then not while they're on holiday — sellers can pause their own listings without the marketplace suspending them.
+
+```typescript Admin SDK
+await adminClient.sellers.invite('sel_xxx')
+await adminClient.sellers.approve('sel_xxx')
+await adminClient.sellers.suspend('sel_xxx', { reason: 'Unresolved delivery complaints' })
+```
+
+Status is never set by writing to the field — each move is its own action, so approving a seller can run the checks that belong to approving.
+
+## Onboarding requirements
+
+What a vendor must do before selling differs by marketplace. A hardware marketplace wants insurance documents; a craft marketplace wants a filled-in profile and one product.
+
+So the checklist is **configured, not hardcoded**. Each store defines its own:
+
+```typescript Admin SDK
+const { data: types } = await adminClient.sellerRequirements.types()
+
+await adminClient.sellerRequirements.create({
+  type: 'Spree::SellerRequirements::MinimumProducts',
+  name: 'List at least three products',
+  required: true,
+  preferences: { minimum_count: 3 },
+})
+```
+
+Requirements come in three flavours, which is what lets one mechanism cover very different demands:
+
+| Kind | How it's satisfied |
+|---|---|
+| **Computed** | Automatically, from the seller's own data — a billing address exists, three products are listed |
+| **Attested** | The seller confirms something — accepting terms |
+| **Verified** | The seller submits something and the marketplace rules on it — a document, an operator review |
+
+Shipped out of the box: accepting terms, completing the profile, a billing address, a returns address, and a minimum number of products. Also available are generic document upload, attestation, operator review, and required custom fields.
+
+A seller sees their checklist and its progress:
+
+```typescript Seller SDK
+const onboarding = await sellerClient.onboarding.get()
+
+onboarding.progress    // { done: 3, total: 5 }
+onboarding.requirements.forEach((r) => {
+  r.name      // "Accept the seller terms"
+  r.status    // complete | incomplete | pending | rejected
+  r.required  // whether it blocks approval
+})
+
+await sellerClient.onboarding.submitForReview()
+```
+
+The checklist is **worked out when read**, never stored on the seller. So a requirement added next month applies immediately to everyone, and nothing has to be backfilled.
+
+> **NOTE:** The checklist is enforced at exactly two moments — submitting for review, and approval. Approval refuses while a required item is outstanding, unless an operator deliberately overrides it.
+> 
+> Afterwards it's advisory. If a seller's insurance certificate lapses, that's flagged for the marketplace to act on; it does not silently stop their sales mid-trade.
+
+## Products belong to sellers
+
+A product can name a seller. No seller means it's the marketplace's own stock — a marketplace that also sells directly is a normal setup.
+
+Sellers don't publish; they **submit**, and the marketplace decides. That review flow, and the statuses behind it, are covered in [Products](products.md#seller-submissions).
+
+```typescript Seller SDK
+const product = await sellerClient.products.create({ name: 'Handmade Vase' })
+await sellerClient.products.submit(product.id)
+```
+
+Stores that trust their vendors can turn auto-approval on and skip the queue.
+
+## One checkout, several sellers
+
+This is the part that makes a marketplace different from a shop, and it's worth understanding before you build a storefront against it.
+
+A customer fills one basket, enters one address, and pays once. But each seller needs their own order — they fulfil separately, get paid separately, and must never see each other's business.
+
+So at completion, a checkout spanning several sellers becomes an **order group**: one container holding one order per seller.
+
+```mermaid
+erDiagram
+    OrderGroup ||--o{ Order : "one per seller"
+    OrderGroup ||--o{ Payment : "one payment"
+    Payment ||--o{ PaymentSplit : "apportioned"
+    Order }o--|| Seller : "belongs to"
+    Order ||--o{ Fulfillment : "shipped by that seller"
+```
+
+| Level | Owns |
+|---|---|
+| **Order group** | The customer, the addresses, the payment, the combined totals |
+| **Order** | One seller's items, fulfillments and money lines |
+
+The single payment is apportioned across the child orders as **payment splits**, so each seller's share of one charge is recorded exactly — which is what makes per-seller refunds and settlement possible later.
+
+Two details worth knowing:
+
+- **Group totals are added up, not divided.** The group's total is the sum of its children, so it always agrees with them.
+- **Delivery and order-level fees are shared out by item value**, so a seller whose goods made up most of the basket carries most of the delivery charge.
+
+> **WARNING:** A storefront must handle the possibility of an order group. Completing a cart may yield one order or several, and a customer's order history should show the group as one purchase rather than confronting them with three orders they don't remember placing separately.
+
+## Commission
+
+Commission is what the marketplace charges for the sale — configured as **rates**, and recorded per sale as immutable **commission lines**.
+
+```typescript Admin SDK
+const { data: lines } = await adminClient.commissionLines.list({
+  filter: { seller_id_eq: 'sel_xxx' },
+})
+```
+
+Three things are worth knowing here; the rest is on its own page.
+
+- **Rates are tried in list order**, and the first whose rules match wins. A rate with no rules matches everything, so the marketplace default belongs at the bottom.
+- **Commission is charged on the seller's net revenue by default**, after discounts and excluding the customer's tax.
+- **Commission tax follows the seller's jurisdiction**, not the shopper's — the marketplace is selling a service to the vendor, which is a separate supply from the vendor's sale to the customer.
+
+See [Commissions](commissions.md) for rate targeting, the four rule types, per-currency floors and caps, and how a fee is calculated and taxed.
+
+## Payouts
+
+Spree records what each seller earned and what the marketplace charged: the payment splits say what each seller's share of the money was, and the commission lines say what was deducted.
+
+> **WARNING:** **Actually moving money to sellers is not implemented in open source.** There is no payout or transfer ledger here — a seller carries payout *preferences* (how often, and a minimum amount), but nothing acts on them.
+> 
+> Paying vendors means connecting a provider such as Stripe Connect, or building against the payment splits and [commission lines](commissions.md). Scheduled payout runs, refund clawbacks, reconciliation and tax reporting are Enterprise features.
+
+## The seller panel
+
+Sellers get their own application — not access to the marketplace's dashboard. It's a separate API with its own sign-in, and every request is scoped to the seller making it, so no endpoint even takes a seller ID.
+
+That last point is the security property worth relying on: a seller cannot ask for another seller's data, because there's nowhere in the request to name one.
+
+```typescript Seller SDK
+import { createSellerClient } from '@spree/seller-sdk'
+
+const sellerClient = createSellerClient({ baseUrl: 'https://marketplace.example.com' })
+
+await sellerClient.auth.login({ email: 'vendor@example.com', password: '…' })
+
+const { data: orders } = await sellerClient.orders.list()
+await sellerClient.orders.fulfillments.fulfill(orderId, fulfillmentId, {
+  tracking: '1Z999AA10123456784',
+})
+```
+
+Sellers can manage their profile, invite their own team, list and submit products, see and fulfil their orders, manage their stock locations, and work through onboarding. They cannot see other sellers, the marketplace's own catalog, or anything belonging to the store at large.
+
+What a seller's staff may do is governed by [roles](staff-roles.md) owned by the seller — the same permission system as the back office, with a narrower set of keys, so a seller role can never reach store settings.
+
+## Related
+
+- [Commissions](commissions.md) — rates, rules, and what the marketplace charges
+- [Products](products.md#seller-submissions) — the listing review flow
+- [Orders](orders.md) — orders and their statuses
+- [Staff & Roles](staff-roles.md) — how seller teams are governed
+- [Seller API](../../api-reference/seller-api/introduction.md) — the full endpoint reference

package/dist/developer/core-concepts/staff-roles.md

@@ -5,47 +5,80 @@ description: Manage Spree admin users, roles, invitations, and permissions — c
 
 ## Overview
 
-Admin users manage the store via the Admin Panel. They have roles that control what they can access.
+Staff manage a store through the dashboard and the Admin API. What each person can do is decided by the **roles** they hold.
 
 ```mermaid
 erDiagram
-    AdminUser ||--o{ RoleUser : "has many"
-    RoleUser }o--|| Role : "belongs to"
-    RoleUser }o--|| Store : "scoped to"
-    AdminUser ||--o{ Invitation : "invites"
+    Store ||--o{ Role : "owns"
+    Seller ||--o{ Role : "owns"
+    Role ||--o{ RoleUser : "assigned through"
+    AdminUser ||--o{ RoleUser : "holds"
+    Role ||--o{ Invitation : "offered by"
 
-    AdminUser {
-        string id
-        string email
+    Role {
+        string name
+        string description
+        json permissions
+        boolean mutable
     }
-
     RoleUser {
         string role_id
-        string resource_type
-        string resource_id
-    }
-
-    Role {
-        string name
+        string user_id
     }
-
     Invitation {
         string email
         string status
-        string token
         datetime expires_at
     }
 ```
 
-## Roles
+Two things about that shape matter:
+
+**A role belongs to what it governs.** Every role names its owner — a Store for back-office staff, a [Seller](sellers.md) for a marketplace seller's own team. The owner is both who the role belongs to and who it applies to, so a role on a Store is a staff role by construction. Assigning someone a role therefore grants access to that owner and nothing else, which is what keeps one store's staff out of another's data.
+
+Because roles are scoped to their owner, two stores can each define a "Manager" without colliding.
+
+**A role carries its permissions directly.** The role holds a plain list of permission keys, so what a role can do is visible on the role itself rather than assembled from something else at runtime.
+
+## Roles and permissions
+
+A permission key is a verb and a resource — `read_orders`, `write_products`. Roles hold a list of them:
+
+```typescript Admin SDK
+const role = await adminClient.roles.create({
+  name: 'Fulfillment staff',
+  description: 'Can see orders and ship them, nothing else',
+  permissions: ['read_orders', 'write_fulfillments', 'read_products'],
+})
+```
+
+Every grantable key is discoverable, so a permission picker never needs a hardcoded list:
+
+```typescript Admin SDK
+const { data: permissions } = await adminClient.permissions.list()
+```
+
+Keys are grouped so they can be presented sensibly — orders, catalog, marketing, customers, settings, access and analytics.
+
+| Group | Covers |
+|---|---|
+| Orders | Orders, payments, fulfillments, refunds, gift cards, store credit |
+| Catalog | Products, media, categories, collections, stock, publishing |
+| Marketing | Promotions |
+| Customers | Customer accounts and groups |
+| Settings | Store settings, webhooks, integrations |
+| Access | API keys, staff, sellers, commissions |
+| Analytics | The dashboard |
+
+> **NOTE:** **The same vocabulary gates API keys.** A secret key's scopes come from this catalog too, so "what may this integration do" and "what may this person do" are described the same way — there is no second permission system to keep in step.
+
+### The admin role
 
-Admin users can have different roles that control their permissions:
+Each store gets one protected `admin` role meaning *everything in this store*. It can't be renamed, edited or deleted, and it isn't shared between stores — each owner has its own.
 
-| Role | Description |
-|------|-------------|
-| `admin` | Full access to all Admin Panel features |
+A role is deletable only when nothing depends on it: staff assignments and pending invitations have to be moved first, so nobody silently loses access.
 
-> **INFO:** You can create custom roles with specific permissions. See the [Customize Permissions guide](../customization/permissions.md) for details.
+> **INFO:** Roles are pure data. They're created through the dashboard, the Admin API, or seeds — there's no code-level role definition to keep in sync. For record-level rules beyond what keys express, see [Customize Permissions](../customization/permissions.md).
 
 ## Creating Admin Users
 

package/dist/developer/core-concepts/taxes.md

@@ -165,11 +165,11 @@ Whichever provider is in use, the result is the same: tax lines on the order, in
 
 Business customers are often exempt, and the paperwork is real. Spree records a customer's or company's **tax identifier** — a VAT number, an ABN — and can validate it. Companies can also hold exemption certificates, scoped to the country or state that issued them.
 
-Exemption is decided when tax is worked out, not stored as a flag on the customer, so an expired certificate stops applying by itself. See [Companies & Catalogs](companies-and-catalogs.md).
+Exemption is decided when tax is worked out, not stored as a flag on the customer, so an expired certificate stops applying by itself. See [Companies](companies.md).
 
 ## Related
 
 - [Order totals](order-totals.md) — how tax rolls into what a customer pays
 - [Markets](markets.md) — where tax treatment and provider are chosen
 - [Addresses](addresses.md) — what determines the rate
-- [Companies & Catalogs](companies-and-catalogs.md) — B2B tax identifiers and exemptions
+- [Companies](companies.md) — B2B tax identifiers and exemptions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.183",
+  "version": "0.1.185",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",

package/dist/developer/core-concepts/companies-and-catalogs.md

@@ -1,81 +0,0 @@
----
-title: Companies & Catalogs
-description: How Spree models B2B buyer organizations — a multi-level company tree with members and an address book — and the catalogs that decide what each audience sees and pays.
----
-
-## Overview
-
-A business customer in Spree is a **tree of company nodes**, not a flat account. One node can stand alone — a company with a few members and addresses — or grow into a group: subsidiaries, divisions, regional units, each with its own buyers and ship-to sites.
-
-```mermaid
-erDiagram
-    Company ||--o{ Company : "parent of"
-    Company ||--o{ CompanyMembership : "has many"
-    Company ||--o{ CompanyAddress : "has many"
-    Company ||--o{ CompanyInvitation : "has many"
-    Company ||--o{ TaxIdentifier : "legal entities only"
-    Company ||--o{ TaxExemptionCertificate : "legal entities only"
-
-    Company {
-        string name
-        string kind "company | division"
-        string external_id
-    }
-    CompanyMembership {
-        string role "cosmetic label"
-    }
-    CompanyAddress {
-        string label
-        boolean default_billing
-        boolean default_shipping
-    }
-    CompanyInvitation {
-        string email
-        string token
-        datetime expires_at
-    }
-```
-
-Three ideas carry the whole model:
-
-- **The tree is structure.** `Spree::Company` is self-referential (`parent_id`), store-scoped, and shallow — depth is capped at five levels. How many ship-to sites a node has never dictates how many nodes exist; addresses are just an address book.
-- **Nodes are typed, and the type decides tax.** A `company` node is a legal entity; a `division` is an organizational unit. Tax registrations and exemption certificates exist only on legal entities, and a purchase's tax always resolves through the node's `legal_entity` — for a `company` that is the node itself, and for a `division` it is its nearest `company` ancestor, whose registrations then cover the division's purchases. The walk stops at that first `company` node whether or not it holds any registration, so a subsidiary with no VAT number of its own has none — it never borrows its parent's.
-- **Membership is standing over a subtree.** A `CompanyMembership` joins a customer to a node, and that standing covers the node and everything below it. Any authorization question — "may this customer act for node N?" — is a membership check on N and its ancestors, never an equality check on one node.
-
-## Members and invitations
-
-People join by email, from either side — staff in the dashboard or an existing member on the storefront. An email that matches a store customer becomes a membership immediately; an unknown email becomes a `Spree::CompanyInvitation` — a plaintext-token record with a 30-day expiry, whose invite email links to the storefront acceptance page. Accepting either registers a new account (through the standard customer-creation flow, with the invited email) or binds the invitation to the signed-in customer, and lands as a membership either way.
-
-Memberships stay always-active and always customer-backed: the pending state lives on the invitation, never as a status on the membership.
-
-**In open source, every member can do everything within their standing** — buy, see the subtree's purchases, manage addresses and members. There are no company roles; the `role` string on a membership is a cosmetic label. Finer control (roles, approvals, spending limits) is an Enterprise layer that enforces through the storefront access policy class (`Spree::Dependencies.storefront_access_policy_class`) and the checkout `validate` hooks — injection points that are deliberate no-ops in OSS.
-
-## Purchases
-
-Carts and orders carry a `company_id` pointing at any node — buying *for* a division means pointing at it. A buyer with exactly one membership resolves to it automatically; a buyer with several names the node on their cart (the `company_id` param on cart update, validated against their standing). The node is frozen onto the order at completion, like every other order attribute, so a placed order's tax treatment stays explainable no matter how the tree changes later.
-
-Exemption certificates and the company's tax registration always resolve through `company.legal_entity` — see [Taxes](taxes.md) for how they reach the tax provider.
-
-## Catalogs
-
-A `Spree::Catalog` narrows what an audience sees and — through an optional price list — what they pay.
-
-```mermaid
-erDiagram
-    Catalog ||--o{ CatalogProduct : "assortment"
-    Catalog ||--o{ CatalogAssignment : "audiences"
-    Catalog }o--o| PriceList : "optional pricing"
-    CatalogAssignment }o--|| Company : "or"
-    CatalogAssignment }o--|| CustomerGroup : "or"
-    CatalogAssignment }o--|| Market : "or"
-    CatalogAssignment }o--|| Channel : "or"
-```
-
-- **Assortment** — a positioned product join, and the switch between a catalog's two modes. A *curated* assortment restricts: the audience sees only what's in it. An *empty* assortment is a pricing-only overlay: the attached price list applies and nothing is hidden — which is how "everyone sees the public store, this company just gets special prices" is expressed. An explicit import action copies the price list's products into the assortment when a restrictive catalog should start from the priced range.
-- **Audiences** — assignments to a channel, a customer group, a market, or a company node. A company assignment covers the node's **subtree**: assign the group-wide catalog once at the root, and a branch adds its own extra catalog without re-assigning the shared one.
-- **Visibility** — a buyer resolving to a company node sees the union of the effective catalogs on the node and its ancestors; otherwise their customer group's catalogs apply; otherwise every channel listing (narrowed to the channel's default catalog when one is set). Any effective catalog with an empty assortment lifts the restriction — the union then includes the whole range. Gated storefront access runs first — a login-gated guest never reaches this resolution.
-- **Pricing** — the effective catalogs' price lists are checked nearest node first (the purchase node's own assignments before its parent's), then the ordinary rule-matched price lists, then base prices. A price list attached to a catalog applies *because the catalog applies* — its own rules are not consulted, and it is excluded from generic rule matching so a rule-less list cannot leak to every shopper.
-
-## Storefront self-service
-
-The Store API ships a full company directory for members: their memberships with ancestor paths (`GET /store/account/companies`), node details and renaming, the address book, members and invitations, and the subtree's completed orders. Authorization on every endpoint is **standing plus the access policy** — never roles, never CanCanCan. The deliberate trade-off: within a company, OSS trusts every member; merchants who need restraint layer the Enterprise governance on the same injection points, with no schema changes.