@spree/docs 0.1.182 → 0.1.184

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

@@ -5,7 +5,9 @@ description: Build percentage and fixed-amount discounts, free shipping, BOGO of
 
 ## Overview
 
-Promotions give money off an order — a percentage off, free shipping, or free items added to the cart. A promotion is a campaign definition: **rules** decide when it applies, **actions** decide what it does. When a promotion applies, its actions write [Discount](taxes-discounts-fees.md#discounts) rows on the order.
+A promotion is a campaign: a percentage off, free shipping, or free items in the cart. **Rules** decide when it applies, **actions** decide what it does.
+
+A promotion is a *rule that exists on its own*, set up in advance and lasting across many orders. What lands on any one order is a [Discount](discounts.md) — the record of money actually coming off. The promotion is the campaign; the discount is what a particular customer got.
 
 ```mermaid
 erDiagram
@@ -52,14 +54,13 @@ Promotions can be activated in two ways:
 - **Automatic promotions** — applied on their own when the rules are met (e.g. free shipping on orders over $50)
 - **Coupon code promotions** — applied when a customer enters a valid code during checkout
 
-### How discounts are recorded
+### When promotions compete
 
-Each applied promotion becomes one or more Discount rows on the order — on a specific line item or on a fulfillment, never a loose adjustment. Each row keeps a copy of the coupon code and the configured value ("10% off"), so the order still tells the whole story even if the promotion is deleted later.
+Several promotions can qualify for the same item at once. Spree applies **only the one that saves the customer the most**, and records just that one.
 
-Two things follow from this design:
+Losing candidates aren't stored or tracked — they're simply reconsidered on every cart change. So a promotion that loses today can win tomorrow, when the basket changes, without any bookkeeping to keep straight.
 
-- **Only winners are stored.** When several promotions compete for the same item, Spree picks the one that saves the customer the most and writes only that one. Losing candidates are recomputed on every cart change, so a promotion that loses today can win tomorrow without any bookkeeping.
-- **A discount on the whole order is shared out across the items.** If a customer later returns one item, Spree knows exactly how much of the discount belonged to it.
+What an applied promotion leaves behind on the order is a [Discount](discounts.md) — a permanent record that survives the promotion being edited or deleted.
 
 ## Promotion Attributes
 
@@ -112,7 +113,7 @@ You can also [build your own rules](../how-to/custom-promotion.md) for business-
 
 Actions define what happens when a promotion applies.
 
-### CreateAdjustment
+### Order discount (`CreateAdjustment`)
 
 A discount on the whole order. The amount is distributed proportionally across the line items — there is no single order-level row, so per-item reporting and partial returns always know their share.
 
@@ -120,7 +121,7 @@ A discount on the whole order. The amount is distributed proportionally across t
 
 **Use case:** "10% off your order", "$20 off orders over $100".
 
-### CreateItemAdjustments
+### Item discount (`CreateItemAdjustments`)
 
 A discount on individual line items. Only items that match the promotion's rules receive it — if a Category rule says "Electronics", only electronics are discounted.
 
@@ -128,13 +129,13 @@ A discount on individual line items. Only items that match the promotion's rules
 
 **Use case:** "15% off shoes", "Buy 2+ shirts get 10% off each".
 
-### FreeShipping
+### Free shipping (`FreeShipping`)
 
 Writes a discount on each fulfillment covering its delivery cost. The row is kept even when the cost is zero — its presence is what marks the order as having free shipping.
 
 **Use case:** "Free shipping on orders over $75", "Free shipping with code FREESHIP".
 
-### CreateLineItems
+### Free items (`CreateLineItems`)
 
 Adds specified products to the cart when the promotion is eligible, checking stock first. Items are not removed automatically if eligibility is lost — customers remove them manually.
 
@@ -245,7 +246,7 @@ Automatic promotions need no customer action at all — they are evaluated on ev
 
 ## Related Documentation
 
-- [Taxes, Discounts & Fees](taxes-discounts-fees.md) — the Discount rows promotions write, and manual discounts
+- [Discounts](discounts.md) — the rows promotions write, and manual discounts
 - [Build Custom Promotion Rules & Actions](../how-to/custom-promotion.md) — step-by-step guide to custom rules, actions and adjusters
 - [Calculators](calculators.md) — promotion calculators
 - [Carts](carts.md) — the cart lifecycle promotions act on

package/dist/developer/core-concepts/search-filtering.md

@@ -3,13 +3,11 @@ title: Search & Filtering
 description: "Use Ransack-style query parameters to search, filter, sort, and paginate products, taxons, and other resources through the Spree Store API."
 ---
 
-import { Since } from '/snippets/since.mdx';
-
 ## Overview
 
 Spree provides powerful search, filtering, and sorting capabilities for products and other resources. The Store API supports:
 
-- Full-text search across product names, SKUs, and searchable product metafields
+- Full-text search across product names, SKUs, and searchable custom fields
 - Attribute-based filtering (price range, availability, stock status)
 - Category and taxon filtering
 - Faceted search with filter counts
@@ -276,7 +274,7 @@ curl 'https://api.mystore.com/api/v3/store/products?page=1&limit=24' \
 
 See [Querying](../../api-reference/store-api/querying.md) for the full list of filtering, sorting, and pagination options.
 
-## Search Providers 
+## Search Providers
 
 Spree uses a pluggable search provider architecture. The default provider uses SQL (ILIKE + Ransack). For production catalogs with 1,000+ products, we recommend switching to [Meilisearch](../../integrations/search/meilisearch.md) for typo tolerance, relevance ranking, and faster faceted search.
 

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/store-credits-gift-cards.md

@@ -3,9 +3,6 @@ title: Store Credits & Gift Cards
 description: How Spree models store credits and gift cards — stored value balances, redeemable codes, and checkout usage for refunds, loyalty, and gifting.
 ---
 
-import { Since } from '/snippets/since.mdx';
-
-
 ## Overview
 
 Spree provides two stored value mechanisms that customers can use at checkout: