@spree/docs 0.1.176 → 0.1.178

package/dist/developer/how-to/custom-promotion.md

@@ -1,18 +1,17 @@
 ---
 title: Build Custom Promotion Rules & Actions
-description: Step-by-step guide to creating custom promotion rules and actions for business-specific eligibility logic and discount behaviors.
+description: Step-by-step guide to creating custom promotion rules, discount actions, and adjusters for business-specific eligibility logic and charges.
 ---
 
 ## Overview
 
-Spree's promotion system is built around two extension points: **Rules** (eligibility conditions) and **Actions** (what happens when a promotion applies). While Spree ships with a comprehensive set of [built-in rules and actions](../core-concepts/promotions.md#rules), you can create custom ones for business-specific logic.
+Spree's promotion system has three extension points:
 
-This guide covers:
-- Creating a custom promotion rule with admin UI
-- Creating a custom promotion action with a calculator
-- Understanding the `eligible?`, `actionable?`, and `perform` contracts
+- **Rules** — conditions that decide when a promotion applies
+- **Actions** — what an applied promotion does, usually writing [Discount](../core-concepts/taxes-discounts-fees.md#discounts) rows
+- **Adjusters** — for discounts and fees that aren't promotions at all (loyalty pricing, gift wrap fees, payment surcharges)
 
-Before starting, make sure you understand [how promotions work in Spree](../core-concepts/promotions.md).
+Spree ships with a comprehensive set of [built-in rules and actions](../core-concepts/promotions.md#rules). This guide shows how to build your own of each kind.
 
 ## Custom Promotion Rules
 
@@ -30,7 +29,7 @@ module Spree
         preference :quantity, :integer, default: 5
 
         def applicable?(promotable)
-          promotable.is_a?(Spree::Order)
+          promotable.is_a?(Spree::Order) || promotable.is_a?(Spree::Cart)
         end
 
         def eligible?(order, options = {})
@@ -56,12 +55,14 @@ end
 
 | Method | Required | Description |
 |--------|----------|-------------|
-| `applicable?(promotable)` | Yes | Returns `true` if this rule type can evaluate the promotable (usually `promotable.is_a?(Spree::Order)`) |
+| `applicable?(promotable)` | Yes | Returns `true` if this rule type can evaluate the promotable — accept both carts and orders (see the note below) |
 | `eligible?(promotable, options = {})` | Yes | Returns `true` if the promotable meets this rule's conditions. Add messages to `eligibility_errors` to explain why not. |
-| `actionable?(line_item)` | No | Returns `true` if a specific line item should receive the promotion's action. Defaults to `true`. Override this for rules that target specific items (like product or category rules). |
+| `actionable?(line_item)` | No | Returns `true` if a specific line item should receive the promotion's discount. Defaults to `true`. Override this for rules that target specific items (like product or category rules). |
 
 The `options` hash passed to `eligible?` can include `:user`, `:email`, and other context from the checkout flow.
 
+> **WARNING:** Accept **both** `Spree::Cart` and `Spree::Order` in `applicable?`. Promotions are evaluated on every cart change, long before the cart becomes an order, and in Spree 6 a cart is its own model rather than an unfinished order. A rule guarding on `Spree::Order` alone silently never applies during checkout — the promotion just appears not to work. Every built-in rule accepts both.
+
 #### Using Preferences
 
 Rules use Spree's preference system for configuration. Each preference creates getter/setter methods automatically:
@@ -81,43 +82,30 @@ Available types: `:string`, `:integer`, `:decimal`, `:boolean`, `:array`.
 
 ### Step 2: Register the Rule
 
-Add your rule to the promotion configuration so it appears in the admin panel:
-
 ```ruby config/initializers/spree.rb
 Rails.application.config.after_initialize do
   Spree.promotions.rules << Spree::Promotion::Rules::MinimumQuantity
 end
 ```
 
-### Step 3: Create the Admin Partial
-
-Create a form partial so admins can configure the rule's preferences. The partial name must match the rule class name in underscore format:
+Registered rules are discoverable at `/api/v3/admin/promotion_rules/types` together with their preference schema, and the dashboard's promotion editor is built on that endpoint — your rule appears there with a generated preferences form, no UI work needed.
 
-```erb app/views/spree/admin/promotions/rules/_minimum_quantity.html.erb
-<div class="row mb-3">
-  <%= f.spree_number_field :preferred_quantity, label: Spree.t(:minimum_quantity) %>
-</div>
-```
+### Step 3: Add Translations
 
-### Step 4: Add Translations
+The rule's display name and description in the dashboard come from your locale file:
 
 ```yaml config/locales/en.yml
 en:
   spree:
-    minimum_quantity: Minimum Quantity
     promotion_rule_types:
       minimum_quantity:
         name: Minimum Quantity
         description: Order must contain at least X items
 ```
 
-### Step 5: Restart and Test
-
-After restarting your application, the new rule will be available in **Admin > Promotions** when adding rules to a promotion.
-
 ### Example: Rule with `actionable?`
 
-When your rule targets specific line items (not the whole order), implement `actionable?` so that actions like `CreateItemAdjustments` only discount matching items:
+When your rule targets specific line items (not the whole order), implement `actionable?` so that item-level actions only discount matching items:
 
 ```ruby app/models/spree/promotion/rules/brand.rb
 module Spree
@@ -127,7 +115,7 @@ module Spree
         preference :brand_names, :array, default: []
 
         def applicable?(promotable)
-          promotable.is_a?(Spree::Order)
+          promotable.is_a?(Spree::Order) || promotable.is_a?(Spree::Cart)
         end
 
         def eligible?(order, options = {})
@@ -153,13 +141,17 @@ end
 
 ## Custom Promotion Actions
 
-Actions define what happens when a promotion is applied. Most actions create [adjustments](../core-concepts/adjustments.md) on orders or line items.
+Actions define what happens when a promotion is applied. A discount action doesn't write rows itself — it declares **where** its discount belongs and **how much** it is, and Spree's promotion engine does the rest: running the competition between promotions, clamping amounts so nothing goes below zero, writing the winning Discount rows, and removing stale ones on every recalculation.
 
-### Step 1: Create the Action Class
+### Discount Action (with Calculator)
 
-#### Discount Action (with Calculator)
+Three declarations make a discount action:
 
-For actions that create monetary adjustments, include `Spree::CalculatedAdjustments` and `Spree::AdjustmentSource`:
+| Method | Description |
+|--------|-------------|
+| `discount_scope` | Where the discount belongs: `:line_item` (per matching item), `:fulfillment` (per delivery), or `:order` (whole order, distributed proportionally across items) |
+| `compute_amount(adjustable)` | The discount for one adjustable — a line item, fulfillment, or the order, matching your scope. Return a **negative** amount, or zero for "no discount". |
+| `perform(options = {})` | Called when the promotion is activated. For discount actions, delegate to `apply_via_adjuster(options)`. |
 
 ```ruby app/models/spree/promotion/actions/tiered_discount.rb
 module Spree
@@ -167,15 +159,15 @@ module Spree
     module Actions
       class TieredDiscount < Spree::PromotionAction
         include Spree::CalculatedAdjustments
-        include Spree::AdjustmentSource
 
         before_validation -> { self.calculator ||= Calculator::FlatRate.new }
 
-        def perform(options = {})
-          order = options[:order]
-          return false unless order.present?
+        def discount_scope
+          :order
+        end
 
-          create_unique_adjustment(order, order)
+        def perform(options = {})
+          apply_via_adjuster(options)
         end
 
         def compute_amount(order)
@@ -186,8 +178,7 @@ module Spree
                      else 0
                      end
 
-          # Must return negative amount for discounts
-          # Cap at order total to prevent negative orders
+          # Negative for discounts, capped at the order total
           [discount, order.item_total].min * -1
         end
       end
@@ -196,9 +187,13 @@ module Spree
 end
 ```
 
-#### Non-Discount Action
+With `discount_scope :order`, the winning amount is shared out proportionally across the line items — you never handle the distribution yourself. With `:line_item`, `compute_amount` is called once per line item, and only items passing your rules' `actionable?` receive rows.
+
+> **NOTE:** There is nothing to clean up either. If the promotion stops being eligible — the cart shrinks below the threshold, the code is removed — the next recalculation deletes its rows. If your action loses to a better promotion, its candidate simply isn't written that round, and it competes again on the next one.
 
-For actions that don't create adjustments (e.g., awarding points, sending notifications):
+### Non-Discount Action
+
+For actions that don't create discounts (awarding points, sending notifications), implement `perform` alone:
 
 ```ruby app/models/spree/promotion/actions/add_loyalty_points.rb
 module Spree
@@ -220,45 +215,9 @@ module Spree
 end
 ```
 
-#### Key Methods to Implement
-
-| Method | Required | Description |
-|--------|----------|-------------|
-| `perform(options = {})` | Yes | Called when the promotion is activated. `options` includes `:order` and `:promotion`. Return `true` if the action was applied. |
-| `compute_amount(adjustable)` | For discount actions | Return the adjustment amount (negative for discounts). Cap at the adjustable's total to prevent negative amounts. |
-| `revert(options = {})` | No | Called when a promotion is deactivated. Use to undo side effects (e.g., remove added line items). |
-
-#### Available Helper Methods
-
-When you include `Spree::AdjustmentSource`, you get:
-
-```ruby
-# Create a single adjustment (e.g., on the order)
-create_unique_adjustment(order, adjustable)
-
-# Create adjustments on multiple items (e.g., all line items)
-create_unique_adjustments(order, order.line_items)
-
-# With a filter block (e.g., only actionable line items)
-create_unique_adjustments(order, order.line_items) do |line_item|
-  promotion.line_item_actionable?(order, line_item)
-end
-```
-
-When you include `Spree::CalculatedAdjustments`, you get:
-
-```ruby
-# Delegate to the calculator
-compute(adjustable)  # calls calculator.compute(adjustable)
-
-# Set calculator by class name
-self.calculator_type = 'Spree::Calculator::FlatRate'
-
-# List available calculators for this action type
-self.class.calculators
-```
+`perform` receives `:order` and `:promotion` in its options and should return `true` if the action was applied. Optionally implement `revert(options = {})` to undo side effects when the promotion is deactivated.
 
-### Step 2: Register the Action
+### Register and Translate
 
 ```ruby config/initializers/spree.rb
 Rails.application.config.after_initialize do
@@ -266,8 +225,6 @@ Rails.application.config.after_initialize do
 end
 ```
 
-### Step 3: Add Translations
-
 ```yaml config/locales/en.yml
 en:
   spree:
@@ -277,39 +234,43 @@ en:
         description: Different discount amounts based on order total tiers
 ```
 
-### Step 4: Restart and Test
-
-After restarting, the new action will be available in **Admin > Promotions** when adding actions to a promotion.
-
-## How Rules and Actions Work Together
-
-Understanding how Spree evaluates promotions helps you build better custom rules and actions:
-
-```mermaid
-flowchart TD
-    A[Order Updated] --> B[PromotionHandler::Cart]
-    B --> C{For each promotion}
-    C --> D{Check dates & usage}
-    D -->|expired/exceeded| E[Deactivate]
-    D -->|valid| F{Evaluate rules}
-    F -->|match_policy: all| G[ALL rules must pass]
-    F -->|match_policy: any| H[ANY rule must pass]
-    G -->|eligible| I[Run actions]
-    H -->|eligible| I
-    G -->|ineligible| E
-    H -->|ineligible| E
-    I --> J[action.perform for each action]
-    J --> K[Create adjustments]
-    K --> L[Best promotion wins]
+Like rules, registered actions surface automatically in the dashboard's promotion editor via `/api/v3/admin/promotion_actions/types`.
+
+## Custom Adjusters
+
+Not every charge or reduction is a promotion. A gift wrap fee, a payment surcharge, or loyalty pricing has no rules, no coupon codes, and no competition — it just needs to be on the order whenever it applies. That's an **adjuster**: a class invoked on every recalculation that owns a family of [Fee or Discount](../core-concepts/taxes-discounts-fees.md) rows.
+
+```ruby app/models/my_app/adjusters/gift_wrap.rb
+module MyApp
+  module Adjusters
+    class GiftWrap < Spree::Adjusters::Base
+      def update
+        if order.gift_wrap?
+          order.fees.find_or_initialize_by(kind: 'gift_wrap').update!(
+            amount: 5.99, label: 'Gift wrapping'
+          )
+        else
+          order.fees.where(kind: 'gift_wrap').destroy_all
+        end
+      end
+    end
+  end
+end
+```
+
+```ruby config/initializers/spree.rb
+Rails.application.config.after_initialize do
+  Spree.adjusters << MyApp::Adjusters::GiftWrap
+end
 ```
 
-**Key points:**
-- `match_policy: 'all'` means every rule must return `eligible? == true`
-- `match_policy: 'any'` means at least one rule must return `eligible? == true`
-- For item-level actions (`CreateItemAdjustments`), `actionable?(line_item)` on each rule filters which line items get the discount
-- When multiple promotions compete, Spree picks the best one (largest discount) and marks others as ineligible
+The contract is one method: `update`. It runs on every recalculation, so it must be idempotent — write the rows that should exist, remove the ones that shouldn't (that's why the example uses `find_or_initialize_by` keyed by `kind` rather than `create`). The `order` it receives is the cart during checkout and the order after placement, and rows attach to it either way.
+
+There's no totals bookkeeping to do: after all adjusters run, Spree re-sums the typed rows into the order totals and the tax provider estimates tax on the result — a fee you write here gets taxed in the same pass, like any other fee.
+
+Custom discounts work the same way, writing `order.discounts` rows with your own `kind` (e.g. `'loyalty'`). Use a kind other than `'promotion'` — promotion rows belong to the promotion engine, which removes any it didn't write itself.
 
-## Testing Custom Rules and Actions
+## Testing
 
 ```ruby spec/models/spree/promotion/rules/minimum_quantity_spec.rb
 require 'spec_helper'
@@ -367,7 +328,7 @@ end
 
 ## Related Documentation
 
-- [Promotions](../core-concepts/promotions.md) - Promotion architecture and built-in rules/actions
-- [Calculators](../core-concepts/calculators.md) - Available calculator types for promotion actions
-- [Adjustments](../core-concepts/adjustments.md) - How adjustments work on orders and line items
-- [Events](../core-concepts/events.md) - Subscribe to promotion events
+- [Promotions](../core-concepts/promotions.md) — promotion architecture and built-in rules and actions
+- [Taxes, Discounts & Fees](../core-concepts/taxes-discounts-fees.md) — the typed rows actions and adjusters write
+- [Calculators](../core-concepts/calculators.md) — available calculator types for promotion actions
+- [Events](../core-concepts/events.md) — subscribe to promotion events

package/dist/developer/how-to/custom-report.md

@@ -9,7 +9,7 @@ Spree's reporting system is designed for extension. Each report is a pair of cla
 
 This guide walks you through building a custom report from scratch, including advanced patterns for SQL aggregations and multi-vendor support.
 
-Before starting, make sure you understand [how the reporting system works](../core-concepts/reports.md).
+Before starting, make sure you understand [how the reporting system works](/v5/developer/core-concepts/reports).
 
 ## Creating a Custom Report
 
@@ -383,5 +383,5 @@ end
 
 ## Related Documentation
 
-- [Reports](../core-concepts/reports.md) - Report architecture and built-in reports
+- [Reports](/v5/developer/core-concepts/reports) - Report architecture and built-in reports
 - [Events](../core-concepts/events.md) - How report generation uses the events system

package/dist/developer/how-to/custom-stock-splitter.md

@@ -5,11 +5,11 @@ description: Step-by-step guide to extending Spree's stock splitter chain — br
 
 ## Overview
 
-When [Order Routing](../core-concepts/shipments.md#order-routing) picks one or more stock locations to fulfill an order, each location's allocation is then run through a chain of **splitters**. Each splitter looks at the packages produced so far and decides whether to break them further along its own axis.
+When [Order Routing](../core-concepts/fulfillments.md#order-routing) picks one or more stock locations to fulfill an order, each location's allocation is then run through a chain of **splitters**. Each splitter looks at the packages produced so far and decides whether to break them further along its own axis.
 
 Spree ships with four splitters out of the box (`ShippingCategory`, `Backordered`, `Digital`, `Weight`). You add your own when you need a *physical* separation that isn't expressed by any of the existing ones — refrigerated SKUs that can't share a box with ambient ones, hazmat goods that need their own carrier label, gift-wrap items that ship from a separate processing room, and so on.
 
-Before starting, make sure you understand [how splitting works in Spree](../core-concepts/shipments.md#stock-splitters) and the [order routing](../core-concepts/shipments.md#order-routing) layer that runs before splitters.
+Before starting, make sure you understand [how splitting works in Spree](../core-concepts/fulfillments.md#stock-splitters) and the [order routing](../core-concepts/fulfillments.md#order-routing) layer that runs before splitters.
 
 | If the answer is "yes" | Pick |
 |---|---|
@@ -170,7 +170,7 @@ end
 
 ### Step 4 (optional): Add a Variant-side Predicate
 
-The example above relies on `variant.refrigerated?`. In a real plugin you'd back that with a [Custom Field](../core-concepts/custom-fields.md) on `Spree::Variant` — say a boolean metafield with key `refrigerated` — and define the predicate as a thin reader:
+The example above relies on `variant.refrigerated?`. In a real plugin you'd back that with a [Custom Field](../core-concepts/metafields.md) on `Spree::Variant` — say a boolean metafield with key `refrigerated` — and define the predicate as a thin reader:
 
 ```ruby app/models/spree/variant_decorator.rb
 Spree::Variant.class_eval do
@@ -208,6 +208,6 @@ Practical implications:
 
 ## Next Steps
 
-- [Shipments — Stock Splitters](../core-concepts/shipments.md#stock-splitters) — Concept overview and built-in splitter list
+- [Shipments — Stock Splitters](../core-concepts/fulfillments.md#stock-splitters) — Concept overview and built-in splitter list
 - [Build Custom Order Routing](custom-order-routing.md) — The other layer of split-shipment customization
-- [Custom Fields](../core-concepts/custom-fields.md) — Tag variants with the data your splitter reads
+- [Custom Fields](../core-concepts/metafields.md) — Tag variants with the data your splitter reads

package/dist/developer/how-to/sell-digital-products.md

@@ -0,0 +1,20 @@
+---
+title: Sell Digital Products
+description: Digital goods in Spree — a digital delivery profile, instant fulfillment without a shipping address, and delivering files or entitlements after payment.
+---
+
+Digital products skip the warehouse: no stock to reserve, no address to collect, no carrier to call. In Spree 6 that behavior comes from the product's delivery profile — assign a digital profile and checkout, fulfillment and the customer experience adapt.
+
+## What you will build
+
+- **Digital delivery profile** — products that require no shipping address and complete checkout without a delivery step.
+- **Instant fulfillment** — the digital fulfillment provider fulfills on payment rather than on dispatch.
+- **Delivery of the goods** — attaching files or granting entitlements, and notifying the customer.
+- **Mixed carts** — physical and digital items in one order, split into separate fulfillments automatically.
+
+## Outline
+
+1. Create a digital delivery profile and assign products
+2. Configure the digital fulfillment provider
+3. Deliver files or entitlements on fulfillment
+4. Handle mixed physical and digital orders

package/dist/developer/multi-tenant/quickstart.md

@@ -20,7 +20,7 @@ Each tenant (store) can have its own isolated data and configuration, including:
 
 All data is fully isolated besides the staff users, which can manage multiple tenants. This allows you to create a SaaS platform where each tenant can have its own store with its own branding and configuration. Isolation works across admin dashboard and API.
 
-> **INFO:** If you need individual seller/supplier/vendor accounts but shared product listings under one site you should use [multi vendor recipe](../multi-vendor.md) instead.
+> **INFO:** If you need individual seller/supplier/vendor accounts but shared product listings under one site you should use [multi vendor recipe](../how-to/build-a-marketplace.md) instead.
 
 ## Prerequisites
 

package/dist/developer/providers/dam.md

@@ -0,0 +1,14 @@
+---
+title: Product Media & DAM
+description: Media hosted in your DAM stays in your DAM — Spree stores the address, not a copy of the bytes, and renders it through the same pipeline as uploaded media.
+---
+
+> **NOTE:** This page documents functionality landing in an upcoming Spree 6.0 release. The interfaces described here may change before final release.
+
+If your media lives in a digital asset management system or a CDN you already operate, importing copies into Spree doubles your storage and guarantees drift. Externally hosted media makes the address the record: Spree stores a URL, renders it wherever uploaded media renders, and your DAM remains the source of truth for the asset itself.
+
+## What this covers
+
+- Product images and videos referenced by URL instead of uploaded bytes
+- Feeding media URLs through the same product feeds and imports as the rest of your catalog data
+- How externally hosted media behaves in the dashboard, the APIs and the storefront alongside uploaded media

package/dist/developer/providers/erp.md

@@ -0,0 +1,31 @@
+---
+title: Connect Your ERP
+description: Keep your ERP as the source of truth for stock. Spree syncs inventory in, answers availability from its own snapshot, and asks your ERP live only at the moments that matter.
+---
+
+> **NOTE:** This page documents functionality landing in an upcoming Spree 6.0 release. The interfaces described here may change before final release.
+
+Your ERP owns inventory truth. Spree's job is to sell against it without keeping a copy that drifts — and without making every product page wait on an ERP round trip.
+
+## What syncs, what stays live
+
+Stock levels sync into Spree and availability renders from Spree's own records. Live calls to the inventory provider happen only at decision moments: add-to-cart, taking a hold, completing checkout. Anonymous browsing never waits on your ERP.
+
+## The inventory provider
+
+A provider answers stock questions with Spree's own stock record shape, so everything downstream — backorder limits, serializers, availability scopes — keeps working without knowing where the number came from. External answers are read-only and never written into the catalog. The default provider reads Spree's own stock records; connecting nothing changes nothing.
+
+## Feeding stock from your ERP
+
+Two ways in, both writing stock movements rather than overwriting numbers — so you can always see why a figure changed:
+
+- **Bulk stock endpoint** — batch updates addressed by Spree IDs or by the keys your ERP already uses.
+- **CSV stock import** — file-based feeds through the standard import pipeline.
+
+## Addressing records by your keys
+
+The same product is known to your ERP and your PIM under different keys. External references are store-scoped mappings that let any feed address a Spree record as `external:<system>:<id>` — a create that names a key Spree already knows updates that record instead of failing.
+
+## Checkout holds and failure policy
+
+Local checkout holds reduce availability against externally reported stock, matched by location, so reservations count correctly. When your ERP is unreachable, inventory falls back to the local snapshot — selling stock that turns out to be missing is recoverable; blocking every checkout is not.

package/dist/developer/providers/fulfillment.md

@@ -0,0 +1,25 @@
+---
+title: Shipping & WMS
+description: Connect your warehouse, 3PL or carrier stack through fulfillment providers — label purchase, tracking, and delivery confirmation flow through one contract.
+---
+
+When an order ships, something outside Spree does the physical work — a warehouse management system, a 3PL, or a carrier API. Fulfillment providers are the contract between Spree's fulfillment lifecycle and that system.
+
+## What a fulfillment provider does
+
+A provider is attached to a delivery method and owns the outbound side of shipping:
+
+- **Label purchase** — providers that generate labels declare it and buy the label *before* the fulfillment is marked as shipped, so the customer email always carries tracking. Labels can also be purchased explicitly ahead of dispatch.
+- **Carrier notification** — creating a fulfillment with the provider is idempotent; cancelling or resuming a fulfillment stands the carrier down or re-engages it.
+
+## Tracking is its own axis
+
+Carrier truth — in transit, out for delivery, delivered — is tracked separately from Spree's fulfillment status. Tracking updates flow in from carrier webhooks and update the tracking status without touching the fulfillment lifecycle; confirmed delivery anchors the returns window.
+
+## The EasyPost reference provider
+
+The `spree_easypost` gem ships in the monorepo as the reference implementation: live carrier rates, label purchase and refunds, and tracker webhooks, with credentials managed through a Spree integration.
+
+## Writing your own
+
+A WMS or 3PL integration implements the same contract: receive the fulfillment, do the physical work, report tracking back. Rate quoting is a separate, smaller contract — see [custom delivery rates](../how-to/custom-delivery-rate-provider.md).

package/dist/developer/{deployment/telemetry.md → providers/observability.md}

@@ -1,5 +1,5 @@
 ---
-title: Telemetry
+title: Observability
 description: Distributed tracing with OpenTelemetry — one gem, standard OTEL_* environment variables, and every checkout becomes a trace from HTTP request to gateway call to webhook delivery.
 ---
 

package/dist/developer/providers/overview.md

@@ -0,0 +1,44 @@
+---
+title: Spree Fits Your Architecture
+description: Spree is the commerce layer in the middle of the systems you already run — ERP, PIM, DAM, WMS, PSP, tax engines, search and identity connect through provider contracts, not forks.
+---
+
+Most mid-size and enterprise merchants do not start from zero. They run an ERP that owns stock, a PIM that owns product data, a DAM that owns media, a warehouse system that ships boxes, and a payment provider with years of history. Replacing all of that to adopt a commerce platform is not a migration — it is a rebuild nobody asked for.
+
+Spree takes the opposite position: **it is the system of record for what the shopper sees, and your existing systems stay the system of record for what is true.** Content, prices and stock sync in and render from Spree's own copy; live calls to your systems happen only at decision moments — pricing a line, adding to cart, taking a stock hold, completing an order.
+
+```mermaid
+flowchart LR
+    PIM[PIM] --> S
+    ERP[ERP] --> S
+    DAM[DAM] --> S
+    subgraph S[Spree — commerce layer]
+        API[Store & Admin APIs]
+    end
+    S --> WMS[WMS / carriers]
+    S --> PSP[PSP]
+    S --> TAX[Tax engine]
+    S --> IDP[Identity provider]
+    S --> APM[Observability / APM]
+```
+
+## The provider contracts
+
+Every connection point is a documented contract with a default implementation that uses Spree's own data — a store that connects nothing works exactly as before.
+
+| Your system | Spree contract | Guide |
+|---|---|---|
+| ERP (stock levels) | Inventory provider | [Connect your ERP](erp.md) |
+| PIM (product data, prices) | Pricing provider + data feeds | [Connect your PIM](pim.md) |
+| DAM (media) | Externally hosted media | [Product media & DAM](dam.md) |
+| WMS / 3PL / carriers | Fulfillment provider | [Shipping & WMS](fulfillment.md) |
+| Carrier rate shopping | Delivery rate provider | [Custom delivery rates](../how-to/custom-delivery-rate-provider.md) |
+| PSP | Payment gateway | [Custom payment method](../how-to/custom-payment-method.md) |
+| Tax engine | Tax provider | [Avalara](../../integrations/tax/avalara.md) |
+| Search | Search provider | [Custom search provider](../how-to/custom-search-provider.md) |
+| Identity provider (SSO) | OpenID Connect | [Identity & SSO](sso.md) |
+| APM / observability | OpenTelemetry | [Observability](observability.md) |
+
+## Credentials live in one place
+
+Provider credentials are managed through Spree integrations — one admin surface for connecting external services, with secrets stored as masked preferences and connections verified before activation. Provider gems ship an integration class; there are no per-provider credential screens or environment-variable contracts for per-store services.

package/dist/developer/providers/pim.md

@@ -0,0 +1,25 @@
+---
+title: Connect Your PIM
+description: Keep product data and pricing in your PIM. Spree syncs content in, renders from its own copy, and can price live from an external source at cart decision moments.
+---
+
+> **NOTE:** This page documents functionality landing in an upcoming Spree 6.0 release. The interfaces described here may change before final release.
+
+Your PIM owns product content — names, descriptions, attributes, associations, prices. Spree renders the shopper-facing copy and asks your systems live only where a stale answer would cost money.
+
+## Product data feeds
+
+Products, variants and prices flow in through the Admin API and CSV imports. Feeds address records by the keys your PIM already uses via external references (`external:<system>:<id>`), so an integration never has to store Spree IDs to update what it created.
+
+## The pricing provider
+
+For merchants whose prices are computed elsewhere — contract pricing from an ERP, a pricing service, a PIM-driven price feed — a pricing provider answers price questions at cart decision moments with Spree's own price record shape. Tax-inclusive restatement and serializers keep working without knowing the number's origin.
+
+Two properties of the contract matter for operations:
+
+- **A provider declares a cache lifetime** and can decline anonymous browsing contexts, sending catalog pages straight to the local price resolver.
+- **Pricing refuses on failure** rather than falling back — charging the wrong price is a dispute, not a retry.
+
+## Price imports
+
+Price lists and plain price updates load through CSV imports and the Admin API, writing history rather than silently overwriting — the audit trail shows what changed and when.

package/dist/developer/providers/sso.md

@@ -0,0 +1,20 @@
+---
+title: Identity & SSO
+description: Single sign-on with OpenID Connect is built into Spree — connect your existing identity provider for staff and customer authentication without custom code.
+---
+
+Enterprises already have an identity provider. Staff accounts live in it, security policy is enforced through it, and a commerce platform that demands its own password database is a liability. Spree 6 ships OpenID Connect support in core.
+
+## Staff single sign-on
+
+Connect your identity provider so back-office users sign in to the dashboard through your existing SSO — sessions, MFA and offboarding stay governed by the system your security team already operates.
+
+## Customer authentication
+
+Storefront customer authentication supports the same standards, so a merchant running a customer identity platform can keep it as the source of truth for shopper accounts.
+
+## Bring your identity provider
+
+Any OpenID Connect issuer works. This guide will walk through connecting the common ones and the configuration each needs.
+
+For wiring a custom or non-OIDC JWT issuer into the Store and Admin APIs directly, see [integrating a third-party identity provider](../how-to/custom-api-authentication.md).

package/dist/developer/sdk/admin/extending.md

@@ -66,5 +66,5 @@ The SDK transforms `filter`/`sort` into the Ransack-flavored query string the Ad
 ## See also
 
 - The [Store SDK extending guide](../extending.md) covers the same pattern for storefront endpoints — the API is identical, only the base path (`/api/v3/store`) and auth header differ.
-- The [API](../../tutorial/api.md) and [SDK](../../tutorial/sdk.md) tutorials walk through creating new Spree endpoints end-to-end (Rails controller, serializer, TypeScript types). Everything they show for the Store API applies equivalently for the Admin API.
+- The [API](../../tutorial/admin-api.md) and [SDK](../../tutorial/storefront.md) tutorials walk through creating new Spree endpoints end-to-end (Rails controller, serializer, TypeScript types). Everything they show for the Store API applies equivalently for the Admin API.
 - For building dashboard UI on top of your custom endpoint, see the [Dashboard](../../dashboard/overview.md) section — start with [Customization Quickstart](../../dashboard/customization/quickstart.md) for in-app changes or [Plugin Overview](../../dashboard/plugins/overview.md) for redistributable packages.

package/dist/developer/sdk/admin/quickstart.md

@@ -66,4 +66,4 @@ const page: PaginatedResponse<Order> = await client.orders.list()
   - [Admin API Reference](../../../api-reference/admin-api/introduction.md) — The underlying REST API the SDK wraps — every endpoint, parameter, and response shape.
 
 
-> **TIP:** Adding your own resources? The [`spree generate api_resource`](../../tutorial/api.md) generator scaffolds Admin API endpoints (model, serializers, controllers, specs) in one command, and the [extending guide](../extending.md) shows how to call custom endpoints from the SDK.
+> **TIP:** Adding your own resources? The [`spree generate api_resource`](../../tutorial/admin-api.md) generator scaffolds Admin API endpoints (model, serializers, controllers, specs) in one command, and the [extending guide](../extending.md) shows how to call custom endpoints from the SDK.

package/dist/developer/sdk/admin/resources.md

@@ -125,4 +125,4 @@ await client.customFields('Spree::Product', 'prod_xxx').list()
 
 ## Adding your own resources
 
-The resource map grows with your store. The [`spree generate api_resource`](../../tutorial/api.md) generator scaffolds new Admin API endpoints (model, serializers, controllers, routes, specs) in one command — then call them from the SDK with a [custom fetch or raw request](../extending.md), or generate a typed client for them.
+The resource map grows with your store. The [`spree generate api_resource`](../../tutorial/admin-api.md) generator scaffolds new Admin API endpoints (model, serializers, controllers, routes, specs) in one command — then call them from the SDK with a [custom fetch or raw request](../extending.md), or generate a typed client for them.

package/dist/developer/sdk/extending.md

@@ -30,4 +30,4 @@ const nike = await client.request<Brand>('GET', '/brands/nike')
 
 `client.request` uses the same auth headers, retry logic, and locale/currency defaults as `client.products.list()` or any other built-in resource.
 
-For a complete walkthrough — creating the API endpoints on the backend, defining TypeScript types, filtering, and expanding associations — see the [API](../tutorial/api.md) and [SDK](../tutorial/sdk.md) tutorials.
+For a complete walkthrough — creating the API endpoints on the backend, defining TypeScript types, filtering, and expanding associations — see the [API](../tutorial/admin-api.md) and [SDK](../tutorial/storefront.md) tutorials.

package/dist/developer/tutorial/admin-api.md

@@ -0,0 +1,13 @@
+---
+title: Admin API
+description: Add a ProductFaq endpoint to the Admin API — resource controller conventions, an admin serializer, and a permission catalog entry.
+---
+
+Staff manage FAQs through the Admin API — the same API the dashboard, integrations and scripts use. This chapter adds the endpoint following the conventions every Spree resource follows, which is what makes the dashboard plugin in the next chapter nearly free.
+
+## What this chapter covers
+
+- The resource controller: full CRUD from one small controller declaring its model, serializer and permitted attributes
+- The admin serializer and prefixed IDs
+- Registering the resource in the permission catalog so roles and API key scopes cover it
+- Exercising the endpoint with the Admin CLI