@spree/docs 0.1.177 → 0.1.178

package/dist/developer/customization/quickstart.md

@@ -1,215 +1,242 @@
 ---
 title: Quickstart
 og:title: Spree Customization Quickstart
-description: Recommended ways to customize Spree — store settings, configuration, events, webhooks, dependencies, admin extensions, and decorators as a last resort.
+description: Recommended ways to customize the Spree 6 backend — configuration, workflow hooks, events, checkout steps, providers, dependencies, and decorators as a last resort.
 ---
 
-Spree is a flexible platform allowing you to customize every part of it to suit your business needs. This guide presents customization options **in order of recommendation** - start from the top and only move down if simpler options don't meet your needs.
+Spree is designed to be customized without forking it. This guide presents the options **in order of recommendation** — start at the top and only move down when a simpler option doesn't fit.
 
-## Quick Reference
+> **NOTE:** Business logic is extended through **workflow hooks** rather than by replacing classes wholesale, and the admin is a React application with its own extension points rather than a Rails engine extended through partials.
+
+## Quick reference
 
 | What you want to do | Recommended approach |
-|---------------------|---------------------|
-| Change store settings (currency, zones, languages) | [Store Settings](#store-settings) |
+|---|---|
+| Change store settings (currency, markets, languages) | [Store settings](#store-settings) |
 | Tweak Spree behavior globally | [Configuration](#configuration) |
-| React to model changes (sync, notifications) | [Events & Subscribers](#events-and-subscribers) |
+| Run your own logic inside checkout, cancellation, refunds | [Workflow hooks](#workflow-hooks) |
+| Block an operation from happening | [Workflow hooks](#workflow-hooks) — `validate` |
+| React after something happened (sync, notifications) | [Events & subscribers](#events-and-subscribers) |
+| Add or reorder checkout steps | [Checkout registry](#checkout-steps) |
+| Swap tax, delivery rate, search or fulfillment behavior | [Providers](#providers) |
+| Add searchable/filterable fields | [Search & filtering](#search-and-filtering) |
+| Use your own user model or identity provider | [Authentication](#authentication) |
 | Notify external services | [Webhooks](#webhooks) |
-| Swap core services (cart, checkout, etc.) | [Dependencies](#dependencies) |
-| Add admin menu items | [Admin Navigation](#admin-extensions) |
-| Add sections to admin forms | [Admin Partials](#admin-extensions) |
-| Add searchable/filterable fields | [Ransack Configuration](#search-and-filtering) |
+| Replace a whole workflow or service | [Dependencies](#dependencies) |
 | Add associations/validations to models | [Decorators](#decorators) (last resort) |
 
-**Best for:** Changing currency, shipping zones, languages, and other business settings.
-
-    There's a lot of Store settings you can change in the admin panel without touching the code.
+> **INFO:** **Customizing the admin?** This page covers the backend — models, API and business logic. The Spree 6 admin is a separate React application with its own extension points. See [Dashboard Customization](../dashboard/customization/quickstart.md).
 
-    Go to **Admin > Settings**
-
-    <img src="/images/spree_admin_store_settings.png" alt="Spree Admin Store Settings" />
+**Best for:** currency, markets, delivery zones, languages, and other business settings.
 
+    Most day-to-day configuration is data, not code. Change it in the dashboard under **Settings** — no deploy required.
   <details>
 <summary>Configuration</summary>
 
-**Best for:** Tweaking Spree's behavior globally without modifying source code.
-
-    Global application configuration allows you to customize various aspects of Spree:
+**Best for:** tweaking Spree's behavior globally.
 
     ```ruby config/initializers/spree.rb
     Spree.config do |config|
-      config.allow_guest_checkout = false
-      config.products_per_page = 20
+      config.minimum_password_length = 10
     end
     ```
 
-    Please see [Configuration](configuration.md) section for more information.
+    See [Configuration](configuration.md).
 
 </details>
 
-
   <details>
-<summary>Events and Subscribers</summary>
+<summary>Workflow hooks</summary>
 
-**Best for:** Reacting to model changes, syncing with external services, sending notifications, audit logging.
+**Best for:** running your own logic *inside* a core flow — checkout completion, order cancellation, refunds, fulfillment creation.
 
-    > **INFO:** Events are the **recommended way** to add behavior when something happens in Spree, replacing the need for decorator callbacks.
+    > **INFO:** Hooks are the **headline extension point in Spree 6**. Before them, customizing a flow meant replacing the entire class and keeping your copy in sync with core forever.
 
-    Spree's event system lets you subscribe to events like `order.completed`, `product.updated`, `payment.paid`, etc.:
+    Register a handler against a hook key — `<workflow key>.<hook name>`:
 
-    ```ruby app/subscribers/order_completed_subscriber.rb
-    class OrderCompletedSubscriber < Spree::Subscriber
-      subscribes_to 'order.completed'
+    ```ruby config/initializers/spree.rb
+    Spree.hooks.register('carts.complete.validate') do |flow|
+      flow.reject!('We cannot deliver to this region') unless deliverable?(flow.cart)
+    end
+    ```
 
-      def handle(event)
-        order = Spree::Order.find_by_prefix_id(event.payload['id'])
-        return unless order
+    Pass a class instead of a block for anything longer than a line:
 
-        # Sync to external service, send notification, etc.
-        ExternalService.notify_order_placed(order)
-      end
-    end
+    ```ruby
+    Spree.hooks.register('carts.complete.after_finalize', 'MyApp::PushOrderToERP')
     ```
 
-    **Key benefits:**
-    - Loose coupling - your code doesn't depend on Spree internals
-    - Async by default - keeps requests fast
-    - Easier testing and upgrades
+    There are three families of hook:
 
-    Please see [Events](../core-concepts/events.md) section for more information.
+    | Family | Naming | What it can do |
+    |---|---|---|
+    | **validate** | `validate` | Veto the operation with `flow.reject!(message)` |
+    | **lifecycle** | past tense — `after_finalize`, `after_cancel` | React to what happened; read-only |
+    | **context** | `set_*_context`, `get_provider_data` | Return a hash that gets merged into the flow's data |
 
-</details>
+    Hook keys are validated after boot, so a typo fails startup rather than silently never running.
 
+    See [Services & Workflows](workflows.md) for the full list of flows and their hooks.
+
+</details>
 
   <details>
-<summary>Webhooks</summary>
+<summary>Events and subscribers</summary>
+
+**Best for:** reacting *after* something happened — syncing to external systems, notifications, audit logging.
 
-**Best for:** Notifying external services (ERPs, CRMs, fulfillment systems) when events occur.
+    ```ruby app/subscribers/spree/order_placed_subscriber.rb
+    module Spree
+      class OrderPlacedSubscriber < Spree::Subscriber
+        subscribes_to 'order.placed'
 
-    Webhooks send HTTP POST requests to external URLs when Spree events happen:
+        def handle(event)
+          order = Spree::Order.find_by_prefix_id(event.payload['id'])
+          return unless order
 
-    - Order completed → Notify fulfillment system
-    - Product updated → Sync with PIM
-    - Customer created → Add to CRM
+          MyApp::ERP.push(order)
+        end
+      end
+    end
+    ```
 
-    Configure webhooks in **Admin > Developers > Webhooks** or via the API.
+    **Events or hooks?** A hook runs *inside* the flow and can influence or block it. An event fires *after* the fact and cannot. Reach for an event unless you need to change the outcome.
 
-    Please see [Webhooks](../core-concepts/webhooks.md) section for more information.
+    See [Events](../core-concepts/events.md).
 
 </details>
 
-
   <details>
-<summary>Dependencies</summary>
+<summary>Checkout steps</summary>
 
-**Best for:** Swapping core services, serializers, and abilities with your own implementations.
+**Best for:** adding, removing or reordering checkout steps.
 
-    Spree allows you to replace core classes without modifying them:
+    Spree 6 has no checkout state machine. A cart reports what it still needs, and you can add to that list:
 
     ```ruby config/initializers/spree.rb
-    Spree::Dependencies.cart_add_item_service = "MyCartAddItemService"
-    Spree::Dependencies.cart_remove_item_service = "MyCartRemoveItemService"
+    Spree::Checkout::Registry.register_step(
+      name: :loyalty,
+      before: :payment,
+      satisfied: ->(cart) { cart.metadata['loyalty_number'].present? },
+      requirements: ->(cart) {
+        [{ step: 'loyalty', field: 'loyalty_number', message: 'Loyalty number is required' }]
+      }
+    )
     ```
 
-    This is cleaner than decorating services because you provide a complete replacement rather than patching behavior.
+    Or attach a requirement to an existing step:
 
-    Please see [Dependencies](dependencies) section for more information.
+    ```ruby
+    Spree::Checkout::Registry.add_requirement(
+      step: :payment,
+      field: :po_number,
+      message: 'PO number is required',
+      satisfied: ->(cart) { cart.metadata['po_number'].present? }
+    )
+    ```
 
-</details>
+    Registered requirements appear in the Cart API's `requirements` array, so your storefront renders them without duplicating any rules.
+
+    See [Carts](../core-concepts/carts.md#checkout-requirements).
 
+</details>
 
   <details>
-<summary>Admin Extensions</summary>
+<summary>Providers</summary>
 
-**Best for:** Adding menu items, form sections, dashboard widgets, and other UI elements to the admin panel.
+**Best for:** swapping a whole area of behavior for your own implementation.
 
-    Spree provides declarative APIs for extending the admin without decorators or view overrides:
+    Spree 6 exposes pluggable providers for the domains that vary most between businesses:
 
-    **Navigation API** - Add menu items:
-    ```ruby config/initializers/spree.rb
-    Rails.application.config.after_initialize do
-      Spree.admin.navigation.sidebar.add :brands,
-        label: :brands,
-        url: :admin_brands_path,
-        icon: 'award',
-        position: 35
-    end
-    ```
+    | Provider | Controls |
+    |---|---|
+    | Tax provider | How tax is calculated, per market |
+    | Delivery rate provider | How delivery is priced — flat rates or live carrier rates |
+    | Fulfillment provider | How a delivery type behaves — shipping, digital, pickup |
+    | Search provider | Database or Meilisearch |
+    | Payout provider | Where marketplace payouts go |
 
-    **Partials API** - Add sections to forms:
-    ```ruby config/initializers/spree.rb
-    Spree.admin.partials.product_form << 'spree/admin/products/erp_section'
-    ```
+    Each is a class you register and select on the relevant record, so no conditional code lands in core.
 
-    Please see:
-    - [Admin Navigation](../admin/navigation.md) - For adding menu items
-    - [Admin Partials](../admin/extending-ui.md) - For extending UI
-    - [Admin Tables](../admin/tables.md) - For customizing list views
+    See [Fulfillments](../core-concepts/fulfillments.md#delivery-types) and [Taxes](../core-concepts/taxes.md).
 
 </details>
 
-
   <details>
-<summary>Search and Filtering</summary>
+<summary>Search and filtering</summary>
 
-**Best for:** Making custom fields searchable/sortable in the admin and API.
-
-    Instead of decorating models to add `ransackable_attributes`, use the Ransack configuration API:
+**Best for:** making custom fields searchable and sortable in the dashboard and API.
 
     ```ruby config/initializers/spree.rb
-    Spree.ransack.add_attribute :product, :erp_id
-    Spree.ransack.add_association :product, :brand
+    Spree.ransack.add_attribute(Spree::Product, :erp_id)
+    Spree.ransack.add_association(Spree::Product, :brand)
+    Spree.ransack.add_scope(Spree::Product, :featured)
     ```
 
-    Please see [Search & Filtering](../core-concepts/search-filtering.md#extending-ransackable-configuration) section for more information.
+    See [Search & Filtering](../core-concepts/search-filtering.md).
 
 </details>
 
-
   <details>
 <summary>Authentication</summary>
 
-**Best for:** Using your own user model or authentication system.
+**Best for:** using your own user model or identity provider.
 
-    Spree allows you to use your own authentication system instead of the default Devise-based one.
+    Spree 6 owns its authentication stack rather than depending on Devise, and separates the customer identity from the staff identity. Point Spree at your own classes with `Spree.user_class` and `Spree.admin_user_class`.
 
-    You can find more information in the [Authentication](authentication) section.
+    See [Authentication](../providers/sso.md).
 
 </details>
 
-
   <details>
-<summary>Checkout flow</summary>
+<summary>Webhooks</summary>
 
-**Best for:** Customizing checkout steps and flow.
+**Best for:** notifying external services — ERPs, CRMs, fulfillment systems — without writing Ruby.
 
-    With Spree you can change the checkout flow to fit your business needs - add steps, remove steps, or change the order.
+    Configure them in the dashboard under **Settings → Webhooks**, or through the Admin API.
 
-    Please see [Checkout flow customization section](checkout) for more information.
+    See [Webhooks](../core-concepts/webhooks.md).
 
 </details>
 
+  <details>
+<summary>Dependencies</summary>
+
+**Best for:** replacing an entire workflow or service with your own class.
+
+    ```ruby config/initializers/spree.rb
+    Spree::Dependencies.cart_add_item_workflow = 'MyApp::Carts::AddItem'
+    ```
+
+    > **WARNING:** Seam names end in `_workflow` in Spree 6. The old `*_service` names still resolve for one release with a warning, but **writes to them are ignored** — a class written against the old service contract isn't interchangeable with a workflow. Update the key when you upgrade.
+
+    Prefer a hook when you only need to add behavior. Replace the class only when you need to change what the flow fundamentally does.
+
+    See [Dependencies](dependencies.md).
+
+</details>
 
   <details>
 <summary>Decorators</summary>
 
-**Best for:** Adding associations, validations, scopes, and methods to Spree models. Use as a last resort.
+**Best for:** adding associations, validations and scopes to Spree models. Use as a last resort.
 
-    > **WARNING:** Decorators should be used **only when no other option works**. They tightly couple your code to Spree internals and can break during upgrades.
+    > **WARNING:** Decorators couple your code to Spree internals and are the most common cause of painful upgrades.
 > 
->       **Do NOT use decorators for:**
->       - After-save callbacks → Use [Events](../core-concepts/events.md) instead
->       - External service sync → Use [Webhooks](../core-concepts/webhooks.md) instead
->       - Custom service logic → Use [Dependencies](dependencies) instead
->       - Admin UI changes → Use [Admin Extensions](#admin-extensions) instead
+>       **Do not use decorators for:**
+>       - Logic inside a core flow → use [workflow hooks](#workflow-hooks)
+>       - After-save callbacks → use [events](#events-and-subscribers)
+>       - External service sync → use [webhooks](#webhooks)
+>       - Replacing a service → use [dependencies](#dependencies)
+>       - Admin UI changes → use [dashboard customization](../dashboard/customization/quickstart.md)
 
-    Decorators are still appropriate for structural changes:
+    They remain appropriate for structural additions:
 
     ```ruby app/models/spree/product_decorator.rb
     module Spree
       module ProductDecorator
         def self.prepended(base)
           base.belongs_to :brand, class_name: 'MyApp::Brand', optional: true
-          base.validates :external_id, presence: true
           base.scope :featured, -> { where(featured: true) }
         end
 
@@ -222,6 +249,30 @@ Spree is a flexible platform allowing you to customize every part of it to suit
     end
     ```
 
-    Please see [Decorators](decorators) section for more information.
+    See [Decorators](decorators.md).
 
 </details>
+
+
+## Choosing between hooks, events and dependencies
+
+These three overlap, and picking the wrong one is the most common source of upgrade pain:
+
+**Step 1: Do you need to block or change the outcome?**
+
+Use a **workflow hook**. Only `validate` hooks can stop an operation, and only they run early enough to do so safely — before money moves.
+
+  **Step 2: Do you just need to know it happened?**
+
+Use an **event subscriber**. It's decoupled, testable, and survives upgrades untouched.
+
+  **Step 3: Do you need the flow to do something fundamentally different?**
+
+Use **dependencies** to replace the class — and accept that you now own keeping it current.
+
+
+## Related
+
+- [Services & Workflows](workflows.md) — the workflow model and every hook
+- [Carts](../core-concepts/carts.md) — checkout requirements and completion
+- [Dashboard Customization](../dashboard/customization/quickstart.md) — extending the admin

package/dist/developer/customization/validations.md

@@ -162,7 +162,7 @@ Spree::Checkout::Registry.add_requirement(
 )
 ```
 
-See the [Spree 6 quickstart](/v6/developer/customization/quickstart) for the full registry API.
+See the [Spree 6 quickstart](quickstart.md) for the full registry API.
 
 ## Custom field values
 

package/dist/developer/dashboard/overview.md

@@ -102,4 +102,4 @@ When in doubt, customize in-app first. The migration path to a plugin is mechani
 - [Plugin scaffolding](plugins/scaffolding.md)
 - [Slots catalog](slots-catalog.md) — every named slot the dashboard exposes
 - [`@spree/dashboard-core` README](https://github.com/spree/spree/tree/main/packages/dashboard-core) — full extension API reference
-- [Classic Admin extension model](../admin/extending-ui.md) — for Spree 5.x
+- [Classic Admin extension model](customization/quickstart.md) — for Spree 5.x

package/dist/developer/how-to/build-a-b2b-store.md

@@ -0,0 +1,21 @@
+---
+title: Build a B2B Store
+description: Wholesale pricing, customer groups, companies with tax exemption, and gated storefront access — assembling Spree's B2B capabilities into a working wholesale channel.
+---
+
+Spree's B2B capabilities are core features composed together rather than a separate product: price lists give buyers negotiated and volume pricing, customer groups segment who sees what, companies carry the legal and tax identity of the buyer, and channel access controls gate the storefront to signed-in buyers.
+
+## What you will build
+
+- **Wholesale pricing** — price lists scoped to customer groups, volume tiers, and regional pricing per market.
+- **Companies** — buyer organizations with locations and contacts, tax identifiers validated per jurisdiction, and tax exemption certificates applied at checkout.
+- **Gated access** — a storefront channel restricted to approved buyers, with guest checkout disabled.
+- **B2B checkout** — orders carrying the buying company and location, priced and taxed accordingly.
+
+## Outline
+
+1. Model your buyer segments as customer groups
+2. Build wholesale price lists and volume tiers
+3. Register companies, locations and tax exemptions
+4. Gate a sales channel for wholesale buyers
+5. Take a wholesale order end to end

package/dist/developer/how-to/build-a-marketplace.md

@@ -0,0 +1,25 @@
+---
+title: Build a Multi-Vendor Marketplace
+description: Marketplace capabilities are part of Spree 6 core — sellers, order splitting, commissions and payouts, without a separate extension.
+---
+
+> **NOTE:** Marketplace features are a headline capability of the Spree 6.0 release and are documented here as they land. This guide covers the open-source core.
+
+Spree 6 brings multi-vendor marketplace support into the open-source core: sellers as first-class records, orders split per seller at completion, a commission engine, and a payout ledger with pluggable payout providers.
+
+## What you will build
+
+- **Sellers** — onboard sellers with an operator-configured requirements checklist, review submissions, and approve them for selling.
+- **Order splitting** — a customer checks out once; completion produces per-seller orders grouped under one purchase.
+- **Commissions** — the platform's cut computed per seller, with EU commission taxation handled.
+- **Payouts** — a transfer and payout ledger, with Stripe Connect payouts (Express onboarding, on-fulfillment transfers) shipping in the open-source monorepo.
+- **Seller operations** — sellers work through their own dedicated API surface, scoped so a seller only ever sees their own trade.
+
+## Outline
+
+1. Enable marketplace capabilities and configure the store
+2. Define seller onboarding requirements
+3. Invite and approve sellers
+4. Assign catalog to sellers and take a multi-seller order through checkout
+5. Configure commissions
+6. Connect Stripe for payouts

package/dist/developer/how-to/custom-api-authentication.md

@@ -378,4 +378,4 @@ end
 - `Spree::Api::V3::Store::AuthController` — `spree/api/app/controllers/spree/api/v3/store/auth_controller.rb`
 - `Spree::Api::V3::Admin::AuthController` — `spree/api/app/controllers/spree/api/v3/admin/auth_controller.rb`
 - `Spree::Api::V3::JwtAuthentication` — `spree/api/app/controllers/concerns/spree/api/v3/jwt_authentication.rb`
-- See also: [Staff & Roles](../core-concepts/staff-roles.md) for the admin login flow, [Customers](../core-concepts/customers.md) for storefront auth, and [Authentication](../customization/authentication.md) for `Spree.user_class` integration.
+- See also: [Staff & Roles](../core-concepts/staff-roles.md) for the admin login flow, [Customers](../core-concepts/customers.md) for storefront auth, and [Authentication](../providers/sso.md) for `Spree.user_class` integration.