Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Bootstrap Spree 6 docs (#14389)
Damian Legawiec3166e5493366
diff --git a/.claude/commands/create-plan.md b/.claude/commands/create-plan.mdindex 3387ab1adc..d0d9a8380c 100644--- a/.claude/commands/create-plan.md+++ b/.claude/commands/create-plan.md@@ -6,8 +6,51 @@ Follow this process:1. Read the plan template at `docs/plans/_template.md`2. Create a new plan file in `docs/plans/` with a kebab-case filename3. Fill in all sections based on our discussion and any existing context-4. Update the "Architecture Plans" section in the root `CLAUDE.md` to include the new plan-5. If the plan affects specific areas of the codebase, add cross-references in relevant directory-level CLAUDE.md files+4. **Resolve every open question interactively before finishing** — see below+5. Update the "Architecture Plans" section in the root `CLAUDE.md` to include the new plan+6. If the plan affects specific areas of the codebase, add cross-references in relevant directory-level CLAUDE.md filesThe filename should follow the pattern: `{release}-{feature-slug}.md`(e.g., `6.0-cart-order-split.md`, `future-mcp-server.md`)++## Resolving open questions (required)++A draft plan that ships with unresolved open questions is not finished. After+writing the draft, **always** walk the author through every open question using+the `AskUserQuestion` tool — do not leave them for later, and do not pick+answers silently.++- Ask them **together in one call** where possible (the tool takes up to 4+ questions), so the author sees the whole decision surface at once.+- For each question give **2–4 concrete options**, not an open prompt. Lead with+ your recommendation and mark it `(Recommended)`.+- Use the `preview` field to show the actual shape of each option — the code,+ the config, or the schema it implies. Seeing `store.preference || global ||+ DEFAULT` next to `store.preference` makes the trade-off obvious in a way prose+ does not.+- State the **cost** of each option in its description, not just what it does.+ "More invasive, touches every caller" is the part the author is deciding on.++Then fold the answers back into the plan:++- Move each resolved question out of **Open Questions** into **Key Decisions**,+ phrased as a decision with its date and the reasoning that settled it.+- Record any **accepted trade-off** explicitly. If an option was chosen knowing+ it has a sharp edge, the plan must say so — and if that edge constrains how+ other code must be written, add it to **Constraints on Current Work**.+- Leave **Open Questions** holding only genuinely deferred items, each with a+ note on what would unblock it. If nothing is left, say so plainly rather than+ deleting the section.+- Once the questions are settled, the plan's status is no longer `Draft` —+ update it (typically to `Design finalized`).++Only skip the interactive pass if the draft genuinely raised no open questions —+which is rare, and worth double-checking before concluding.++## Recording decisions++When a new plan settles something significant — a decision other plans will need+to reference, or a constraint on how code elsewhere must be written — also add a+dated entry to `docs/plans/decisions.md`, and add a superseding note to any+existing plan whose Key Decisions it contradicts. A decision that lives in only+one plan will be missed by whoever reads the other one.diff --git a/.claude/commands/update-plan.md b/.claude/commands/update-plan.mdindex 15b651fbfa..6c462c0ed5 100644--- a/.claude/commands/update-plan.md+++ b/.claude/commands/update-plan.md@@ -6,5 +6,43 @@ Instructions: $ARGUMENTS2. Identify the relevant plan based on the instructions3. Read the current plan content4. Apply the requested changes while preserving the document structure-5. Update the `Last updated` date-6. If status changed, update the reference in root `CLAUDE.md`+5. **Resolve open questions interactively before finishing** — see below+6. Update the `Last updated` date+7. If status changed, update the reference in root `CLAUDE.md`++## Resolving open questions (required)++Never leave a plan sitting on unresolved open questions after an edit. Before+finishing, check the plan's **Open Questions** section and use the+`AskUserQuestion` tool to settle anything the author can decide now — both+questions that were already there and any your changes introduced.++- Ask them **together in one call** where possible (the tool takes up to 4+ questions), so the author sees the whole decision surface at once.+- For each question give **2–4 concrete options**, not an open prompt. Lead with+ your recommendation and mark it `(Recommended)`.+- Use the `preview` field to show the actual shape of each option — the code,+ the config, or the schema it implies.+- State the **cost** of each option in its description, not just what it does.++Then fold the answers back into the plan:++- Move each resolved question out of **Open Questions** into **Key Decisions**,+ phrased as a decision with its date and the reasoning that settled it.+- Record any **accepted trade-off** explicitly, and if it constrains how other+ code must be written, add it to **Constraints on Current Work**.+- Leave **Open Questions** holding only genuinely deferred items, each with a+ note on what would unblock it.+- If the last blocking question is now settled, move the status off `Draft`.++If a question genuinely cannot be answered yet — it depends on work that hasn't+landed, or on information nobody has — say so and leave it deferred with the+reason. That is a resolution too; silently leaving it unexamined is not.++## Recording decisions++When an update settles something significant — a reversal, a cross-plan+constraint, or a decision other plans will need to reference — also add a dated+entry to `docs/plans/decisions.md`, and add a superseding note to any other plan+whose Key Decisions this contradicts. A decision that lives in only one plan+will be missed by whoever reads the other one.diff --git a/CLAUDE.md b/CLAUDE.mdindex e40a8480ee..d4586c717f 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -32,6 +32,7 @@ Active plans (6.0 target, work pending):- `6.0-replace-taxons-with-categories.md` — Split Taxon into Category (hierarchy) + Collection (flat/rule-based). **Shipped to 6-0-dev (PR #14302):** the Category surface (5.5–5.6) plus the 6.0 core — `spree_taxons`→`spree_categories` table rename + inheritance flip (`Spree::Category < Spree.base_class`, `Spree::Taxon` alias kept), the full `Collection` stack (model + rules + DB/Meilisearch manual sort + API), the taxon→category/collection data migration, and de-ruling Category. Pending (all 6.1): channel-aware `CollectionRules::AvailableOn` (ships interim now, rides with channels) + dropping `spree_taxon_rules`/`Taxonomy`. No brand feature in 6.0 — brands are modeled as a Category/Collection; `brand_taxon`/`brand_name` removed with `Taxonomy`.- `6.0-delivery-method-rules.md` — `Spree::DeliveryMethodRule` STI on DeliveryMethod (design finalized 2026-07-29): ItemTotal/Weight rules first (Channel/Market/CustomerGroup later in lockstep with payment-method-rules), enforced solely in `Stock::Estimator`'s method filter so calculator- AND provider-priced methods obey eligibility; replaces the FlatRate-only bound preferences (one-release bridge + data task). Phase 1 rides the 6.0 core-rewrite finishing work.- `6.0-service-workflows.md` — Two-tier services doctrine (2026-07-30). **Tier 1 `app/services/`:** plain `ServiceModule` classes, hand-written `def call(cart:, ...)`, Ruby kwargs as the contract — the permanent default; no DSL, no new `run`-pipelines, no hand-rolled sagas. **Tier 2 `app/workflows/`:** `Spree::Workflow` — named steps inside a plain `def perform(order:, ...)` (the ActiveJob::Continuable shape; bare `super` turns parameters into readers). Vocabulary: `step`/`external_step` (+ `with:`, `on_flow_failure:`), `run_hooks` + class-level `hooks`, `failure`/`halt!`; plain `ApplicationRecord.transaction`/`with_lock`/`rescue`/`publish_event`; every step instrumented as `step.spree_workflow`. Money lives in `Carts::RecalculateTotals` (single totals seam; the completed-order branch is the post-placement resum — rows re-summed, never regenerated), statuses in `Orders::UpdateStatuses` (refreshes each fulfillment's state, then rolls up); Order/CartUpdater are 6.1-removed warning shells. Shared Cart/Order surface lives in `Spree::Purchase::*` concerns; completion side effects (newsletter, account creation, risk) run in the sync `OrderPlacedSubscriber` on order.placed. Reserved for flows needing hooks, compensation/external I/O, or replay — currently `Carts::Complete`, `Carts::AddItem`, `Carts::Recalculate`, `Carts::RecalculateTotals` (+ order twins) and `Orders::Cancel` (absorbed `Order#after_cancel`; gateway settlement is an external_step). A service graduates to the workflow tier when it earns a hook, never speculatively — but hooks on flows already in the tier ship deliberately on the 6.0 boundary (2026-08-02), since hook keys are public API and moving one later is breaking. **New models get no state machine** — plain `status` string + inclusion validation, transitions through workflows; gateway I/O never in a save callback. Three hook families, contracts settled 2026-08-02: **lifecycle** (past tense, read-only), **validate** (handler calls `workflow.reject!(message)` to veto), **context** (`set_*_context`/`get_provider_data` — handler returns a hash, `run_hooks` deep-merges all handlers and returns it; last writer wins on collision). Phase 3 **shipped (2026-08-02)**: `run_hooks` returns the merged hash and `Workflow#reject!` is public API; `validate`/context/lifecycle hooks live on AddItem, Complete, Recalculate, RecalculateTotals, Cancel and Resume; `Fulfillments::Create`, `Payments::Capture`/`Refund`, `Payments::HandleWebhook` and `Carts::Merge` moved to `app/workflows/` (seams `fulfillment_create_workflow`, `payment_capture_workflow`, `payment_refund_workflow`, `payments_handle_webhook_workflow`, `cart_merge_workflow`; legacy names readable one release). Payment workflows own the transaction boundary and guards — money movement stays in the model, called from an `external_step`. No workflows for plain CRUD. Workflow Dependencies seams use `*_workflow` keys; legacy `*_service` names stay settable/readable with warnings until 6.1 but writes are stashed, never applied (old service classes aren't workflow-contract compatible). `Carts::Complete` battery must pass unmodified. **Durability = plain Rails:** long-running background work uses `ActiveJob::Continuable` directly (reference: `Spree::Imports::ProcessJob` — CSV spine with a row-number cursor; `CreateRowsJob`/`ProcessRowsJob` deprecated shells); workflows are synchronous request-cycle flows and are NOT jobs — Workflow-level durable execution ships only if the payout run proves the need.+- `6.0-store-scoped-configuration.md` — Move nine commerce-behavior globals (`auto_capture`, `auto_capture_on_dispatch`, `allow_checkout_on_gateway_error`, `track_inventory_levels`, `stock_reservations_enabled`, `track_price_history`, `show_products_without_price`, `address_requires_phone`, `disable_sku_validation`) from `Spree::Config` to `Spree::Store` preferences. Store preference is **authoritative — no runtime fallback** (a fallback chain is what made `default_stock_reservation_ttl_minutes` silently unreachable); upgrade carries values over via `spree:store_settings:backfill_from_config`; globals are deprecated shells until 6.1. Storeless readers (`Address`, the product availability scope) use `Spree::Current.store` with a default fallback. Seven dead settings (`products_per_page`, `storefront_*_path`, …) get shells then deletion. **Constraints now:** no new `Spree::Config` reads of the movers; new behavior flags are born on Store, never global; jobs that validate addresses or query the catalog must set `Spree::Current.store`.- `6.0-store-scoped-custom-field-definitions.md` — Add `store_id` + persisted `filter_key` to `Spree::MetafieldDefinition` (today global and computed), making uniqueness `(store_id, resource_type, filter_key)` with a DB index. Deferred from the 5.6 custom-field search/sort/filter work (schema change, not patch-safe). **Until then:** `filter_key` is a computed method — no Ransack predicates or `where`/`order` against it; definitions are global; uniqueness rests on a `CONCAT` validation with no index behind it.Multi-version plans (some phases shipped, some pending):diff --git a/docs/developer/customization/api.mdx b/docs/developer/customization/api.mdxindex 0df12b05c2..ca01659a22 100644--- a/docs/developer/customization/api.mdx+++ b/docs/developer/customization/api.mdx@@ -3,7 +3,7 @@ title: Customizing the Spree APIdescription: Add new Store API endpoints, customize existing JSON responses with serializer decorators, and extend Spree's REST API to fit your storefront needs.----Before you start customizing Spree API endpoints, make sure you reviewed all existing API endpoints in the [Spree API docs](/api-reference).+Before you start customizing Spree API endpoints, make sure you reviewed all existing API endpoints in the [Spree API docs](/api-reference/admin-api/endpoints).For a step-by-step walkthrough of adding a complete new resource (model, serializer, controller, routes), see the [API tutorial](/developer/tutorial/api).diff --git a/docs/developer/customization/decorators.mdx b/docs/developer/customization/decorators.mdxindex a4b2b21484..2321ad236b 100644--- a/docs/developer/customization/decorators.mdx+++ b/docs/developer/customization/decorators.mdx@@ -564,4 +564,3 @@ end- [Admin Partials](/developer/admin/extending-ui) - Extend admin UI without view decorators- [Extending Core Models Tutorial](/developer/tutorial/extending-models) - Step-by-step guide to connecting custom models with Spree core- [Customization Overview](/developer/customization/quickstart) - General customization patterns-- [Logic Customization](/developer/customization/logic) - Customizing business logicdiff --git a/docs/developer/customization/dependencies.mdx b/docs/developer/customization/dependencies.mdxindex c64d0823f7..39bf7f4d66 100644--- a/docs/developer/customization/dependencies.mdx+++ b/docs/developer/customization/dependencies.mdx@@ -7,7 +7,7 @@ section: customizationWith Dependencies, you can replace parts of Spree core with your custom code:[Services and Workflows](/developer/customization/workflows), CanCanCan-Abilities (used for [Permissions](permissions)), and API Serializers (used for+Abilities (used for [Permissions](/developer/customization/permissions)), and API Serializers (used forgenerating JSON API responses).<Tip>diff --git a/docs/developer/getting-started/quickstart.mdx b/docs/developer/getting-started/quickstart.mdxindex 874cf09873..43908566fb 100644--- a/docs/developer/getting-started/quickstart.mdx+++ b/docs/developer/getting-started/quickstart.mdx@@ -1,66 +1,27 @@---title: "Installing Spree"sidebarTitle: Installation-description: "Install Spree Commerce locally with Docker or Ruby on Rails, run your first store, and deploy it to production with the official starter template."+description: "Install Spree Commerce locally, run your first store, and deploy it to production with the official starter template."----## Installation options--<Tabs>- <Tab title="create-spree-app">- The quickest way to get started. Scaffolds a full Spree project with Next.js Storefront (optional).-- **Requirements:** [Node.js](https://nodejs.org/) 20+ and [Docker](https://docs.docker.com/get-docker/) running.-- ```bash- npx create-spree-app@latest my-store- ```-- The CLI walks you through an interactive setup:-- 1. Choose **Full-stack** (Backend + Next.js Storefront) or **Backend only**- 2. Optionally load **sample data** (products, categories, images)-- Once complete, your store should be running at [http://localhost:3000/admin](http://localhost:3000/admin). The port can be different if `3000` is already used on your system.-- See the full [create-spree-app documentation](/developer/create-spree-app/quickstart) for all CLI flags and options.- </Tab>- <Tab title="Manual Installation">- For developers who prefer full control over the setup, or want to add Spree to an existing Rails application.-- 1. Install [Ruby](https://www.ruby-lang.org/en/documentation/installation/)- 2. Install [vips](https://www.libvips.org/install.html) for image processing- 3. Install Rails gem:- ```bash- gem install rails- ```- 4. Create a new Spree application:- ```bash- rails new my_store -m https://raw.githubusercontent.com/spree/spree/main/spree/template.rb- ```- To use a specific database, pass the `-d` flag:- ```bash- rails new my_store -d postgresql -m https://raw.githubusercontent.com/spree/spree/main/spree/template.rb- rails new my_store -d mysql -m https://raw.githubusercontent.com/spree/spree/main/spree/template.rb- ```- 5. Navigate to the application directory:- ```bash- cd my_store- ```- 6. Start the development server:- ```bash- bin/dev- ```- 7. Optionally load sample data (products, categories, etc.):- ```bash- bin/rails spree_sample:load- ```-- <Info>- Spree works with **PostgreSQL**, **MySQL**, and **SQLite** databases. The Rails template defaults to SQLite for quick setup. You can switch to PostgreSQL or MySQL at any time. [Learn more about database configuration](/developer/deployment/database).- </Info>- </Tab>-</Tabs>+## Using `create-spree-app`++ The quickest way to get started. Scaffolds a full Spree project with Next.js Storefront (optional).++ **Requirements:** [Node.js](https://nodejs.org/) 20+ and [Docker](https://docs.docker.com/get-docker/) running.++ ```bash+ npx create-spree-app@latest my-store+ ```++ The CLI walks you through an interactive setup:++ 1. Choose **Full-stack** (Backend + Next.js Storefront) or **Backend only**+ 2. Optionally load **sample data** (products, categories, images)++ Once complete, your store should be running at [http://localhost:3000/admin](http://localhost:3000/admin). The port can be different if `3000` is already used on your system.++ See the full [create-spree-app documentation](/developer/create-spree-app/quickstart) for all CLI flags and options.## Accessing Admin Paneldiff --git a/docs/docs.json b/docs/docs.jsonindex f0e322dd84..ef8f77bf10 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -160,6 +160,1598 @@]},"navigation": {+ "versions": [+ {+ "version": "v5.x",+ "default": true,+ "tabs": [+ {+ "tab": "Guides",+ "menu": [+ {+ "item": "Getting Started",+ "icon": "rocket",+ "description": "Quickstart guide and core concepts",+ "groups": [+ {+ "group": "Getting started",+ "icon": "rocket",+ "pages": [+ "developer/getting-started/quickstart"+ ]+ },+ {+ "group": "Platform",+ "icon": "settings",+ "pages": [+ "developer/core-concepts/architecture",+ "developer/core-concepts/stores",+ "developer/core-concepts/channels",+ "developer/core-concepts/markets",+ "developer/core-concepts/customers",+ "developer/core-concepts/staff-roles"+ ]+ },+ {+ "group": "Catalog",+ "icon": "package",+ "pages": [+ "developer/core-concepts/products",+ "developer/core-concepts/pricing",+ "developer/core-concepts/inventory",+ "developer/core-concepts/media",+ "developer/core-concepts/search-filtering"+ ]+ },+ {+ "group": "Cart & Checkout",+ "icon": "shopping-cart",+ "pages": [+ "developer/core-concepts/orders",+ "developer/core-concepts/payments",+ "developer/core-concepts/taxes",+ "developer/core-concepts/promotions",+ "developer/core-concepts/store-credits-gift-cards"+ ]+ },+ {+ "group": "Fulfillment",+ "icon": "truck",+ "pages": [+ "developer/core-concepts/shipments",+ "developer/core-concepts/addresses",+ "developer/core-concepts/adjustments",+ "developer/core-concepts/calculators"+ ]+ },+ {+ "group": "Extensibility",+ "icon": "plug",+ "pages": [+ "developer/core-concepts/events",+ "developer/core-concepts/webhooks",+ "developer/core-concepts/translations",+ "developer/core-concepts/slugs",+ "developer/core-concepts/metafields",+ "developer/core-concepts/reports",+ "developer/core-concepts/imports-exports"+ ]+ }+ ]+ },+ {+ "item": "Building a Storefront",+ "icon": "store",+ "description": "Next.js, custom frontend, or Rails engine",+ "groups": [+ {+ "group": "Next.js Storefront",+ "pages": [+ "developer/storefront/nextjs/quickstart",+ "developer/storefront/nextjs/architecture",+ "developer/storefront/nextjs/multi-region",+ "developer/storefront/nextjs/customization",+ "developer/storefront/nextjs/emails",+ "developer/storefront/nextjs/wholesale",+ "developer/storefront/nextjs/wallet-payments",+ "developer/storefront/nextjs/testing",+ "developer/storefront/nextjs/environment-variables",+ "developer/storefront/nextjs/deployment"+ ]+ }+ ]+ },+ {+ "item": "Use Cases",+ "icon": "book-open",+ "description": "Multi-store/multi-tenant, and marketplace setups",+ "groups": [+ {+ "group": "Multi-Tenant / Multi-Store",+ "pages": [+ "developer/multi-tenant/quickstart",+ "developer/multi-tenant/core-concepts",+ "developer/multi-tenant/configuration"+ ]+ },+ {+ "group": "Multi-Vendor Marketplace",+ "pages": [+ "developer/multi-vendor/quickstart",+ "developer/multi-vendor/installation"+ ]+ }+ ]+ }+ ]+ },+ {+ "tab": "Framework",+ "menu": [+ {+ "item": "Extending",+ "icon": "puzzle",+ "description": "Customize admin panel, API, and business logic",+ "groups": [+ {+ "group": "Tutorial",+ "icon": "graduation-cap",+ "pages": [+ "developer/tutorial/introduction",+ "developer/tutorial/model",+ "developer/tutorial/admin",+ "developer/tutorial/extending-models",+ "developer/tutorial/api",+ "developer/tutorial/events",+ "developer/tutorial/sdk",+ "developer/tutorial/testing"+ ]+ },+ {+ "group": "Admin Panel",+ "icon": "gauge",+ "pages": [+ "developer/admin/admin",+ "developer/admin/extending-ui",+ "developer/admin/navigation",+ "developer/admin/tables",+ "developer/admin/form-builder",+ "developer/admin/components",+ "developer/admin/helper-methods",+ "developer/admin/authentication",+ "developer/admin/custom-javascript",+ "developer/admin/custom-css"+ ]+ },+ {+ "group": "Customization Reference",+ "icon": "wrench",+ "pages": [+ "developer/customization/quickstart",+ "developer/customization/configuration",+ "developer/customization/authentication",+ "developer/customization/checkout",+ "developer/customization/permissions",+ "developer/customization/workflows",+ "developer/customization/dependencies",+ "developer/customization/decorators",+ "developer/customization/model-preferences",+ "developer/customization/metadata",+ "developer/customization/routes",+ "developer/customization/api"+ ]+ }+ ]+ },+ {+ "item": "How-to Guides",+ "icon": "book-open",+ "description": "Step-by-step guides for common tasks",+ "groups": [+ {+ "group": "Order Routing",+ "icon": "route",+ "pages": [+ "developer/how-to/custom-order-routing"+ ]+ },+ {+ "group": "Stock Splitters",+ "icon": "boxes-stacked",+ "pages": [+ "developer/how-to/custom-stock-splitter"+ ]+ },+ {+ "group": "Payments",+ "icon": "credit-card",+ "pages": [+ "developer/how-to/custom-payment-method"+ ]+ },+ {+ "group": "Promotions",+ "icon": "tag",+ "pages": [+ "developer/how-to/custom-promotion"+ ]+ },+ {+ "group": "Reports",+ "icon": "chart-bar",+ "pages": [+ "developer/how-to/custom-report"+ ]+ },+ {+ "group": "Search",+ "icon": "search",+ "pages": [+ "developer/how-to/custom-search-provider"+ ]+ },+ {+ "group": "Authentication",+ "icon": "key",+ "pages": [+ "developer/how-to/custom-api-authentication"+ ]+ }+ ]+ },+ {+ "item": "Operations",+ "icon": "server",+ "description": "Deploy, upgrade, and maintain your store",+ "groups": [+ {+ "group": "Deployment",+ "icon": "server",+ "pages": [+ "developer/deployment/quickstart",+ "developer/deployment/docker",+ "developer/deployment/environment_variables",+ {+ "group": "AWS",+ "pages": [+ "developer/deployment/aws",+ "developer/deployment/aws_ecs"+ ]+ },+ "developer/deployment/render",+ "developer/deployment/assets",+ "developer/deployment/emails",+ "developer/deployment/cdn",+ "developer/deployment/background_jobs",+ "developer/deployment/caching",+ "developer/deployment/database"+ ]+ },+ {+ "group": "Upgrading",+ "icon": "circle-arrow-up",+ "pages": [+ "developer/upgrades/quickstart",+ {+ "group": "Upgrade Guides",+ "pages": [+ "developer/upgrades/5.5-to-5.6",+ "developer/upgrades/5.4-to-5.5",+ "developer/upgrades/5.3-to-5.4",+ "developer/upgrades/5.2-to-5.3",+ "developer/upgrades/5.1-to-5.2",+ "developer/upgrades/5.0-to-5.1",+ "developer/upgrades/4.10-to-5.0",+ "developer/upgrades/4.9-to-4.10",+ "developer/upgrades/4.8-to-4.9",+ "developer/upgrades/4.x-to-4.8",+ "developer/upgrades/4.6-to-4.7",+ "developer/upgrades/4.5-to-4.6",+ "developer/upgrades/4.4-to-4.5",+ "developer/upgrades/4.3-to-4.4",+ "developer/upgrades/4.2-to-4.3",+ "developer/upgrades/4.1-to-4.2",+ "developer/upgrades/4.0-to-4.1",+ "developer/upgrades/3.7-to-4.0",+ "developer/upgrades/3.6-to-3.7",+ "developer/upgrades/3.5-to-3.6",+ "developer/upgrades/3.4-to-3.5",+ "developer/upgrades/3.3-to-3.4",+ "developer/upgrades/3.2-to-3.3",+ "developer/upgrades/3.1-to-3.2",+ "developer/upgrades/3.0-to-3.1",+ "developer/upgrades/2.3-to-2.4",+ "developer/upgrades/2.2-to-2.3",+ "developer/upgrades/2.1-to-2.2",+ "developer/upgrades/2.0-to-2.1"+ ]+ }+ ]+ },+ {+ "group": "Contributing",+ "icon": "heart",+ "pages": [+ "developer/contributing/quickstart",+ "developer/contributing/developing-spree",+ "developer/contributing/creating-an-extension"+ ]+ },+ {+ "group": "Security",+ "icon": "shield",+ "pages": [+ "developer/security/security_policy",+ "developer/security/pci_compliance"+ ]+ }+ ]+ }+ ]+ },+ {+ "tab": "SDK & Tools",+ "menu": [+ {+ "item": "Store SDK",+ "icon": "code",+ "description": "TypeScript SDK for the Store API",+ "groups": [+ {+ "group": "Getting Started",+ "pages": [+ "developer/sdk/quickstart",+ "developer/sdk/authentication",+ "developer/sdk/configuration",+ "developer/sdk/extending"+ ]+ },+ {+ "group": "Store API",+ "pages": [+ "developer/sdk/store/products",+ "developer/sdk/store/cart-checkout",+ "developer/sdk/store/payments",+ "developer/sdk/store/markets",+ "developer/sdk/store/account",+ "developer/sdk/store/wishlists"+ ]+ }+ ]+ },+ {+ "item": "Admin SDK",+ "icon": "shield-check",+ "description": "TypeScript SDK for the Admin API",+ "groups": [+ {+ "group": "Admin SDK",+ "pages": [+ "developer/sdk/admin/quickstart",+ "developer/sdk/admin/authentication",+ "developer/sdk/admin/resources",+ "developer/sdk/admin/querying-and-errors",+ "developer/sdk/admin/extending"+ ]+ }+ ]+ },+ {+ "item": "CLI",+ "icon": "square-terminal",+ "description": "Command-line interface for Spree",+ "groups": [+ {+ "group": "CLI",+ "pages": [+ "developer/cli/quickstart",+ "developer/cli/admin-api"+ ]+ }+ ]+ },+ {+ "item": "create-spree-app",+ "icon": "rocket",+ "description": "Scaffold a new Spree project",+ "groups": [+ {+ "group": "create-spree-app",+ "pages": [+ "developer/create-spree-app/quickstart"+ ]+ }+ ]+ },+ {+ "item": "Agentic Development",+ "icon": "bot",+ "description": "Build Spree with AI coding agents",+ "groups": [+ {+ "group": "Agentic Development",+ "pages": [+ "developer/agentic/overview",+ "developer/agentic/agent-skills",+ "developer/agentic/mcp",+ "developer/agentic/llm-docs"+ ]+ }+ ]+ }+ ]+ },+ {+ "tab": "API Reference",+ "menu": [+ {+ "item": "Store API",+ "icon": "store",+ "description": "REST API for storefronts and custom integrations",+ "groups": [+ {+ "group": "API basics",+ "pages": [+ "api-reference/store-api/introduction",+ "api-reference/store-api/authentication",+ "api-reference/store-api/errors",+ "api-reference/store-api/idempotency",+ "api-reference/store-api/rate-limitting",+ "api-reference/store-api/querying",+ "api-reference/store-api/relations",+ "api-reference/store-api/metadata",+ "api-reference/store-api/localization",+ "api-reference/store-api/monetary-amounts",+ "api-reference/store-api/migrating-from-storefront-api-v2"+ ]+ },+ {+ "group": "Endpoints",+ "openapi": {+ "source": "api-reference/store.yaml",+ "directory": "api-reference/store-api"+ }+ }+ ]+ },+ {+ "item": "Admin API",+ "icon": "shield",+ "description": "REST API for pragmatically managing stores",+ "groups": [+ {+ "group": "API basics",+ "pages": [+ "api-reference/admin-api/introduction",+ "api-reference/admin-api/authentication",+ "api-reference/admin-api/errors",+ "api-reference/admin-api/querying",+ "api-reference/admin-api/monetary-amounts",+ "api-reference/admin-api/endpoints"+ ]+ },+ {+ "group": "Endpoints",+ "openapi": {+ "source": "api-reference/admin.yaml",+ "directory": "api-reference/admin-api"+ }+ }+ ]+ },+ {+ "item": "Webhooks",+ "icon": "webhook",+ "description": "Event payloads and delivery reference",+ "groups": [+ {+ "group": "Webhooks",+ "pages": [+ "api-reference/webhooks-events"+ ]+ }+ ]+ },+ {+ "item": "Legacy API v2",+ "icon": "clock",+ "description": "Previous-generation Storefront and Platform APIs",+ "groups": [+ {+ "group": "API basics",+ "pages": [+ "api-reference/v2/introduction",+ "api-reference/v2/pagination",+ "api-reference/v2/filtering-and-sorting",+ "api-reference/v2/fetching-multiple-resources"+ ]+ },+ {+ "group": "Tutorials",+ "pages": [+ "api-reference/tutorials/quick-checkout-with-stripe",+ "api-reference/tutorials/adyen-integration-guide-for-android",+ "api-reference/tutorials/adyen-integration-guide-for-ios"+ ]+ },+ {+ "group": "Storefront API",+ "pages": [+ "api-reference/storefront/authentication"+ ],+ "openapi": {+ "source": "api-reference/storefront.yaml",+ "directory": "api-reference/storefront"+ }+ },+ {+ "group": "Platform API",+ "pages": [+ "api-reference/platform/authentication"+ ],+ "openapi": {+ "source": "api-reference/platform.yaml",+ "directory": "api-reference/platform"+ }+ }+ ]+ }+ ]+ },+ {+ "tab": "Integrations",+ "groups": [+ {+ "group": "Integrations",+ "pages": [+ "integrations/integrations"+ ]+ },+ {+ "group": "Payments",+ "pages": [+ "integrations/payments/stripe",+ "integrations/payments/adyen",+ "integrations/payments/paypal",+ "integrations/payments/razorpay"+ ]+ },+ {+ "group": "Tax",+ "pages": [+ "integrations/tax/avalara"+ ]+ },+ {+ "group": "Search",+ "pages": [+ "integrations/search/meilisearch"+ ]+ },+ {+ "group": "Analytics",+ "pages": [+ "integrations/analytics/google-analytics",+ "integrations/analytics/google-tag-manager"+ ]+ },+ {+ "group": "Marketing",+ "pages": [+ "integrations/marketing/klaviyo"+ ]+ }+ ]+ },+ {+ "tab": "User Guide",+ "groups": [+ {+ "group": "Introduction",+ "pages": [+ "user/what-is-spree-commerce",+ "user/using-spree",+ "user/user-quickstart-guide"+ ]+ },+ {+ "group": "Migration",+ "pages": [+ "user/migration/migrate-from-shopify"+ ]+ },+ {+ "group": "How-to Guides",+ "pages": [+ "user/how-to/multi-currency-pricing",+ "user/how-to/multiple-languages",+ "user/how-to/multi-region-pricing",+ "user/how-to/wholesale-pricing",+ "user/how-to/volume-pricing",+ "user/how-to/regional-wholesale",+ "user/how-to/regional-volume",+ "user/how-to/schedule-sale-pricing"+ ]+ },+ {+ "group": "Products",+ "pages": [+ {+ "group": "Create & Edit Products",+ "pages": [+ "user/products/creating-products",+ "user/products/deleting-products",+ "user/products/editing-products",+ "user/products/editing-multi-variant-products",+ "user/products/cloning-products"+ ]+ },+ {+ "group": "Manage Products",+ "pages": [+ "user/manage-products/search-products",+ "user/manage-products/bulk-product-operations",+ "user/manage-products/price-lists",+ "user/manage-products/export-products",+ "user/manage-products/import-products",+ "user/manage-products/multi-currency-import-export",+ "user/manage-products/product-import-file-template",+ "user/manage-products/translations",+ "user/manage-products/stock-levels",+ "user/manage-products/stock-transfers",+ "user/manage-products/product-taxonomies",+ "user/manage-products/product-options",+ "user/manage-products/product-metafields"+ ]+ }+ ]+ },+ {+ "group": "Orders",+ "pages": [+ "user/orders/order-states",+ "user/orders/processing-orders",+ "user/orders/creating-orders",+ "user/orders/editing-orders",+ "user/orders/order-adjustments",+ "user/orders/exporting-orders",+ "user/orders/cancelling-orders",+ "user/orders/refunding-orders",+ "user/orders/searching-orders"+ ]+ },+ {+ "group": "Returns",+ "pages": [+ "user/settings/returns-configuration",+ "user/returns/returns-processing"+ ]+ },+ {+ "group": "Customers",+ "pages": [+ "user/customers/create-customer",+ "user/customers/customer-profile",+ "user/customers/edit-customer",+ "user/customers/issue-gift-card",+ "user/customers/assign-store-credits",+ "user/customers/searching-customers",+ "user/customers/exporting-customers",+ "user/customers/customer-groups"+ ]+ },+ {+ "group": "Promotions",+ "pages": [+ "user/promotions/create-a-promotion",+ "user/promotions/promotion-rules",+ "user/promotions/promotion-actions",+ "user/promotions/gift-cards"+ ]+ },+ {+ "group": "Vendors",+ "pages": [+ "user/settings/marketplace",+ "user/vendors/vendor-onboarding-shopify",+ "user/vendors/vendor-onboarding-woocommerce",+ "user/vendors/vendor-onboarding-manual",+ "user/vendors/vendor-management",+ "user/vendors/commission-rates",+ "user/vendors/vendor-payouts",+ "user/vendors/multi-vendor-checkout"+ ]+ },+ {+ "group": "Settings",+ "pages": [+ "user/settings/store-details",+ "user/settings/sales-channels",+ "user/settings/users",+ "user/settings/emails",+ "user/settings/policies",+ "user/settings/payments",+ "user/settings/markets",+ "user/settings/zones",+ "user/settings/shipping-methods",+ "user/settings/tax",+ "user/settings/locations",+ "user/settings/metafields"+ ]+ },+ {+ "group": "Security",+ "pages": [+ "user/security"+ ]+ }+ ]+ },+ {+ "tab": "Solutions",+ "groups": [+ {+ "group": "Overview",+ "pages": [+ "use-case/overview"+ ]+ },+ {+ "group": "B2B Commerce",+ "pages": [+ "use-case/b2b/b2b-commerce-model",+ "use-case/b2b/b2b-capabilities",+ "use-case/b2b/b2b-admin-capabilities",+ "use-case/b2b/b2b-buyer-capabilities"+ ]+ },+ {+ "group": "Digital Products",+ "pages": [+ "use-case/digital-products/model",+ "use-case/digital-products/capabilities",+ "use-case/digital-products/admin-capabilities"+ ]+ },+ {+ "group": "Multi-Tenant Platform",+ "pages": [+ "use-case/multi-tenant/multi-tenant-model",+ "use-case/multi-tenant/multi-tenant-capabilities",+ "use-case/multi-tenant/super-admin-capabilities",+ "use-case/multi-tenant/tenant-capabilities",+ "use-case/multi-tenant/franchises-and-reseller-networks",+ "use-case/multi-tenant/multi-brand-enterprise-model",+ "use-case/multi-tenant/white-label-saas"+ ]+ },+ {+ "group": "Multi-Vendor Marketplace",+ "pages": [+ "use-case/marketplace/model",+ "use-case/marketplace/capabilities",+ "use-case/marketplace/admin-dashboard",+ "use-case/marketplace/vendor-dashboard",+ "use-case/marketplace/customer-ux"+ ]+ }+ ]+ }+ ]+ },+ {+ "version": "v6.x",+ "tag": "beta",+ "tabs": [+ {+ "tab": "Guides",+ "menu": [+ {+ "item": "Getting Started",+ "icon": "rocket",+ "description": "Quickstart guide and core concepts",+ "groups": [+ {+ "group": "Getting started",+ "icon": "rocket",+ "pages": [+ "developer/getting-started/quickstart"+ ]+ },+ {+ "group": "Platform",+ "icon": "settings",+ "pages": [+ "developer/core-concepts/architecture",+ "developer/core-concepts/stores",+ "developer/core-concepts/channels",+ "developer/core-concepts/markets",+ "developer/core-concepts/customers",+ "developer/core-concepts/staff-roles"+ ]+ },+ {+ "group": "Catalog",+ "icon": "package",+ "pages": [+ "developer/core-concepts/products",+ "developer/core-concepts/pricing",+ "developer/core-concepts/inventory",+ "developer/core-concepts/media",+ "developer/core-concepts/search-filtering"+ ]+ },+ {+ "group": "Cart & Checkout",+ "icon": "shopping-cart",+ "pages": [+ "v6/developer/core-concepts/carts",+ "v6/developer/core-concepts/orders",+ "developer/core-concepts/payments",+ "developer/core-concepts/taxes",+ "v6/developer/core-concepts/taxes-discounts-fees",+ "developer/core-concepts/promotions",+ "developer/core-concepts/store-credits-gift-cards"+ ]+ },+ {+ "group": "Fulfillment",+ "icon": "truck",+ "pages": [+ "v6/developer/core-concepts/fulfillments",+ "v6/developer/core-concepts/returns-exchanges-claims",+ "developer/core-concepts/addresses",+ "developer/core-concepts/calculators"+ ]+ },+ {+ "group": "Extensibility",+ "icon": "plug",+ "pages": [+ "developer/core-concepts/events",+ "developer/core-concepts/webhooks",+ "developer/core-concepts/translations",+ "developer/core-concepts/slugs",+ "developer/core-concepts/metafields",+ "developer/core-concepts/imports-exports"+ ]+ }+ ]+ },+ {+ "item": "Building a Storefront",+ "icon": "store",+ "description": "Next.js, custom frontend, or Rails engine",+ "groups": [+ {+ "group": "Next.js Storefront",+ "pages": [+ "developer/storefront/nextjs/quickstart",+ "developer/storefront/nextjs/architecture",+ "developer/storefront/nextjs/multi-region",+ "developer/storefront/nextjs/customization",+ "developer/storefront/nextjs/emails",+ "developer/storefront/nextjs/wholesale",+ "developer/storefront/nextjs/wallet-payments",+ "developer/storefront/nextjs/testing",+ "developer/storefront/nextjs/environment-variables",+ "developer/storefront/nextjs/deployment"+ ]+ }+ ]+ },+ {+ "item": "Use Cases",+ "icon": "book-open",+ "description": "Multi-store/multi-tenant, and marketplace setups",+ "groups": [+ {+ "group": "Multi-Tenant / Multi-Store",+ "pages": [+ "developer/multi-tenant/quickstart",+ "developer/multi-tenant/core-concepts",+ "developer/multi-tenant/configuration"+ ]+ },+ {+ "group": "Multi-Vendor Marketplace",+ "pages": [+ "developer/multi-vendor/quickstart",+ "developer/multi-vendor/installation"+ ]+ }+ ]+ }+ ]+ },+ {+ "tab": "Framework",+ "menu": [+ {+ "item": "Extending",+ "icon": "puzzle",+ "description": "Customize Checkout, API, and business logic",+ "groups": [+ {+ "group": "Tutorial",+ "icon": "graduation-cap",+ "pages": [+ "developer/tutorial/introduction",+ "developer/tutorial/model",+ "developer/tutorial/admin",+ "developer/tutorial/extending-models",+ "developer/tutorial/api",+ "developer/tutorial/events",+ "developer/tutorial/sdk",+ "developer/tutorial/testing"+ ]+ },+ {+ "group": "Backend Customization",+ "icon": "wrench",+ "pages": [+ "v6/developer/customization/quickstart",+ "v6/developer/customization/configuration",+ "developer/customization/workflows",+ "developer/customization/api",+ "developer/customization/model-preferences",+ "developer/customization/metadata",+ "v6/developer/customization/dependencies",+ "developer/customization/decorators"+ ]+ }+ ]+ },+ {+ "item": "How-to Guides",+ "icon": "book-open",+ "description": "Step-by-step guides for common tasks",+ "groups": [+ {+ "group": "Order Routing",+ "icon": "route",+ "pages": [+ "developer/how-to/custom-order-routing"+ ]+ },+ {+ "group": "Stock Splitters",+ "icon": "boxes-stacked",+ "pages": [+ "developer/how-to/custom-stock-splitter"+ ]+ },+ {+ "group": "Payments",+ "icon": "credit-card",+ "pages": [+ "developer/how-to/custom-payment-method"+ ]+ },+ {+ "group": "Promotions",+ "icon": "tag",+ "pages": [+ "developer/how-to/custom-promotion"+ ]+ },+ {+ "group": "Reports",+ "icon": "chart-bar",+ "pages": [+ "developer/how-to/custom-report"+ ]+ },+ {+ "group": "Search",+ "icon": "search",+ "pages": [+ "developer/how-to/custom-search-provider"+ ]+ },+ {+ "group": "Authentication",+ "icon": "key",+ "pages": [+ "developer/how-to/custom-api-authentication"+ ]+ }+ ]+ },+ {+ "item": "Dashboard",+ "icon": "gauge",+ "description": "React dashboard",+ "groups": [+ {+ "group": "Overview",+ "pages": [+ "developer/dashboard/overview",+ "developer/dashboard/concepts"+ ]+ },+ {+ "group": "Customization",+ "pages": [+ "developer/dashboard/customization/quickstart",+ "developer/dashboard/customization/navigation",+ "developer/dashboard/customization/routes",+ "developer/dashboard/customization/slots",+ "developer/dashboard/customization/tables",+ "developer/dashboard/customization/translations",+ "developer/dashboard/customization/permissions",+ "developer/dashboard/customization/backend"+ ]+ },+ {+ "group": "Recipes",+ "pages": [+ "developer/dashboard/recipes/attribute-end-to-end",+ "developer/dashboard/recipes/custom-form-field",+ "developer/dashboard/recipes/page-action-button",+ "developer/dashboard/recipes/sidebar-widget"+ ]+ },+ {+ "group": "Plugins",+ "pages": [+ "developer/dashboard/plugins/overview",+ "developer/dashboard/plugins/scaffolding",+ "developer/dashboard/plugins/publishing",+ "developer/dashboard/plugins/distributing"+ ]+ },+ {+ "group": "Reference",+ "pages": [+ "developer/dashboard/public-api",+ "developer/dashboard/slots-catalog",+ "developer/dashboard/deployment"+ ]+ }+ ]+ },+ {+ "item": "Operations",+ "icon": "server",+ "description": "Deploy, upgrade, and maintain your store",+ "groups": [+ {+ "group": "Deployment",+ "icon": "server",+ "pages": [+ "developer/deployment/quickstart",+ "developer/deployment/docker",+ "developer/deployment/environment_variables",+ {+ "group": "AWS",+ "pages": [+ "developer/deployment/aws",+ "developer/deployment/aws_ecs"+ ]+ },+ "developer/deployment/render",+ "developer/deployment/assets",+ "developer/deployment/emails",+ "developer/deployment/cdn",+ "developer/deployment/background_jobs",+ "developer/deployment/caching",+ "developer/deployment/database"+ ]+ },+ {+ "group": "Upgrading",+ "icon": "circle-arrow-up",+ "pages": [+ "developer/upgrades/quickstart",+ {+ "group": "Upgrade Guides",+ "pages": [+ "developer/upgrades/5.5-to-5.6",+ "developer/upgrades/5.4-to-5.5",+ "developer/upgrades/5.3-to-5.4",+ "developer/upgrades/5.2-to-5.3",+ "developer/upgrades/5.1-to-5.2",+ "developer/upgrades/5.0-to-5.1",+ "developer/upgrades/4.10-to-5.0",+ "developer/upgrades/4.9-to-4.10",+ "developer/upgrades/4.8-to-4.9",+ "developer/upgrades/4.x-to-4.8",+ "developer/upgrades/4.6-to-4.7",+ "developer/upgrades/4.5-to-4.6",+ "developer/upgrades/4.4-to-4.5",+ "developer/upgrades/4.3-to-4.4",+ "developer/upgrades/4.2-to-4.3",+ "developer/upgrades/4.1-to-4.2",+ "developer/upgrades/4.0-to-4.1",+ "developer/upgrades/3.7-to-4.0",+ "developer/upgrades/3.6-to-3.7",+ "developer/upgrades/3.5-to-3.6",+ "developer/upgrades/3.4-to-3.5",+ "developer/upgrades/3.3-to-3.4",+ "developer/upgrades/3.2-to-3.3",+ "developer/upgrades/3.1-to-3.2",+ "developer/upgrades/3.0-to-3.1",+ "developer/upgrades/2.3-to-2.4",+ "developer/upgrades/2.2-to-2.3",+ "developer/upgrades/2.1-to-2.2",+ "developer/upgrades/2.0-to-2.1"+ ]+ }+ ]+ },+ {+ "group": "Contributing",+ "icon": "heart",+ "pages": [+ "developer/contributing/quickstart",+ "developer/contributing/developing-spree",+ "developer/contributing/creating-an-extension"+ ]+ },+ {+ "group": "Security",+ "icon": "shield",+ "pages": [+ "developer/security/security_policy",+ "developer/security/pci_compliance"+ ]+ }+ ]+ }+ ]+ },+ {+ "tab": "SDK & Tools",+ "menu": [+ {+ "item": "Store SDK",+ "icon": "code",+ "description": "TypeScript SDK for the Store API",+ "groups": [+ {+ "group": "Getting Started",+ "pages": [+ "developer/sdk/quickstart",+ "developer/sdk/authentication",+ "developer/sdk/configuration",+ "developer/sdk/extending"+ ]+ },+ {+ "group": "Store API",+ "pages": [+ "developer/sdk/store/products",+ "developer/sdk/store/cart-checkout",+ "developer/sdk/store/payments",+ "developer/sdk/store/markets",+ "developer/sdk/store/account",+ "developer/sdk/store/wishlists"+ ]+ }+ ]+ },+ {+ "item": "Admin SDK",+ "icon": "shield-check",+ "description": "TypeScript SDK for the Admin API",+ "groups": [+ {+ "group": "Admin SDK",+ "pages": [+ "developer/sdk/admin/quickstart",+ "developer/sdk/admin/authentication",+ "developer/sdk/admin/resources",+ "developer/sdk/admin/querying-and-errors",+ "developer/sdk/admin/extending"+ ]+ }+ ]+ },+ {+ "item": "CLI",+ "icon": "square-terminal",+ "description": "Command-line interface for Spree",+ "groups": [+ {+ "group": "CLI",+ "pages": [+ "developer/cli/quickstart",+ "developer/cli/admin-api"+ ]+ }+ ]+ },+ {+ "item": "create-spree-app",+ "icon": "rocket",+ "description": "Scaffold a new Spree project",+ "groups": [+ {+ "group": "create-spree-app",+ "pages": [+ "developer/create-spree-app/quickstart"+ ]+ }+ ]+ },+ {+ "item": "Agentic Development",+ "icon": "bot",+ "description": "Build Spree with AI coding agents",+ "groups": [+ {+ "group": "Agentic Development",+ "pages": [+ "developer/agentic/overview",+ "developer/agentic/agent-skills",+ "developer/agentic/mcp",+ "developer/agentic/llm-docs"+ ]+ }+ ]+ }+ ]+ },+ {+ "tab": "API Reference",+ "menu": [+ {+ "item": "Store API",+ "icon": "store",+ "description": "REST API for storefronts and custom integrations",+ "groups": [+ {+ "group": "API basics",+ "pages": [+ "api-reference/store-api/introduction",+ "api-reference/store-api/authentication",+ "api-reference/store-api/errors",+ "api-reference/store-api/idempotency",+ "api-reference/store-api/rate-limitting",+ "api-reference/store-api/querying",+ "api-reference/store-api/relations",+ "api-reference/store-api/metadata",+ "api-reference/store-api/localization",+ "api-reference/store-api/monetary-amounts",+ "api-reference/store-api/migrating-from-storefront-api-v2"+ ]+ },+ {+ "group": "Endpoints",+ "openapi": {+ "source": "api-reference/store.yaml",+ "directory": "api-reference/store-api"+ }+ }+ ]+ },+ {+ "item": "Admin API",+ "icon": "shield",+ "description": "REST API for pragmatically managing stores",+ "groups": [+ {+ "group": "API basics",+ "pages": [+ "api-reference/admin-api/introduction",+ "api-reference/admin-api/authentication",+ "api-reference/admin-api/errors",+ "api-reference/admin-api/querying",+ "api-reference/admin-api/monetary-amounts",+ "api-reference/admin-api/endpoints"+ ]+ },+ {+ "group": "Endpoints",+ "openapi": {+ "source": "api-reference/admin.yaml",+ "directory": "api-reference/admin-api"+ }+ }+ ]+ },+ {+ "item": "Webhooks",+ "icon": "webhook",+ "description": "Event payloads and delivery reference",+ "groups": [+ {+ "group": "Webhooks",+ "pages": [+ "api-reference/webhooks-events"+ ]+ }+ ]+ },+ {+ "item": "Legacy API v2",+ "icon": "clock",+ "description": "Previous-generation Storefront and Platform APIs",+ "groups": [+ {+ "group": "API basics",+ "pages": [+ "api-reference/v2/introduction",+ "api-reference/v2/pagination",+ "api-reference/v2/filtering-and-sorting",+ "api-reference/v2/fetching-multiple-resources"+ ]+ },+ {+ "group": "Tutorials",+ "pages": [+ "api-reference/tutorials/quick-checkout-with-stripe",+ "api-reference/tutorials/adyen-integration-guide-for-android",+ "api-reference/tutorials/adyen-integration-guide-for-ios"+ ]+ },+ {+ "group": "Storefront API",+ "pages": [+ "api-reference/storefront/authentication"+ ],+ "openapi": {+ "source": "api-reference/storefront.yaml",+ "directory": "api-reference/storefront"+ }+ },+ {+ "group": "Platform API",+ "pages": [+ "api-reference/platform/authentication"+ ],+ "openapi": {+ "source": "api-reference/platform.yaml",+ "directory": "api-reference/platform"+ }+ }+ ]+ }+ ]+ },+ {+ "tab": "Integrations",+ "groups": [+ {+ "group": "Integrations",+ "pages": [+ "integrations/integrations"+ ]+ },+ {+ "group": "Payments",+ "pages": [+ "integrations/payments/stripe",+ "integrations/payments/adyen",+ "integrations/payments/paypal",+ "integrations/payments/razorpay"+ ]+ },+ {+ "group": "Tax",+ "pages": [+ "integrations/tax/avalara"+ ]+ },+ {+ "group": "Search",+ "pages": [+ "integrations/search/meilisearch"+ ]+ },+ {+ "group": "Analytics",+ "pages": [+ "integrations/analytics/google-analytics",+ "integrations/analytics/google-tag-manager"+ ]+ },+ {+ "group": "Marketing",+ "pages": [+ "integrations/marketing/klaviyo"+ ]+ }+ ]+ },+ {+ "tab": "User Guide",+ "groups": [+ {+ "group": "Introduction",+ "pages": [+ "user/what-is-spree-commerce",+ "user/using-spree",+ "user/user-quickstart-guide"+ ]+ },+ {+ "group": "Migration",+ "pages": [+ "user/migration/migrate-from-shopify"+ ]+ },+ {+ "group": "How-to Guides",+ "pages": [+ "user/how-to/multi-currency-pricing",+ "user/how-to/multiple-languages",+ "user/how-to/multi-region-pricing",+ "user/how-to/wholesale-pricing",+ "user/how-to/volume-pricing",+ "user/how-to/regional-wholesale",+ "user/how-to/regional-volume",+ "user/how-to/schedule-sale-pricing"+ ]+ },+ {+ "group": "Products",+ "pages": [+ {+ "group": "Create & Edit Products",+ "pages": [+ "user/products/creating-products",+ "user/products/deleting-products",+ "user/products/editing-products",+ "user/products/editing-multi-variant-products",+ "user/products/cloning-products"+ ]+ },+ {+ "group": "Manage Products",+ "pages": [+ "user/manage-products/search-products",+ "user/manage-products/bulk-product-operations",+ "user/manage-products/price-lists",+ "user/manage-products/export-products",+ "user/manage-products/import-products",+ "user/manage-products/multi-currency-import-export",+ "user/manage-products/product-import-file-template",+ "user/manage-products/translations",+ "user/manage-products/stock-levels",+ "user/manage-products/stock-transfers",+ "user/manage-products/product-taxonomies",+ "user/manage-products/product-options",+ "user/manage-products/product-metafields"+ ]+ }+ ]+ },+ {+ "group": "Orders",+ "pages": [+ "user/orders/order-states",+ "user/orders/processing-orders",+ "user/orders/creating-orders",+ "user/orders/editing-orders",+ "user/orders/order-adjustments",+ "user/orders/exporting-orders",+ "user/orders/cancelling-orders",+ "user/orders/refunding-orders",+ "user/orders/searching-orders"+ ]+ },+ {+ "group": "Returns",+ "pages": [+ "user/settings/returns-configuration",+ "user/returns/returns-processing"+ ]+ },+ {+ "group": "Customers",+ "pages": [+ "user/customers/create-customer",+ "user/customers/customer-profile",+ "user/customers/edit-customer",+ "user/customers/issue-gift-card",+ "user/customers/assign-store-credits",+ "user/customers/searching-customers",+ "user/customers/exporting-customers",+ "user/customers/customer-groups"+ ]+ },+ {+ "group": "Promotions",+ "pages": [+ "user/promotions/create-a-promotion",+ "user/promotions/promotion-rules",+ "user/promotions/promotion-actions",+ "user/promotions/gift-cards"+ ]+ },+ {+ "group": "Vendors",+ "pages": [+ "user/settings/marketplace",+ "user/vendors/vendor-onboarding-shopify",+ "user/vendors/vendor-onboarding-woocommerce",+ "user/vendors/vendor-onboarding-manual",+ "user/vendors/vendor-management",+ "user/vendors/commission-rates",+ "user/vendors/vendor-payouts",+ "user/vendors/multi-vendor-checkout"+ ]+ },+ {+ "group": "Settings",+ "pages": [+ "user/settings/store-details",+ "user/settings/sales-channels",+ "user/settings/users",+ "user/settings/emails",+ "user/settings/policies",+ "user/settings/payments",+ "user/settings/markets",+ "user/settings/zones",+ "user/settings/shipping-methods",+ "user/settings/tax",+ "user/settings/locations",+ "user/settings/metafields"+ ]+ },+ {+ "group": "Security",+ "pages": [+ "user/security"+ ]+ }+ ]+ },+ {+ "tab": "Solutions",+ "groups": [+ {+ "group": "Overview",+ "pages": [+ "use-case/overview"+ ]+ },+ {+ "group": "B2B Commerce",+ "pages": [+ "use-case/b2b/b2b-commerce-model",+ "use-case/b2b/b2b-capabilities",+ "use-case/b2b/b2b-admin-capabilities",+ "use-case/b2b/b2b-buyer-capabilities"+ ]+ },+ {+ "group": "Digital Products",+ "pages": [+ "use-case/digital-products/model",+ "use-case/digital-products/capabilities",+ "use-case/digital-products/admin-capabilities"+ ]+ },+ {+ "group": "Multi-Tenant Platform",+ "pages": [+ "use-case/multi-tenant/multi-tenant-model",+ "use-case/multi-tenant/multi-tenant-capabilities",+ "use-case/multi-tenant/super-admin-capabilities",+ "use-case/multi-tenant/tenant-capabilities",+ "use-case/multi-tenant/franchises-and-reseller-networks",+ "use-case/multi-tenant/multi-brand-enterprise-model",+ "use-case/multi-tenant/white-label-saas"+ ]+ },+ {+ "group": "Multi-Vendor Marketplace",+ "pages": [+ "use-case/marketplace/model",+ "use-case/marketplace/capabilities",+ "use-case/marketplace/admin-dashboard",+ "use-case/marketplace/vendor-dashboard",+ "use-case/marketplace/customer-ux"+ ]+ }+ ]+ }+ ]+ }+ ],"tabs": [{"tab": "Guides",@@ -1027,8 +2619,8 @@}},{- "label": "v5.5.0",- "href": "https://github.com/spree/spree/releases/tag/v5.5.0"+ "label": "v5.6.0",+ "href": "https://github.com/spree/spree/releases/tag/v5.6.0"},{"label": "Join Discord",diff --git a/docs/plans/6.0-stock-reservations.md b/docs/plans/6.0-stock-reservations.mdindex efa4d23d2e..75cac55672 100644--- a/docs/plans/6.0-stock-reservations.md+++ b/docs/plans/6.0-stock-reservations.md@@ -29,8 +29,8 @@ Every modern commerce platform solves this with time-limited reservations.- **`StockItem.count_on_hand` is never modified by reservations.** It only changes on order completion (decrement) or stock adjustment. Reservations are a soft hold computed at query time.- **Available quantity = `count_on_hand - allocated_count - active_reservations`** — the `Quantifier` is updated to subtract both allocations (from 6.0-typed-stock-movements.md) and active reservations from physical stock. **In 5.5 the `allocated_count` term is omitted** — it lands with Typed Stock Movements in 6.0. The 5.5 formula is `count_on_hand - active_reservations`.- **Store API only in 5.5.** Reservation create/extend/release hooks fire from Store API endpoints (`Spree::Api::V3::Storefront::*`) only. Legacy Rails storefront (`Spree::CheckoutController`) and v2 API are intentionally not wired. Other customers' availability still reflects reservations (Quantifier subtracts them globally) — they just can't create their own from non-v3 paths. Release-note this clearly.-- **Configurable trigger** — `Spree::Config[:reserve_stock_on]` controls when reservations are created: `:checkout` (when entering checkout, default) or `:cart` (when adding to cart). Cart-level is more aggressive, checkout-level is the standard.-- **Configurable TTL per store, with global default** — `store.preferred_stock_reservation_ttl_minutes` overrides `Spree::Config[:default_stock_reservation_ttl_minutes]` (default: 10). Resolved by `Spree::StockReservation.ttl_for(order)`. **TTL deliberately lives on Store, not StockLocation** — it's a checkout-experience policy, not a warehouse property. A multi-location cart never has to merge conflicting TTLs from different warehouses. If future merchants need differentiation, the natural next move is splitting TTL by guest vs authenticated customer on the Store, not by location. BOPIS lead time belongs on `StockLocation#pickup_ready_in_minutes` (see `6.0-fulfillment-and-delivery.md`), which is a different concept.+- **Configurable trigger** — ~~`Spree::Config[:reserve_stock_on]` controls when reservations are created: `:checkout` (when entering checkout, default) or `:cart` (when adding to cart). Cart-level is more aggressive, checkout-level is the standard.~~ **Superseded (2026-08-04):** the Cart/Order split wired `Reserve` directly into the cart flows (`Carts::AddItem`, `Carts::SetQuantity`, `Carts::RemoveLineItem`, `Carts::Update`), gated only on `Spree::Config[:stock_reservations_enabled]`. A usage audit found the trigger switch has no read sites anywhere; the short TTL already bounds cart-level aggressiveness. `reserve_stock_on` is retired via `6.0-store-scoped-configuration.md` (deprecated shell in 6.0, deleted in 6.1).+- **Configurable TTL per store, with global default** — `store.preferred_stock_reservation_ttl_minutes` overrides `Spree::Config[:default_stock_reservation_ttl_minutes]` (default: 10). *(2026-08-04: the global fallback proved unreachable — the Store preference carries its own `default: 10` and a `greater_than: 0` validation, so it is never blank. `6.0-store-scoped-configuration.md` deprecates the global; `ttl_for` keeps its hard 10-minute floor for storeless contexts.)* Resolved by `Spree::StockReservation.ttl_for(order)`. **TTL deliberately lives on Store, not StockLocation** — it's a checkout-experience policy, not a warehouse property. A multi-location cart never has to merge conflicting TTLs from different warehouses. If future merchants need differentiation, the natural next move is splitting TTL by guest vs authenticated customer on the Store, not by location. BOPIS lead time belongs on `StockLocation#pickup_ready_in_minutes` (see `6.0-fulfillment-and-delivery.md`), which is a different concept.- **Reservations extend on activity** — each checkout interaction (address update, shipping selection, payment) resets `expires_at` to prevent expiry during active checkout.- **Background job expires reservations** — `Spree::StockReservations::ExpireJob` runs periodically, deletes expired records. Simple `DELETE WHERE expires_at < NOW()`.- **On order completion: reservation deleted, `count_on_hand` decremented** — the existing stock decrement logic stays, reservation is just cleaned up.@@ -325,8 +325,10 @@ GET /api/v3/admin/stock_reservations?filter[variant_id]=variant_xxx### Configuration```ruby-Spree::Config[:stock_reservations_enabled] = true # default: true-Spree::Config[:reserve_stock_on] = :checkout # :checkout or :cart+# 6.0: both move to Store preferences — see 6.0-store-scoped-configuration.md.+# `reserve_stock_on` is retired (never read); the TTL global is deprecated+# because the Store preference below always wins.+store.preferred_stock_reservations_enabled = true # default: true# Per-store TTL (minutes)store.preferred_stock_reservation_ttl_minutes = 10 # default: 10diff --git a/docs/plans/6.0-store-scoped-configuration.md b/docs/plans/6.0-store-scoped-configuration.mdnew file mode 100644index 0000000000..4759794299--- /dev/null+++ b/docs/plans/6.0-store-scoped-configuration.md@@ -0,0 +1,127 @@+# Store-Scoped Configuration++**Status:** Design finalized, implementation not started+**Target:** Spree 6.0 (globals deleted in 6.1)+**Depends on:** Single-owner Product (`6.1-channels-catalogs-b2b.md`, shipped 5.5), Cart/Order split (`6.0-cart-order-split.md`), Tax provider (`6.0-tax-provider.md`, for the `tax_using_ship_address` retirement)+**Author:** Damian + Claude+**Last updated:** 2026-08-04++## Summary++A full usage audit of `Spree::Config` (2026-08-04, multi-agent trace with adversarial verification over all 68 preferences) found 38 genuinely live settings, 6 read only by subsystems 6.0 replaced, and 7 with zero read sites anywhere. The live settings split into two kinds: **application configuration** (security, limits, jobs, URLs — properties of the installation) and **commerce behavior** (capture timing, inventory tracking, catalog visibility — properties of a store). Now that Products, Promotions, PaymentMethods and StockLocations are single-store resources, a global flag for per-store behavior is a design smell. This plan moves nine commerce-behavior globals to `Spree::Store` preferences — finishing the migration that `company` → `company_field_enabled` and `allow_guest_checkout` → `guest_checkout` already started — and retires the dead ones.++## Problem++One finding motivates the whole plan. `default_stock_reservation_ttl_minutes` is read only when the Store preference it backs is blank — but `Store#stock_reservation_ttl_minutes` carries `default: 10` and a `greater_than: 0` validation, so it is *never* blank. The global has been silently unreachable for every order with a store, and because both default to 10 nobody noticed.++That is what two sources of truth for one behavior produces: one quietly wins, the other becomes a lie in the documentation. The audit found the same shape forming elsewhere — `auto_capture` exists both globally and as a per-payment-method column, and the dashboard only exposes the column.++## Classification test++**Would a second store on the same installation plausibly want a different value?**++- Yes → Store preference (an EU store needs `track_price_history`; its non-EU sibling doesn't)+- No → stays in `Spree.config` (password length protects the app, not a shop)++## Key Decisions (do not deviate without discussion)++- **The nine movers** (identical names on Store, defaults unchanged):++ | Global today | Store preference | Default |+ |---|---|---|+ | `auto_capture` | `preferred_auto_capture` | `true` |+ | `auto_capture_on_dispatch` | `preferred_auto_capture_on_dispatch` | `false` |+ | `allow_checkout_on_gateway_error` | `preferred_allow_checkout_on_gateway_error` | `false` |+ | `track_inventory_levels` | `preferred_track_inventory_levels` | `true` |+ | `stock_reservations_enabled` | `preferred_stock_reservations_enabled` | `true` |+ | `track_price_history` | `preferred_track_price_history` | `true` |+ | `show_products_without_price` | `preferred_show_products_without_price` | `false` |+ | `address_requires_phone` | `preferred_address_requires_phone` | `false` |+ | `disable_sku_validation` | `preferred_disable_sku_validation` | `false` |++- **Store preference is authoritative — no runtime fallback to the global** (decided 2026-08-04). Core reads the store preference and the declared default, never the old global. A fallback chain would reintroduce exactly the drift that made `default_stock_reservation_ttl_minutes` unreachable. The `company` precedent already works this way.+- **A backfill rake carries existing installs over**, not a fallback: `spree:store_settings:backfill_from_config` copies each global whose value differs from its default onto every store. Added to the 5.6→6.0 upgrade manifest (same mechanism as `sanitize_rich_text`). Idempotent; logs each store and setting it writes.+- **Globals become deprecated shells for one release** (`deprecated: 'Set …on the store'` in the preference DSL, which warns through `Spree::Deprecation` on access), deleted in 6.1. Repo-wide deprecation-bridge rule.+- **`auto_capture` resolution chain:** payment method column when not `nil` → store preference. The dashboard already exposes the per-method column; the store preference replaces only the global fallback in `PaymentMethod#auto_capture?` (`payment_method.rb:178`). The per-method column stays the primary control.+- **Storeless contexts read `Spree::Current.store`, falling back to the declared default** (decided 2026-08-04). Two readers have no record-level store: `Address` (no store association) and the `Product` availability scope (class-level). Both resolve through `Spree::Current.store`. Accepted trade-off: validation or a catalog query run outside a request — a console session, a seed, a job that forgets to set the store — silently uses the default rather than the store's value. This is why the alternative (threading a store argument through every caller, breaking a public scope) was rejected as disproportionate. **Any job that validates addresses or queries the catalog must set `Spree::Current.store`.**+- **`default_stock_reservation_ttl_minutes` is deprecated, not moved.** `Store#stock_reservation_ttl_minutes` already owns the value. `StockReservation.ttl_for` drops the global read and keeps its hard 10-minute floor for storeless contexts.+- **`track_price_history` goes to Store in 6.0, with Market as a noted future refinement** (decided 2026-08-04). EU Omnibus is per-country law, and Market already owns `return_window_days` and the other legal settings — but prices are not market-scoped today, so a Market home needs design work this plan will not carry. Store now; revisit when price/market scoping is on the table.+- **Stay global despite looking behavioral:** `credit_to_new_allocation` (ledger-shape convention — per-store variance makes one install's accounting inconsistent) and `non_expiring_credit_types` (reference data).+- **The seven dead settings get deprecation shells in 6.0, deleted in 6.1:** `products_per_page`, `alternative_shipping_phone`, `show_variant_full_price`, `reserve_stock_on`, `storefront_products_path`, `storefront_taxons_path`, `storefront_pages_path`. Zero read sites, audit-verified including dynamic-lookup forms. Shells only so an initializer that sets one doesn't crash boot mid-upgrade.+- **Already deprecated this cycle, recorded here for completeness:** `tax_using_ship_address` (the tax provider owns address choice per market), `allow_empty_price_amount` (price lists already allow blank), `always_include_confirm_step` (confirm is an advertised step, never enforced — the storefront renders a review screen when it wants one), `restock_inventory` / `return_eligibility_number_of_days` / `expedited_exchanges` / `expedited_exchanges_days_window` (the returns rework owns these), `use_user_locale` (locale comes from `x-spree-locale` or the `locale` param), `enable_legacy_default_price` (leave off).+- **New behavior flags never start global.** From 6.0 on, a setting that shapes how a store sells is born on Store (or Market/Channel where regional), never in `Spree.config`.++## Design Details++### Read sites to re-point (from the audit)++| Setting | Read sites | Store reached via |+|---|---|---|+| `auto_capture` | `payment_method.rb:178` | PaymentMethod is store-owned |+| `auto_capture_on_dispatch` | `fulfillment.rb:280,615` | fulfillment → order/cart → store |+| `allow_checkout_on_gateway_error` | `purchase/payment_processing.rb:67` | concern on Cart/Order — `store` is present |+| `track_inventory_levels` | `variant.rb:669`, `product.rb:868` | variant → product → store |+| `stock_reservations_enabled` | `stock_reservations/reserve.rb:11`, `extend.rb:11`, `stock/quantifier.rb:69` | cart/order → store; stock_item → stock_location → store |+| `track_price_history` | `price.rb:189` | price → variant → product → store |+| `show_products_without_price` | `product_scopes.rb:322` | `Spree::Current.store` (class-level scope) |+| `address_requires_phone` | `address.rb:66,210`, `addresses/phone_validator.rb:11` | `Spree::Current.store` (no store association) |+| `disable_sku_validation` | `variant.rb:84,774` | variant → product → store |++`Product.store` is `optional: true` (`product/channels.rb:12`), so every re-pointed reader keeps the preference default as its nil-store fallback.++### Admin API + Dashboard++Store preferences already flow through the Admin API v3 store settings surface and the dashboard settings pages. Phase 2 adds the nine to the store serializer and permitted params, and surfaces them in the relevant dashboard sections (payments, inventory, catalog, checkout). Serializer changes ride the type-generation pipeline.++### Incidental fixes (do regardless of the move)++- `coupon_codes_total_limit` is interpolated into the `Promotion` numericality validation at class-load time (`promotion.rb:68`), so setting it in an initializer that loads later has no effect until restart. Make the validation option a lambda.+- The definition comment on `disable_sku_validation` (`configuration.rb:52`, "when turned off disables") is backwards — `true` disables the validation.+- `storefront_products_path` isn't merely unread: `base_helper.rb:37` and the Google feed presenter hardcode `/products/`, so overriding it today silently produces broken feed URLs. Deleting it makes that explicit.++## Migration Path++### Phase 1 (6.0): move + deprecate++1. Add the nine preferences to `Spree::Store` with defaults matching the globals.+2. Re-point the read sites per the table above; `Address` and the product scope read `Spree::Current.store`.+3. Mark the nine globals plus the seven dead settings `deprecated:` in `spree/core/lib/spree/core/configuration.rb`.+4. Ship `spree:store_settings:backfill_from_config` and add it to the 5.6→6.0 upgrade manifest.+5. `StockReservation.ttl_for` drops its global read.++### Phase 2 (6.0): expose++6. Admin API v3 store serializer and permitted params for the nine; regenerate types.+7. Dashboard settings pages gain the new toggles in their natural sections.+8. Docs: `docs/v6/developer/customization/configuration.mdx` already carries the commerce/application split — move the nine into the store-settings docs once shipped.++### Phase 3 (6.1): delete++9. Delete the nine deprecated globals, the seven dead settings, and the legacy shells listed above.++## Constraints on Current Work++- **Don't add new `Spree::Config` reads of the nine movers.** New code needing one of these values should read it from the store, or take it as an argument, so Phase 1 has fewer sites to chase.+- **New behavior flags go on Store from the start** — never add a commerce-behavior preference to `Spree.config`.+- **Don't build UI against the global `auto_capture`.** The dashboard exposes the per-method column; that stays the primary control.+- **Background jobs that validate addresses or query the catalog must set `Spree::Current.store`** — after Phase 1 those paths read the ambient store and will otherwise silently use defaults.+- The v6 configuration docs page keeps its commerce/application two-group structure; new settings slot into the right group.++## Open Questions++None blocking. Settled 2026-08-04: storeless reads use `Spree::Current.store` with a default fallback; `track_price_history` goes to Store with Market noted as a future refinement; upgrade is a backfill rake with no runtime fallback.++Deferred, not blocking:++- **Market-scoped `track_price_history`.** Revisit when price/market scoping is designed; needs prices to be market-aware first.+- **Cart expiry settings** (`guest_cart_expiry_days` and siblings) stay application housekeeping. Per-store retention deferred until someone asks.++## References++- Config usage audit, 2026-08-04 — multi-agent trace with adversarial verification; 38 active / 6 legacy / 7 unused of 51 non-deprecated preferences+- Precedents: `company` → `Store#company_field_enabled` (`configuration.rb:47`), `allow_guest_checkout` → `Store#guest_checkout`, `Store#stock_reservation_ttl_minutes` (`store.rb:58`)+- `5.6-6.0-single-store-promotions-payment-methods.md` — the backfill + deprecation-bridge pattern this plan reuses+- `6.0-tax-provider.md` — owns the `tax_using_ship_address` retirement+- `6.0-returns-exchanges-claims.md` — owns the returns-related retirements+- `6.0-stock-reservations.md` — carries the superseding note for `reserve_stock_on` and the TTL global+- Docs page: `docs/v6/developer/customization/configuration.mdx`diff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex ea67637255..5f64c59154 100644--- a/docs/plans/decisions.md+++ b/docs/plans/decisions.md@@ -1,3 +1,58 @@+## 2026-08-04: Commerce-behavior globals move to Store preferences; app configuration stays global++A full usage audit of `Spree::Config` (multi-agent trace with adversarial+verification over all 68 preferences) found 38 genuinely live settings, 6 read+only by subsystems 6.0 replaced, and 7 with zero read sites anywhere. One of the+38 — `default_stock_reservation_ttl_minutes` — has a read site but is *silently+unreachable*: the Store preference it falls back from carries its own default+and a `> 0` validation, so it is never blank. Both default to 10, so nobody+noticed.+That failure mode is the argument for the whole decision: two sources of truth+for one behavior, where one quietly wins and the documentation becomes a lie.++**The classification test:** would a second store on the same installation+plausibly want a different value? Yes → the setting belongs on `Spree::Store`+(an EU store needs `track_price_history`; its sibling doesn't). No → it stays+in `Spree.config` (password length protects the app, not a shop).++Nine globals move in 6.0 — `auto_capture` (the per-payment-method column still+wins when set), `auto_capture_on_dispatch`, `allow_checkout_on_gateway_error`,+`track_inventory_levels`, `stock_reservations_enabled`, `track_price_history`,+`show_products_without_price`, `address_requires_phone`,+`disable_sku_validation`. The store preference is **authoritative with no+runtime fallback to the global**; existing installs carry over through+`spree:store_settings:backfill_from_config` in the upgrade manifest, and the+globals live one release as deprecated shells. A fallback chain was explicitly+rejected — it is the shape that produced the unreachable TTL. This finishes the+migration `company` → `Store#company_field_enabled` and `allow_guest_checkout`+→ `Store#guest_checkout` already started.++Two readers have no record-level store: `Address` (no association) and the+class-level product availability scope. Both read `Spree::Current.store` and+fall back to the declared default. The trade-off is accepted knowingly —+validation or a catalog query outside a request uses the default — because the+alternative, threading a store argument through every caller and breaking a+public scope, is disproportionate. Jobs touching those paths must set+`Spree::Current.store`.++`track_price_history` goes to Store rather than Market despite Omnibus being+per-country law: Market already owns `return_window_days` and the other legal+settings, but prices are not market-scoped today, so a Market home needs design+this plan won't carry. Noted as a 6.1 refinement. Two behavior-looking settings+stay global: `credit_to_new_allocation` (ledger-shape convention — per-store+variance corrupts one install's accounting) and `non_expiring_credit_types`+(reference data).++Corollary settled at the same time: **new behavior flags are born on Store** (or+Market/Channel where regional), never in `Spree.config`. Also retired on the+evidence: `reserve_stock_on` (the Cart/Order split wired reservations into the+cart flows gated on `stock_reservations_enabled`; the trigger switch was never+read — superseding note added to `6.0-stock-reservations.md`) and the confirm+checkout step as a configuration concern (`confirm` is advertised, never+enforced — a storefront renders a review screen when it wants one;+`PaymentMethod#confirmation_required?` is the real, unrelated requirement).+Plan: `6.0-store-scoped-configuration.md`.+## 2026-08-03: Return eligibility ships as a hook, not a policy engine — enforced in the workflow, scoped per marketA survey of Shopify, Medusa, Saleor and Vendure settled how far 6.0 goes ondiff --git a/docs/v6/developer/core-concepts/carts.mdx b/docs/v6/developer/core-concepts/carts.mdxnew file mode 100644index 0000000000..1310eee9f7--- /dev/null+++ b/docs/v6/developer/core-concepts/carts.mdx@@ -0,0 +1,209 @@+---+title: Carts+description: How Spree models the shopping and checkout phase — a cart collects items and customer details, then completing it creates an order.+---++## Overview++A cart is everything that happens before a purchase is final: adding items, entering an address, choosing delivery, and paying. Completing a cart creates an [Order](/v6/developer/core-concepts/orders) — a separate, permanent record.++The two are kept apart because they want opposite things. A cart changes constantly, tolerates half-finished states, and is often abandoned. An order is a financial record: it must not change quietly, and it has to keep saying what the customer actually agreed to pay.++```mermaid+erDiagram+ Cart ||--o{ LineItem : "has many"+ Cart ||--o{ Fulfillment : "has many"+ Cart ||--o| Order : "completes into"+ Cart }o--|| Customer : "belongs to"++ Cart {+ string token+ string email+ string currency+ string total+ datetime completed_at+ }++ Order {+ string number+ string payment_status+ string fulfillment_status+ string total+ }+```++## Cart attributes++| Attribute | Description |+|---|---|+| `id` | Cart ID, e.g. `cart_86Rf07xd4z` |+| `token` | Guest cart token — save it so a guest can return to their cart |+| `email` | Customer's email address |+| `currency` | Cart currency, e.g. `USD` |+| `total_quantity` | Total number of items |+| `requirements` | What the cart still needs before it can be completed |+| `item_total` / `display_item_total` | Sum of line item prices |+| `delivery_total` / `display_delivery_total` | Delivery cost |+| `tax_total` / `display_tax_total` | Total tax |+| `discount_total` / `display_discount_total` | Total discount |+| `total` / `display_total` | Cart total |+| `amount_due` / `display_amount_due` | Still to pay after store credit and gift cards |+| `warnings` | Items removed or changed since the customer last looked |+| `completed_at` | Set once checkout succeeded |++Every amount comes in two forms: `total` is the raw value (`"135.60"`) and [`display_total` is formatted for the currency](/api-reference/store-api/monetary-amounts) (`"$135.60"`). Render the `display_` one.++<Note>+Money is sent as a **string**, not a number. JavaScript numbers can't represent every decimal exactly — `0.1 + 0.2` gives `0.30000000000000004` — which is not something you want inside a price. Let Spree do the arithmetic and render the formatted strings.+</Note>++## Creating a cart and adding items++<CodeGroup>++```typescript Store SDK+// Create a cart+const cart = await client.carts.create()+// cart.token => "abc123" (save this for guest checkout)++// Add an item+await client.carts.items.create(cart.id, {+ variant_id: 'var_xxx',+ quantity: 2,+})++// Update quantity+await client.carts.items.update(cart.id, 'li_xxx', { quantity: 3 })++// Remove an item+await client.carts.items.delete(cart.id, 'li_xxx')+```++```bash cURL+# Create a cart+curl -X POST 'https://api.mystore.com/api/v3/store/carts' \+ -H 'X-Spree-API-Key: pk_xxx'++# Add an item+curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/items' \+ -H 'X-Spree-API-Key: pk_xxx' \+ -H 'X-Spree-Token: abc123' \+ -H 'Content-Type: application/json' \+ -d '{ "variant_id": "var_xxx", "quantity": 2 }'++# Update quantity+curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/items/li_xxx' \+ -H 'X-Spree-API-Key: pk_xxx' \+ -H 'X-Spree-Token: abc123' \+ -H 'Content-Type: application/json' \+ -d '{ "quantity": 3 }'+```++</CodeGroup>++Every change returns the whole cart with new totals, so you never need a second request to refresh the summary.++When a guest signs in, attach their cart to the account:++```typescript Store SDK+await client.carts.associate(cartId, { spreeToken: 'abc123' })+```++## Checkout requirements++A cart tells you what it still needs before it can be completed:++```json+{+ "requirements": [+ {+ "step": "address",+ "field": "email",+ "code": "email_required",+ "message": "Email address is required"+ }+ ]+}+```++An empty `requirements` array means the cart is ready.++This is what lets you design your own checkout. Spree tells you what's missing; you decide how and when to ask for it — one long page, a few steps, or whatever suits your storefront.++## Checkout++<Steps>+ <Step title="Add the customer's details">+ ```typescript Store SDK+ await client.carts.update(cartId, {+ email: '[email protected]',+ shipping_address: {+ first_name: 'John', last_name: 'Doe',+ address1: '123 Main St', city: 'Los Angeles',+ country_iso: 'US', state_abbr: 'CA', postal_code: '90001',+ },+ })+ ```+ </Step>+ <Step title="Choose delivery">+ Each [fulfillment](/v6/developer/core-concepts/fulfillments) offers delivery rates. Pick one per fulfillment.++ ```typescript Store SDK+ const cart = await client.carts.get(cartId)+ await client.carts.fulfillments.update(cartId, cart.fulfillments[0].id, {+ selected_delivery_rate_id: 'rate_xxx',+ })+ ```+ </Step>+ <Step title="Take payment">+ For providers like Stripe, create a payment session and confirm it with their own SDK.++ ```typescript Store SDK+ const session = await client.carts.paymentSessions.create(cartId, {+ payment_method_id: 'pm_xxx',+ })+ // session.external_data.client_secret => use with Stripe.js++ await client.carts.paymentSessions.complete(cartId, session.id)+ ```+ </Step>+ <Step title="Complete the cart">+ ```typescript Store SDK+ const order = await client.carts.complete(cartId)+ ```++ You get back an [Order](/v6/developer/core-concepts/orders).+ </Step>+</Steps>++Discount codes, gift cards and store credit can be applied any time before completion:++```typescript Store SDK+await client.carts.discountCodes.apply(cartId, 'SUMMER20')+await client.carts.giftCards.apply(cartId, 'GIFT-XXXX')+await client.carts.storeCredits.apply(cartId)+```++## What completion guarantees++Completing a cart moves real money, so Spree is careful about it:++**Double submission is safe.** A customer double-clicking "Place order" gets the same order back rather than a second charge. This holds even when your app runs on several servers.++**An interrupted completion recovers.** If something dies after the customer was charged, trying again finishes the job instead of charging twice.++**Totals are worked out at the last moment.** The amount charged is calculated when the cart is completed, not taken from an earlier request — so a price or promotion that changed while the customer was reviewing can't lead to the wrong charge.++If a cart can't be completed you get told why — a payment failure, or unmet [requirements](#checkout-requirements) — and the cart is left alone so the customer can fix it and try again.++## Abandoned carts++Carts emit `cart.created`, `cart.updated` and `cart.deleted` [events](/developer/core-concepts/events), which also reach [webhooks](/developer/core-concepts/webhooks) — enough to drive abandonment email without polling for changes.++Completed carts are kept rather than deleted, and an order records which cart it came from, so you can measure conversion. Abandoned carts are cleared out on a schedule you control; carts with a payment in progress are never removed.++## Related++- [Orders](/v6/developer/core-concepts/orders) — the record a cart becomes+- [Payments](/developer/core-concepts/payments) — payment methods and sessions+- [Fulfillments](/v6/developer/core-concepts/fulfillments) — delivery optionsdiff --git a/docs/v6/developer/core-concepts/fulfillments.mdx b/docs/v6/developer/core-concepts/fulfillments.mdxnew file mode 100644index 0000000000..4bbfd3a0dc--- /dev/null+++ b/docs/v6/developer/core-concepts/fulfillments.mdx@@ -0,0 +1,193 @@+---+title: Fulfillments+description: How Spree models getting items to the customer — fulfillments, delivery methods and zones, and delivery types covering shipping, digital and pickup.+---++## Overview++A fulfillment is one batch of items going to the customer by one method — a parcel from a warehouse, a digital download, or an order waiting at a pickup counter. An order gets one fulfillment per combination of stock location and delivery method, so an order sourced from two warehouses has two.++The word is deliberately broader than "shipment". A digital download has no carrier, no address and no package, and click-and-collect ships nowhere at all — a fulfillment covers all of them without dragging along fields that make no sense for most.++```mermaid+erDiagram+ Order ||--o{ Fulfillment : "has many"+ Fulfillment ||--o{ FulfillmentItem : "has many"+ Fulfillment ||--o{ DeliveryRate : "offers"+ Fulfillment }o--|| StockLocation : "sourced from"+ DeliveryRate }o--|| DeliveryMethod : "priced by"+ DeliveryMethod }o--o{ DeliveryZone : "serves"++ Fulfillment {+ string number+ string status+ string tracking+ string cost+ datetime fulfilled_at+ }+```++## Fulfillment attributes++| Attribute | Description |+|---|---|+| `id` | Fulfillment ID, e.g. `ful_86Rf07xd4z` |+| `number` | Fulfillment number, e.g. `F123456789` |+| `status` | See [statuses](#statuses) below |+| `tracking` | Carrier tracking number, once it's on its way |+| `cost` / `display_cost` | Delivery cost for this fulfillment |+| `delivery_rates` | The options the customer can choose from |+| `selected_delivery_rate_id` | The chosen option |+| `fulfilled_at` | When it went out |++## Statuses++| Value | Meaning |+|---|---|+| `pending` | Not ready yet — awaiting payment, or items are on backorder |+| `ready` | Everything in stock and paid for; the warehouse can pick it |+| `backorder` | Waiting on stock |+| `fulfilled` | It went out |+| `canceled` | It won't be sent |++One rule only ever moves one way: once something has gone out, it stays gone out. A later payment problem changes the order's [payment status](/v6/developer/core-concepts/orders#statuses) and leaves the fulfillment alone.++## Delivery types++Every delivery method has a type that decides how it behaves:++| Type | Behaviour |+|---|---|+| `shipping` | Physical delivery to an address. Someone marks it sent. |+| `digital` | Available the moment the order is placed. No address needed. |+| `pickup` | Collection from one of your own stock locations. |+| `pickup_point` | Collection from a third-party point — a locker or partner shop. |++This is what lets a store sell a downloadable album and a vinyl record in the same order without any special handling in your storefront: the download is ready immediately, the record gets a tracking number.++## Choosing delivery at checkout++Each fulfillment on a cart offers delivery rates. The customer picks one per fulfillment.++<CodeGroup>++```typescript Store SDK+const cart = await client.carts.get(cartId)++cart.fulfillments[0].delivery_rates+// => [{ id: 'rate_xxx', name: 'DHL Express', display_cost: '$12.00',+// estimated_delivery_date: '2026-08-07' }, ...]++await client.carts.fulfillments.update(cartId, cart.fulfillments[0].id, {+ selected_delivery_rate_id: 'rate_xxx',+})+```++```bash cURL+curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/fulfillments/ful_xxx' \+ -H 'X-Spree-API-Key: pk_xxx' \+ -H 'X-Spree-Token: abc123' \+ -H 'Content-Type: application/json' \+ -d '{ "selected_delivery_rate_id": "rate_xxx" }'+```++</CodeGroup>++Rates carry more than a price — carrier, service level and estimated delivery date — so you can show "DHL Express, arrives Tuesday" instead of just a number.++## Pickup++For pickup methods, ask the API where the customer can collect:++<CodeGroup>++```typescript Store SDK+// Your own pickup-enabled locations+const locations = await client.deliveryMethods.pickupLocations('dm_xxx')++// Third-party pickup points near the customer+const points = await client.deliveryMethods.pickupPoints('dm_xxx', {+ latitude: 34.0522,+ longitude: -118.2437,+})+```++```bash cURL+curl 'https://api.mystore.com/api/v3/store/delivery_methods/dm_xxx/pickup_locations' \+ -H 'X-Spree-API-Key: pk_xxx'+```++</CodeGroup>++## Managing fulfillments++<CodeGroup>++```typescript Admin SDK+// What's ready to pick+const fulfillments = await adminClient.orders.fulfillments.list('or_xxx')++// Add tracking, then mark it sent+await adminClient.orders.fulfillments.update('or_xxx', 'ful_xxx', {+ tracking: '1Z999AA10123456784',+})+await adminClient.orders.fulfillments.fulfill('or_xxx', 'ful_xxx')++// Split it when only part can go now+await adminClient.orders.fulfillments.split('or_xxx', 'ful_xxx', {+ items: [{ fulfillment_item_id: 'fi_xxx', quantity: 1 }],+})++// Cancel+await adminClient.orders.fulfillments.cancel('or_xxx', 'ful_xxx')+```++```bash cURL+curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/fulfillments/ful_xxx' \+ -H 'X-Spree-API-Key: sk_xxx' \+ -H 'Content-Type: application/json' \+ -d '{ "tracking": "1Z999AA10123456784" }'++curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/fulfillments/ful_xxx/fulfill' \+ -H 'X-Spree-API-Key: sk_xxx'+```++</CodeGroup>++## Delivery methods and zones++A **delivery method** is what the customer picks — "Standard", "Express", "Collect in store". A **delivery zone** decides where it's available.++Zones match on country and state, and also on postal code prefixes and ranges, so you can offer same-day delivery to a handful of city postcodes without listing every one:++```typescript Admin SDK+await adminClient.deliveryZones.create({+ name: 'London same-day',+ members: [+ { member_type: 'postal_code', country_iso: 'GB', postal_code_prefix: 'SW1' },+ { member_type: 'postal_code', country_iso: 'GB', postal_code_from: 'EC1A', postal_code_to: 'EC1V' },+ ],+})+```++A zone member is either a whole country, a state, or a postal code prefix or range.++<Note>+Delivery zones cover delivery only. Tax is handled separately — see [Taxes](/developer/core-concepts/taxes).+</Note>++### Pricing and rules++Delivery is priced either by a rule you configure in the dashboard — flat rate, per item, price bands — or by asking a carrier for live rates.++Methods can also carry conditions that decide when they're offered at all: free shipping over a certain order value, or heavy items excluded from letter post. These are applied in one place, so both kinds of pricing respect them.++## Events++Fulfillments publish [events](/developer/core-concepts/events) — `fulfillment.created`, `fulfillment.fulfilled`, `fulfillment.canceled` — which also reach [webhooks](/developer/core-concepts/webhooks). Use them to notify a customer, push to a warehouse system, or send tracking emails.++## Related++- [Orders](/v6/developer/core-concepts/orders) — how delivery status rolls up+- [Inventory](/developer/core-concepts/inventory) — stock locations and availability+- [Returns, Exchanges & Claims](/v6/developer/core-concepts/returns-exchanges-claims) — items coming backdiff --git a/docs/v6/developer/core-concepts/orders.mdx b/docs/v6/developer/core-concepts/orders.mdxnew file mode 100644index 0000000000..7c3f3155bd--- /dev/null+++ b/docs/v6/developer/core-concepts/orders.mdx@@ -0,0 +1,164 @@+---+title: Orders+description: How Spree models orders — a permanent record created by completing a cart, with separate payment and delivery statuses.+---++## Overview++An order is a placed purchase. It's created by completing a [Cart](/v6/developer/core-concepts/carts) and holds its own copy of everything the customer agreed to — items, prices, taxes, discounts and delivery.++```mermaid+erDiagram+ Order ||--o{ LineItem : "has many"+ Order ||--o{ Fulfillment : "has many"+ Order ||--o{ Payment : "has many"+ Order ||--o{ Return : "has many"+ Order }o--|| Cart : "created from"+ Order }o--|| Customer : "belongs to"++ Order {+ string number+ string payment_status+ string fulfillment_status+ string total+ datetime completed_at+ }+```++## Order attributes++| Attribute | Description |+|---|---|+| `id` | Order ID, e.g. `or_86Rf07xd4z` |+| `number` | Order number shown to customers, e.g. `R123456789` |+| `cart_id` | The cart this order came from |+| `email` | Customer's email address |+| `currency` | Order currency, e.g. `USD` |+| `total_quantity` | Total number of items |+| `payment_status` | See [statuses](#statuses) below |+| `fulfillment_status` | See [statuses](#statuses) below |+| `item_total` / `display_item_total` | Sum of line item prices |+| `delivery_total` / `display_delivery_total` | Delivery cost |+| `tax_total` / `display_tax_total` | Total tax |+| `discount_total` / `display_discount_total` | Total discount |+| `total` / `display_total` | Order total |+| `amount_due` / `display_amount_due` | Still outstanding |+| `completed_at` | When the order was placed |++Every amount comes in two forms: `total` is the raw value (`"135.60"`) and [`display_total` is formatted for the currency](/api-reference/store-api/monetary-amounts) (`"$135.60"`). Render the `display_` one.++## Statuses++An order tracks payment and delivery separately, because they genuinely move at different speeds. An order can be paid but not yet sent, or sent and later partly refunded.++**`payment_status`**++| Value | Meaning |+|---|---|+| `none` | Nothing paid or authorized yet |+| `authorized` | Money is held but not taken |+| `partially_paid` | Some of the total has been taken |+| `paid` | Fully paid |+| `partially_refunded` | Some money returned |+| `refunded` | Everything returned |+| `overcharged` | More was taken than the order total |+| `voided` | The hold was released without taking money |++**`fulfillment_status`**++| Value | Meaning |+|---|---|+| `pending` | Not ready to send yet |+| `ready` | Everything in stock and paid for |+| `backorder` | Waiting on stock |+| `partial` | Some of it has gone out |+| `fulfilled` | Everything has gone out |+| `canceled` | Nothing will be sent |++Both are worked out automatically from the order's payments, refunds and fulfillments. You change an order's status by acting on those — taking a payment, sending a parcel, issuing a refund — never by setting the status yourself.++## Reading an order++A customer can fetch their own order; guests use the order token they got at checkout.++<CodeGroup>++```typescript Store SDK+// A single order+const order = await client.orders.get('or_xxx')++// The signed-in customer's order history+const orders = await client.customers.orders.list({ per_page: 20 })+```++```bash cURL+curl 'https://api.mystore.com/api/v3/store/orders/or_xxx' \+ -H 'X-Spree-API-Key: pk_xxx' \+ -H 'X-Spree-Token: order_token_xxx'+```++</CodeGroup>++## Managing orders++Back-office work happens through the Admin API.++<CodeGroup>++```typescript Admin SDK+// Find orders needing attention+const orders = await adminClient.orders.list({+ filter: { payment_status_eq: 'paid', fulfillment_status_eq: 'ready' },+})++// Cancel an order+await adminClient.orders.cancel('or_xxx', {+ reason: 'customer',+ restock_items: true,+ refund_payments: true,+})++// Take an authorized payment+await adminClient.orders.payments.capture('or_xxx', 'pay_xxx')++// Refund against a specific payment+await adminClient.orders.refunds.create('or_xxx', {+ payment_id: 'pay_xxx',+ amount: '25.00',+})+```++```bash cURL+curl 'https://api.mystore.com/api/v3/admin/orders?filter[payment_status_eq]=paid' \+ -H 'X-Spree-API-Key: sk_xxx'++curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/cancel' \+ -H 'X-Spree-API-Key: sk_xxx' \+ -H 'Content-Type: application/json' \+ -d '{ "reason": "customer", "restock_items": true }'+```++</CodeGroup>++Canceling records who canceled and why, puts stock back, and settles any payments.++## Orders don't change quietly++A placed order is meant to stay put. Its items and prices are written when the cart is completed and then left alone, so an order keeps saying what the customer actually agreed to — even if a product's price changes the next day.++Where admin edits are allowed, totals are re-added from the order's existing rows rather than worked out again from scratch. Editing an order must never quietly re-apply today's promotions and hand the customer a different discount than the one they accepted.++## Money on an order++Tax, discounts and fees are kept as separate records, so you can ask what tax was charged without picking through a mixed list. See [Taxes, Discounts & Fees](/v6/developer/core-concepts/taxes-discounts-fees).++## Events++Orders publish [events](/developer/core-concepts/events) — `order.placed`, `order.canceled`, `order.paid` and more — which also reach [webhooks](/developer/core-concepts/webhooks). This is the right way to push orders to another system, trigger fulfillment, or start an email flow.++## Related++- [Carts](/v6/developer/core-concepts/carts) — shopping and checkout+- [Fulfillments](/v6/developer/core-concepts/fulfillments) — getting items to the customer+- [Returns, Exchanges & Claims](/v6/developer/core-concepts/returns-exchanges-claims) — after the sale+- [Payments](/developer/core-concepts/payments) — payment methods and processingdiff --git a/docs/v6/developer/core-concepts/returns-exchanges-claims.mdx b/docs/v6/developer/core-concepts/returns-exchanges-claims.mdxnew file mode 100644index 0000000000..c91432721d--- /dev/null+++ b/docs/v6/developer/core-concepts/returns-exchanges-claims.mdx@@ -0,0 +1,177 @@+---+title: Returns, Exchanges & Claims+description: How Spree models what happens after a customer receives an order — three separate records for money back, different items, and something gone wrong.+---++## Overview++Three things can happen after a customer receives an order, and Spree models each on its own:++| Record | What happened | Outcome |+|---|---|---|+| **Return** | Customer sends items back | Money back |+| **Exchange** | Customer sends items back | Different items |+| **Claim** | Item arrived damaged, wrong, or never arrived | Refund, replacement, or both — usually without asking for the goods back |++Keeping them separate matters most for claims. Without a record for "it arrived smashed", merchants end up either creating a manual order or opening a return they immediately mark received — which records the wrong thing and makes damage reporting impossible.++```mermaid+erDiagram+ Order ||--o{ Return : "has many"+ Order ||--o{ Exchange : "has many"+ Order ||--o{ Claim : "has many"+ Return ||--o{ ReturnLineItem : "has many"+ Return }o--|| StockLocation : "received at"++ Return {+ string number+ string status+ datetime received_at+ }+ Claim {+ string number+ string status+ string claim_type+ }+```++## Statuses++| Record | Statuses |+|---|---|+| **Return** | `requested` → `approved` → `received` → `refunded`, or `canceled` |+| **Exchange** | `requested` → `approved` → `received` → `fulfilled`, or `canceled` |+| **Claim** | `open` → `approved` → `resolved`, or `denied` / `canceled` |++Each step is its own API call, because each one needs information the last one didn't have — what actually turned up, how much to refund, what to send instead.++## Customer self-service++Customers can open a return or a claim on their own order and follow its progress. Approving, receiving and refunding stay with the merchant.++<CodeGroup>++```typescript Store SDK+// Request a return — items refer to units that shipped, not cart line items+const returnRequest = await client.orders.returns.create('or_xxx', {+ items: [{ fulfillment_item_id: 'fi_xxx', quantity: 1 }],+ reason_id: 'rsn_xxx',+ memo: 'Too small',+})++// Report a problem+const claim = await client.orders.claims.create('or_xxx', {+ items: [{ line_item_id: 'li_xxx', quantity: 1, description: 'Arrived cracked' }],+ claim_type: 'damaged',+})++// Follow progress+const returns = await client.orders.returns.list('or_xxx')+```++```bash cURL+curl -X POST 'https://api.mystore.com/api/v3/store/orders/or_xxx/returns' \+ -H 'X-Spree-API-Key: pk_xxx' \+ -H 'X-Spree-Token: order_token_xxx' \+ -H 'Content-Type: application/json' \+ -d '{ "items": [{ "fulfillment_item_id": "fi_xxx", "quantity": 1 }],+ "memo": "Too small" }'+```++</CodeGroup>++Claim types are `damaged`, `missing`, `wrong_item` and `other` out of the box, and a store can add its own.++## Processing a return++<CodeGroup>++```typescript Admin SDK+// Approve+await adminClient.orders.returns.approve('or_xxx', 'ret_xxx')++// Record what actually arrived+await adminClient.orders.returns.receive('or_xxx', 'ret_xxx', {+ items: [+ { return_line_item_id: 'rli_1', quantity: 2, resellable: true },+ { return_line_item_id: 'rli_2', quantity: 1, resellable: false },+ ],+})++// Refund+await adminClient.orders.returns.refund('or_xxx', 'ret_xxx', {+ amount: '24.99',+ refund_method: 'original_payment',+})+```++```bash cURL+curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/returns/ret_xxx/receive' \+ -H 'X-Spree-API-Key: sk_xxx' \+ -H 'Content-Type: application/json' \+ -d '{ "items": [{ "return_line_item_id": "rli_1", "quantity": 2, "resellable": true }] }'+```++</CodeGroup>++Receiving takes the quantities the warehouse actually counted, because partial and damaged returns are normal rather than exceptional. A customer says three items are coming; two arrive; one of those can't be sold again. Only resellable goods go back into stock.++Leave `items` out to receive everything as requested. Refunds default to whatever the return is still owed, and can go back to the original payment method or to store credit.++## Resolving a claim++What to do about a claim is decided when you resolve it, not when the customer opens it — merchants usually decide once they've seen the photos.++```typescript Admin SDK+await adminClient.orders.claims.approve('or_xxx', 'clm_xxx')++await adminClient.orders.claims.resolve('or_xxx', 'clm_xxx', {+ resolution: 'refund_and_replacement', // or 'refund', 'replacement'+ refund_method: 'store_credit',+ replacement_line_item_ids: ['li_xxx'],+})+```++A replacement creates a new [fulfillment](/v6/developer/core-concepts/fulfillments) on the original order, so the customer doesn't have to place a second one.++## Exchanges++An exchange works like a return, but ends by sending different items instead of refunding:++```typescript Admin SDK+await adminClient.orders.exchanges.approve('or_xxx', 'exch_xxx')+await adminClient.orders.exchanges.receive('or_xxx', 'exch_xxx')+await adminClient.orders.exchanges.fulfill('or_xxx', 'exch_xxx')+```++## Reporting++Because each one is its own record, you can query them directly:++```typescript Admin SDK+// Everything awaiting action+const pending = await adminClient.returns.list({ filter: { status_eq: 'approved' } })++// Damage rate this month+const claims = await adminClient.claims.list({+ filter: { claim_type_eq: 'damaged', created_at_gt: '2026-08-01' },+})+```++## Return policy++Spree ships no built-in return window. Whether a customer may open a return is store policy, and it's checked when the return is created — so you can hold customers to a 30-day window while letting staff make an exception for a good customer, and vary the rule by market where local law requires it.++Set the return window per market, or express a more specific rule in your own application. See [Configuration](/v6/developer/customization/configuration) and [Services & Workflows](/developer/customization/workflows).++## Events++Each step publishes an [event](/developer/core-concepts/events) — `return.received`, `return.refunded`, `exchange.fulfilled`, `claim.resolved` — which also reach [webhooks](/developer/core-concepts/webhooks).++Returns and claims also update the order's [payment status](/v6/developer/core-concepts/orders#statuses), so a refunded order reflects it without any manual bookkeeping.++## Related++- [Orders](/v6/developer/core-concepts/orders) — payment status after refunds+- [Fulfillments](/v6/developer/core-concepts/fulfillments) — replacement deliveries+- [Inventory](/developer/core-concepts/inventory) — putting returned goods back in stockdiff --git a/docs/v6/developer/core-concepts/taxes-discounts-fees.mdx b/docs/v6/developer/core-concepts/taxes-discounts-fees.mdxnew file mode 100644index 0000000000..2453f8fa94--- /dev/null+++ b/docs/v6/developer/core-concepts/taxes-discounts-fees.mdx@@ -0,0 +1,199 @@+---+title: Taxes, Discounts & Fees+description: How Spree records money added to or taken off an order — separate tax lines, discounts and fees, and the order totals you render in a storefront.+---++## Overview++An order total is rarely just the sum of item prices. Tax gets added, a promo code takes something off, gift wrapping costs extra. Spree records each of those as its own row, of one of three kinds:++| Kind | Effect | What it is |+|---|---|---|+| **Tax line** | adds | Tax charged on an item, on delivery, or on a fee |+| **Discount** | subtracts | A promotion or a manual reduction |+| **Fee** | adds | A surcharge — handling, gift wrap, cash on delivery |++Keeping them apart means a direct question gets a direct answer. "What tax did we charge on this order?" is one request against tax lines, rather than filtering a mixed list and hoping you caught every case.++```mermaid+erDiagram+ Order ||--o{ TaxLine : "has many"+ Order ||--o{ Discount : "has many"+ Order ||--o{ Fee : "has many"+ LineItem ||--o{ TaxLine : "taxed by"+ LineItem ||--o{ Discount : "reduced by"+ Fulfillment ||--o{ TaxLine : "taxed by"+ Fee ||--o{ TaxLine : "taxed by"++ TaxLine {+ string label+ string rate+ boolean included+ string amount+ }+ Discount {+ string label+ string kind+ string code+ string amount+ }+ Fee {+ string label+ string kind+ string amount+ }+```++<Note>+Money is sent as a **string** — `"15.99"`, not `15.99`. JavaScript numbers can't represent every decimal exactly, and `0.1 + 0.2` gives `0.30000000000000004`, which is not something you want inside a total. If you need to do arithmetic, use a decimal library or work in whole cents.+</Note>++## Building an order summary++Most storefronts never need the individual rows. The order already carries a total for each kind, so you can render a summary directly:++```typescript+const order = await client.orders.get('or_xxx')++order.display_item_total // "$120.00" items before tax and discounts+order.display_discount_total // "-$12.00" everything taken off+order.display_delivery_total // "$5.00" delivery+order.display_tax_total // "$22.60" all tax+order.display_total // "$135.60" what the customer pays+```++Every total comes in two forms: `total` is the raw value (`"135.60"`) and `display_total` is formatted for the order's currency (`"$135.60"`). Render the `display_` one — it handles the symbol, decimal separator and where the symbol goes.++| Attribute | What it sums |+|---|---|+| `item_total` | Line item prices before tax and discounts |+| `discount_total` | All discounts |+| `tax_total` | All tax |+| `included_tax_total` | Tax already inside displayed prices |+| `additional_tax_total` | Tax added on top |+| `delivery_total` | Delivery charges |+| `total` | What the customer pays |++<Warning>+If you add up a subtotal yourself, include `additional_tax_total` only. `included_tax_total` is **already inside** the item prices — adding it again counts the tax twice. This is the most common mistake when building a European storefront.+</Warning>++## Tax lines++A tax line records one tax charge and what it was charged on.++| Attribute | Description |+|---|---|+| `label` | What the customer sees, e.g. `VAT 20%` |+| `rate` | The rate applied, e.g. `"0.2"` |+| `included` | Whether the tax was already inside the displayed price |+| `amount` / `display_amount` | Tax charged |+| `line_item_id` / `fulfillment_id` / `fee_id` | What was taxed — exactly one is set |+| `tax_rate_id` | The configured rate, when tax came from Spree rather than an outside service |++`included` is the field that trips people up. In most of Europe a €120 price already contains €20 of VAT, so the tax line is there for information — the customer pays €120, not €140. In the US, tax is added at checkout, so the same field is `false` and the amount really is extra.++```typescript Admin SDK+const taxLines = await adminClient.orders.taxLines.list('or_xxx')+```++You never create tax lines yourself. They're written whenever the order total is worked out — see [Taxes](/developer/core-concepts/taxes).++## Discounts++| Attribute | Description |+|---|---|+| `label` | What the customer sees, e.g. `Summer Sale` |+| `kind` | `promotion` or `manual` |+| `code` | The coupon code used, if any |+| `value` / `value_type` | The rule behind it, e.g. `"10"` / `percent`. Accepts a string or a number on write. |+| `amount` / `display_amount` | The reduction, as a negative amount |+| `promotion_id` | The promotion it came from |+| `line_item_id` / `fulfillment_id` | What it reduced |++Most discounts come from [Promotions](/developer/core-concepts/promotions) — a customer applies a code and the rows appear. A **manual** discount is one an admin adds directly, for a goodwill gesture or a price match:++<CodeGroup>++```typescript Admin SDK+// 10% off a single line item+await adminClient.orders.discounts.create('or_xxx', {+ label: 'Goodwill discount',+ value: '10',+ value_type: 'percent',+ line_item_id: 'li_xxx',+})++// A flat amount across the order+await adminClient.orders.discounts.create('or_xxx', {+ label: 'Price match',+ value: '15.00',+ value_type: 'flat',+})+```++```bash cURL+curl -X POST 'https://api.mystore.com/api/v3/admin/orders/or_xxx/discounts' \+ -H 'X-Spree-API-Key: sk_xxx' \+ -H 'Content-Type: application/json' \+ -d '{ "label": "Goodwill discount", "value": 10, "value_type": "percent" }'+```++</CodeGroup>++Only manual discounts can be edited or deleted. Changing one that came from a promotion returns a `422` — those belong to the promotion that created them, and letting an order disagree with its own promotion is how reporting stops adding up.++A discount on the whole order is shared out across the items rather than kept as one lump sum. So if the customer later returns one item, Spree knows how much of the discount belonged to it.++## Fees++| Attribute | Description |+|---|---|+| `label` | What the customer sees, e.g. `Gift wrapping` |+| `kind` | `surcharge`, `handling`, `gift_wrap`, `cod`, `payment`, or your own |+| `amount` / `display_amount` | The charge |+| `line_item_id` / `fulfillment_id` | What it applies to — both empty means the whole order |++```typescript Admin SDK+await adminClient.orders.fees.create('or_xxx', {+ label: 'Gift wrapping',+ kind: 'gift_wrap',+ amount: '5.00',+ line_item_id: 'li_xxx',+})+```++Fees are always positive, and they're taxable — a fee can have its own tax lines. To take money off, create a discount instead. That way a refund never has to work out whether a negative fee was a charge or a credit.++## Where rows attach++Each row points at exactly the thing it applies to:++- **Tax lines** → a line item, a [fulfillment](/v6/developer/core-concepts/fulfillments), or a fee, so item tax and delivery tax stay separately visible+- **Discounts** → a line item or a fulfillment+- **Fees** → a line item, a fulfillment, or the order itself++Rows also keep a copy of where they came from — the rate and label on a tax line, the code and promotion on a discount. If someone deletes that promotion next month, the order still says what the customer was actually given.++## When totals change++Totals are worked out again whenever something changes on a cart — an item added, an address entered, a code applied. The response to every cart change already includes the new totals, so a follow-up request is never needed:++```typescript+// The returned cart already has updated totals+const cart = await client.carts.items.create(cartId, {+ variant_id: 'var_xxx',+ quantity: 2,+})++cart.display_total // already correct+```++Once an order is placed, the rows stop being regenerated. Editing a placed order re-adds its existing rows rather than starting from scratch, so today's promotions can't quietly rewrite what a customer agreed to last week.++## Related++- [Taxes](/developer/core-concepts/taxes) — how tax is worked out+- [Promotions](/developer/core-concepts/promotions) — where most discounts come from+- [Fulfillments](/v6/developer/core-concepts/fulfillments) — delivery charges+- [Orders](/v6/developer/core-concepts/orders) — order totals and statusesdiff --git a/docs/v6/developer/customization/configuration.mdx b/docs/v6/developer/customization/configuration.mdxnew file mode 100644index 0000000000..87fc0b0128--- /dev/null+++ b/docs/v6/developer/customization/configuration.mdx@@ -0,0 +1,180 @@+---+title: Configuration+description: Every global Spree setting that is actually read by Spree 6 — grouped by area, with defaults and what each one changes.+---++Global settings live in `config/initializers/spree.rb` and apply to the whole application. Anything that varies per store — currency, markets, delivery zones, languages — is data you change in the dashboard instead.++```ruby config/initializers/spree.rb+Spree.config do |config|+ config.minimum_password_length = 10+ config.track_inventory_levels = false+end+```++<Note>+Restart your Rails server after editing the initializer.+</Note>++This page lists only settings Spree 6 actually reads. Settings that exist for backwards compatibility are listed under [Deprecated settings](#deprecated-settings) rather than mixed in with the rest.++## Checkout and payments++| Setting | Default | What it does |+|---|---|---|+| `auto_capture` | `true` | Store-wide default for whether cards are charged immediately at checkout, or only authorized and captured later. Individual payment methods override it. |+| `auto_capture_on_dispatch` | `false` | Delays charging until goods actually go out. A parcel becomes ready to send once payment is authorized, and money is taken on dispatch. |+| `allow_checkout_on_gateway_error` | `false` | Lets a customer finish checkout even when the payment gateway returns an error. |+| `always_include_confirm_step` | `false` | Always shows a confirmation step, even when the payment method doesn't need one. |+| `tax_using_ship_address` | `true` | Calculates tax from the shipping address rather than the billing address. |+| `credit_to_new_allocation` | `false` | Records refunded store credit as a new entry each time instead of topping the original credit back up. |+| `non_expiring_credit_types` | `[]` | Store credit category names whose balances never expire. Gift cards never expire regardless. |++## Carts and stock reservations++| Setting | Default | What it does |+|---|---|---|+| `stock_reservations_enabled` | `true` | Holds stock for shoppers while they check out, so the same item can't be sold twice. |+| `default_stock_reservation_ttl_minutes` | `10` | How long a stock hold lasts, for stores that haven't set their own value. |+| `guest_cart_expiry_days` | `30` | How long an abandoned guest cart is kept before deletion. |+| `customer_cart_expiry_days` | `90` | How long a signed-in customer's abandoned cart is kept. |+| `empty_cart_expiry_hours` | `48` | How long a cart with no items is kept. |++## Inventory++| Setting | Default | What it does |+|---|---|---|+| `track_inventory_levels` | `true` | Global switch for stock tracking. Turn it off and the store stops counting on-hand quantities and treats everything as always available. |++## Products and pricing++| Setting | Default | What it does |+|---|---|---|+| `show_products_without_price` | `false` | Whether products with no price in the shopper's currency still appear in listings and search. |+| `allow_empty_price_amount` | `false` | Allows a price to be left blank instead of requiring an amount. Prices in a price list already allow blank. |+| `disable_sku_validation` | `false` | Set to `true` to let more than one variant share the same SKU. |+| `track_price_history` | `true` | Records price changes so the store can show the lowest price of the last 30 days, as the EU Omnibus Directive requires. Turn off for non-EU stores. |+| `price_history_retention_days` | `30` | How many days of price history the `spree:price_history:prune` task keeps. |+| `always_use_translations` | `false` | Always read product, category and collection names from the translation tables, even in the store's own default language. |++## Addresses++| Setting | Default | What it does |+|---|---|---|+| `address_requires_phone` | `false` | Makes a phone number mandatory on customer addresses. |+| `geocode_addresses` | `true` | Looks up latitude and longitude for saved addresses. |++## Media++| Setting | Default | What it does |+|---|---|---|+| `max_image_download_size` | `20971520` | Largest file size, in bytes, accepted when downloading an image from an external URL. |+| `images_save_from_url_job_attempts` | `5` | How many times to retry fetching an external image before giving up. |++## Promotions and gift cards++| Setting | Default | What it does |+|---|---|---|+| `coupon_codes_web_limit` | `500` | How many coupon codes are created immediately when saving a promotion. Larger batches move to a background job so saving stays fast. |+| `coupon_codes_total_limit` | `5000` | Maximum coupon codes a single promotion may generate. |+| `gift_card_batch_web_limit` | `500` | How many gift card codes a batch creates immediately before switching to a background job. |+| `gift_card_batch_limit` | `50000` | Maximum gift card codes in a single batch. |++## Accounts and passwords++| Setting | Default | What it does |+|---|---|---|+| `minimum_password_length` | `8` | Shortest password a customer or staff member may set. |+| `maximum_password_length` | `72` | Longest password allowed. |+| `max_failed_login_attempts` | `5` | Failed sign-ins before an account is temporarily locked. |+| `lockout_duration` | `1800` | How long an account stays locked, in seconds. |+| `customer_password_reset_expires_in` | `15` | How long a customer's password reset link stays valid, in minutes. |+| `admin_password_reset_expires_in` | `15` | How long a staff password reset link stays valid, in minutes. |++## URLs++| Setting | Default | What it does |+|---|---|---|+| `dashboard_url` | `nil` | Where the React dashboard lives, so single sign-on can send staff back to it after they authenticate. |+| `admin_url` | `nil` | Base address used to build staff invitation links in email. Invitation links are relative when this is unset. |++## Imports and events++| Setting | Default | What it does |+|---|---|---|+| `large_import_threshold` | `500` | Row count above which a CSV import switches to bulk processing — faster, with less live progress detail. |+| `events_log_enabled` | `true` | Writes every Spree event to the Rails log. |+| `disable_migration_check` | `false` | Silences the boot warning about pending engine migrations. |++## API settings++API settings live on their own configuration object:++```ruby config/initializers/spree.rb+Spree::Api::Config.jwt_expiration = 1800+```++### Authentication++| Setting | Default | What it does |+|---|---|---|+| `jwt_expiration` | `3600` | How long a customer or store access token stays valid, in seconds. |+| `admin_jwt_expiration` | `300` | How long a staff access token stays valid. Deliberately short — admin tokens carry far more privilege. |+| `refresh_token_expiry` | `2592000` | How long a refresh token stays valid, in seconds (30 days). |+| `jwt_secret_key` | `nil` | Signing key for tokens. Falls back to the Rails secret key base. |++### Rate limits++| Setting | Default | What it does |+|---|---|---|+| `rate_limit_window` | `60` | Length of the rate-limit window, in seconds. |+| `rate_limit_per_key` | `300` | Requests allowed per publishable API key per window. |+| `rate_limit_login` | `5` | Sign-in attempts allowed per IP per window. |+| `rate_limit_register` | `3` | Registration attempts per IP. |+| `rate_limit_refresh` | `10` | Token refresh attempts per IP. |+| `rate_limit_password_reset` | `3` | Password reset requests per IP. |+| `max_request_body_size` | `102400` | Largest accepted request body, in bytes (100 KB). |++### Webhooks++| Setting | Default | What it does |+|---|---|---|+| `webhooks_enabled` | `true` | Whether webhooks fire at all. |+| `webhooks_verify_ssl` | `true` | Verifies SSL certificates on webhook endpoints. Off in development. |++## Reading a setting++```ruby+Spree::Config.track_inventory_levels # => true+Spree::Api::Config.jwt_expiration # => 3600+```++Assigning at runtime affects only the current process and is lost on restart. Set values in the initializer to make them stick.++## Deprecated settings++These still exist so upgrades don't break, but Spree 6 either ignores them or reads them only from subsystems it has replaced. Don't use them in new code.++| Setting | Use instead |+|---|---|+| `return_eligibility_number_of_days` | The `return_window_days` preference on [Market](/developer/core-concepts/markets), or a `returns.create.validate` [hook](/developer/customization/workflows) |+| `restock_inventory` | Restocking is decided per return line item by its resellable flag — see [Returns](/v6/developer/core-concepts/returns-exchanges-claims#processing-a-return) |+| `expedited_exchanges` | [Exchanges](/v6/developer/core-concepts/returns-exchanges-claims) |+| `expedited_exchanges_days_window` | [Exchanges](/v6/developer/core-concepts/returns-exchanges-claims) |+| `enable_legacy_default_price` | Compatibility switch for the old default-price behavior; leave off |+| `use_user_locale` | Locale comes from the `x-spree-locale` header or the `locale` parameter |+| `allow_guest_checkout` | The `guest_checkout` setting on the store or channel |+| `company` | The `company_field_enabled` setting on the store |+| `address_requires_state` | State requirements come from the country |+| `checkout_zone` | [Delivery zones](/v6/developer/core-concepts/fulfillments#delivery-methods-and-zones) |+| `currency` | Store and market currencies |+| `disable_store_presence_validation` | Every store-owned record now requires a store |++<Warning>+These settings have no effect at all in Spree 6, and are scheduled for removal: `products_per_page`, `alternative_shipping_phone`, `show_variant_full_price`, `reserve_stock_on`, `storefront_products_path`, `storefront_taxons_path`, `storefront_pages_path`. Setting them changes nothing.+</Warning>++## Related++- [Model preferences](/developer/customization/model-preferences) — per-record settings+- [Services & Workflows](/developer/customization/workflows) — changing behavior rather than settingsdiff --git a/docs/v6/developer/customization/dependencies.mdx b/docs/v6/developer/customization/dependencies.mdxnew file mode 100644index 0000000000..39bf7f4d66--- /dev/null+++ b/docs/v6/developer/customization/dependencies.mdx@@ -0,0 +1,290 @@+---+title: Dependencies+section: customization+---++## Overview++With Dependencies, you can replace parts of Spree core with your custom code:+[Services and Workflows](/developer/customization/workflows), CanCanCan+Abilities (used for [Permissions](/developer/customization/permissions)), and API Serializers (used for+generating JSON API responses).++<Tip>+Replacing a whole class means keeping your copy in sync with every Spree+release. If you only need to run code inside an existing flow — validating,+reacting, or contributing data to a calculation — use a+[hook](/developer/customization/workflows#extending-a-workflow-with-hooks)+instead. Hooks survive upgrades.+</Tip>++## Application (global) customization++This will change every aspect of the application (both APIs, Admin Panel, and Storefront).++In your `config/initializers/spree.rb` file, you can set the following:++```ruby+Spree.cart_update_service = MyStore::CartUpdate+```++or using the block syntax:++```ruby+Spree.dependencies do |dependencies|+ dependencies.cart_update_service = MyStore::CartUpdate+end+```++Now let's create your custom service.++```bash+mkdir -p app/services/my_store && touch app/services/my_store/cart_update.rb+```++And add the following code to it:++```ruby+module MyStore+ class CartUpdate < Spree::Carts::Update+ def call(cart:, params:)+ result = super++ MyStore::ErpSync.push(result.value) if result.success?++ result+ end+ end+end+```++Inheriting and calling `super` keeps Spree's behaviour and adds yours around it,+which is usually what you want — a full rewrite means re-implementing logic that+changes between releases.++### Replacing a workflow++Workflow-backed seams end in `_workflow` (`cart_add_item_workflow`,+`carts_complete_workflow`, `payment_capture_workflow`, …). A replacement+subclasses the workflow and overrides `perform`:++```ruby+module MyStore+ class AddItem < Spree::Carts::AddItem+ def perform(variant:, cart: nil, **rest)+ super++ # your logic, then the standard result+ end+ end+end++Spree.cart_add_item_workflow = MyStore::AddItem+```++<Note>+Before writing this, check whether a+[hook](/developer/customization/workflows#available-hooks) covers your case —+`carts.add_item.validate` and `carts.add_item.after_item_added` handle most+reasons people replace this class, and they don't need maintaining across+upgrades.+</Note>++## Using dependencies in your code++When you need to use a dependency in your code, you can access it directly via the `Spree` module:++```ruby+# Returns the resolved class (not a string)+Spree.cart_add_item_workflow.call(cart: cart, variant: variant, quantity: 1)++# For API dependencies, use the Spree.api accessor+Spree.api.storefront_cart_serializer.new(order).serializable_hash+```++## Controller level customization++If you need to replace [serializers](https://github.com/jsonapi-serializer/jsonapi-serializer) or Services in a specific API endpoint you can create a [code decorator](/developer/customization/decorators):++```bash+mkdir -p app/controllers/spree && touch app/controllers/spree/cart_controller_decorator.rb+```++and add the following code to it:++```ruby+module Spree+ module CartControllerDecorator+ def resource_serializer+ MyNewAwesomeCartSerializer+ end++ def add_item_service+ MyNewAwesomeAddItemToCart+ end+ end++ CartController.prepend(CartControllerDecorator)+end+```++This will change the serializer in this API endpoint to `MyNewAwesomeCartSerializer` and also it will swap the default `add_item_service` to `MyNewAwesomeAddItemToCart`.++Different API endpoints can have different dependency injection points. You can review their [source code](https://github.com/spree/spree/tree/main/api/app/controllers/spree/api/v3) to see what you can replace.++## API level customization++Storefront API and Platform API have separate Dependencies injection points so you can easily customize one without touching the other.++In your Spree initializer (`config/initializers/spree.rb`) please add:++```ruby+Spree.api.storefront_cart_serializer = MyNewAwesomeCartSerializer+Spree.api.storefront_cart_add_item_service = MyNewAwesomeAddItemToCart+```++This will swap the default Cart serializer and Add Item to Cart service for your custom ones within all Storefront API endpoints that use those classes.++You can mix and match both global and API-level customizations:++```ruby+Spree.cart_add_item_workflow = MyNewAwesomeAddItemToCart+Spree.api.storefront_cart_add_item_service = AnotherAddItemToCart+```++The second line will have precedence over the first one, and the Storefront API will use `AnotherAddItemToCart` and the rest of the application will use `MyNewAwesomeAddItemToCart`.++## Debugging dependencies++Spree provides rake tasks to help you debug and inspect dependencies:++### List all dependencies++```bash+bin/rake spree:dependencies:list+```++This will output all dependencies with their current values:++```+[CORE]+cart_add_item_workflow Spree::Carts::AddItem+carts_create_service Spree::Carts::Create+cart_recalculate_workflow Spree::Carts::Recalculate [OVERRIDDEN]+...++[API]+storefront_cart_serializer Spree::V2::Storefront::CartSerializer+storefront_cart_add_item_service MyApp::CartAddItem [OVERRIDDEN]+...+```++You can use `grep` to filter results:++```bash+bin/rake spree:dependencies:list | grep cart+```++### Show only overridden dependencies++```bash+bin/rake spree:dependencies:overrides+```++This shows only the dependencies that have been customized, along with their original and current values:++```+[Core OVERRIDES]+cart_recalculate_workflow Spree::Carts::Recalculate -> MyApp::CartRecalculate (config/initializers/spree.rb:15)++[API OVERRIDES]+storefront_cart_add_item_service Spree::Carts::AddItem -> MyApp::CartAddItem (config/initializers/spree.rb:20)+```++### Validate all dependencies++```bash+bin/rake spree:dependencies:validate+```++This validates that all dependencies can be resolved to valid classes. If any dependency points to a non-existent class, it will report an error:++```+..........F.........+1 invalid dependencies:+ [Core] cart_add_item_workflow: uninitialized constant NonExistentClass+```++## Programmatic introspection++You can also inspect dependencies programmatically:++```ruby+# Check all current values+Spree::Dependencies.current_values+# => [{name: :cart_add_item_workflow, current: MyApp::CartAddItem, default: 'Spree::Carts::AddItem', overridden: true}, ...]++# Check if a specific dependency is overridden+Spree::Dependencies.overridden?(:cart_add_item_workflow)+# => true++# Get override information (where it was set)+Spree::Dependencies.override_info(:cart_add_item_workflow)+# => {value: MyApp::CartAddItem, source: "config/initializers/spree.rb:15", set_at: 2024-01-15 10:30:00}++# Validate all dependencies resolve to valid classes+Spree::Dependencies.validate!+# => true (or raises Spree::DependencyError)+```++## Renamed seams in Spree 6.0++Seams backed by a [workflow](/developer/customization/workflows) were renamed+from `*_service` to `*_workflow` in 6.0:++| Legacy name | Current name |+|---|---|+| `cart_add_item_service` | `cart_add_item_workflow` |+| `cart_recalculate_service` | `cart_recalculate_workflow` |+| `carts_complete_service` | `carts_complete_workflow` |+| `cart_merge_strategy` | `cart_merge_workflow` |+| `order_cancel_service` | `order_cancel_workflow` |+| `order_complete_service` | `order_complete_workflow` |+| `fulfillment_create_service` | `fulfillment_create_workflow` |+| `payments_handle_webhook_service` | `payments_handle_webhook_workflow` |++<Warning>+The legacy names stay readable for one release, but **assigning to one no longer+has any effect** — the override is recorded and a deprecation warning names the+seam to port to. A class written against the old service contract isn't+interchangeable with the workflow the new call sites use, so applying it+silently would break checkout in ways that are hard to trace.++If you override any of these, move to the `*_workflow` name and make sure your+class subclasses the workflow. The legacy names are removed in Spree 6.1.+</Warning>++## Backwards compatibility++The legacy string-based syntax is still supported for backwards compatibility:++```ruby+# Legacy syntax (still works)+Spree::Dependencies.carts_create_service = 'MyStore::CartCreate'+result = Spree::Dependencies.carts_create_service.constantize++# New syntax (recommended)+Spree.carts_create_service = MyStore::CartCreate+result = Spree.carts_create_service+```++Both syntaxes can coexist, but the new syntax is recommended as it's more concise and provides better error messages at assignment time.++## Default values++Default values can be easily checked by:++1. Using the rake task: `bin/rake spree:dependencies:list`+2. Looking at the source code:+ * [Application (global) dependencies](https://github.com/spree/spree/blob/main/core/lib/spree/core/dependencies.rb)+ * [API level dependencies](https://github.com/spree/spree/blob/main/api/lib/spree/api/dependencies.rb)diff --git a/docs/v6/developer/customization/quickstart.mdx b/docs/v6/developer/customization/quickstart.mdxnew file mode 100644index 0000000000..9668b1a215--- /dev/null+++ b/docs/v6/developer/customization/quickstart.mdx@@ -0,0 +1,251 @@+---+title: Quickstart+og:title: Spree Customization Quickstart+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 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.++<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.+</Note>++## Quick reference++| What you want to do | Recommended approach |+|---|---|+| Change store settings (currency, markets, languages) | [Store settings](#store-settings) |+| Tweak Spree behavior globally | [Configuration](#configuration) |+| 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) |+| Replace a whole workflow or service | [Dependencies](#dependencies) |+| Add associations/validations to models | [Decorators](#decorators) (last resort) |++<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](/developer/dashboard/customization/quickstart).+</Info>++<AccordionGroup>+ <Accordion title="Store settings" defaultOpen>+ **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.+ </Accordion>+ <Accordion title="Configuration">+ **Best for:** tweaking Spree's behavior globally.++ ```ruby config/initializers/spree.rb+ Spree.config do |config|+ config.minimum_password_length = 10+ end+ ```++ See [Configuration](/v6/developer/customization/configuration).+ </Accordion>+ <Accordion title="Workflow hooks">+ **Best for:** running your own logic *inside* a core flow — checkout completion, order cancellation, refunds, fulfillment creation.++ <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.+ </Info>++ Register a handler against a hook key — `<workflow key>.<hook name>`:++ ```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+ ```++ Pass a class instead of a block for anything longer than a line:++ ```ruby+ Spree.hooks.register('carts.complete.after_finalize', 'MyApp::PushOrderToERP')+ ```++ There are three families of hook:++ | 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 |++ Hook keys are validated after boot, so a typo fails startup rather than silently never running.++ See [Services & Workflows](/developer/customization/workflows) for the full list of flows and their hooks.+ </Accordion>+ <Accordion title="Events and subscribers">+ **Best for:** reacting *after* something happened — syncing to external systems, notifications, audit logging.++ ```ruby app/subscribers/spree/order_placed_subscriber.rb+ module Spree+ class OrderPlacedSubscriber < Spree::Subscriber+ subscribes_to 'order.placed'++ def handle(event)+ order = Spree::Order.find_by_prefix_id(event.payload['id'])+ return unless order++ MyApp::ERP.push(order)+ end+ end+ end+ ```++ **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.++ See [Events](/developer/core-concepts/events).+ </Accordion>+ <Accordion title="Checkout steps">+ **Best for:** adding, removing or reordering checkout steps.++ 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::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' }]+ }+ )+ ```++ Or attach a requirement to an existing step:++ ```ruby+ Spree::Checkout::Registry.add_requirement(+ step: :payment,+ field: :po_number,+ message: 'PO number is required',+ satisfied: ->(cart) { cart.metadata['po_number'].present? }+ )+ ```++ Registered requirements appear in the Cart API's `requirements` array, so your storefront renders them without duplicating any rules.++ See [Carts](/v6/developer/core-concepts/carts#checkout-requirements).+ </Accordion>+ <Accordion title="Providers">+ **Best for:** swapping a whole area of behavior for your own implementation.++ Spree 6 exposes pluggable providers for the domains that vary most between businesses:++ | 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 |++ Each is a class you register and select on the relevant record, so no conditional code lands in core.++ See [Fulfillments](/v6/developer/core-concepts/fulfillments#delivery-types) and [Taxes](/developer/core-concepts/taxes).+ </Accordion>+ <Accordion title="Search and filtering">+ **Best for:** making custom fields searchable and sortable in the dashboard and API.++ ```ruby config/initializers/spree.rb+ Spree.ransack.add_attribute(Spree::Product, :erp_id)+ Spree.ransack.add_association(Spree::Product, :brand)+ Spree.ransack.add_scope(Spree::Product, :featured)+ ```++ See [Search & Filtering](/developer/core-concepts/search-filtering).+ </Accordion>+ <Accordion title="Authentication">+ **Best for:** using your own user model or identity provider.++ 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`.++ See [Authentication](/developer/customization/authentication).+ </Accordion>+ <Accordion title="Webhooks">+ **Best for:** notifying external services — ERPs, CRMs, fulfillment systems — without writing Ruby.++ Configure them in the dashboard under **Settings → Webhooks**, or through the Admin API.++ See [Webhooks](/developer/core-concepts/webhooks).+ </Accordion>+ <Accordion title="Dependencies">+ **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.+ </Warning>++ 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](/v6/developer/customization/dependencies).+ </Accordion>+ <Accordion title="Decorators">+ **Best for:** adding associations, validations and scopes to Spree models. Use as a last resort.++ <Warning>+ Decorators couple your code to Spree internals and are the most common cause of painful upgrades.++ **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](/developer/dashboard/customization/quickstart)+ </Warning>++ 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.scope :featured, -> { where(featured: true) }+ end++ def full_title+ "#{brand&.name} #{name}"+ end+ end++ Product.prepend(ProductDecorator)+ end+ ```++ See [Decorators](/developer/customization/decorators).+ </Accordion>+</AccordionGroup>++## Choosing between hooks, events and dependencies++These three overlap, and picking the wrong one is the most common source of upgrade pain:++<Steps>+ <Step title="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>+ <Step title="Do you just need to know it happened?">+ Use an **event subscriber**. It's decoupled, testable, and survives upgrades untouched.+ </Step>+ <Step title="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.+ </Step>+</Steps>++## Related++- [Services & Workflows](/developer/customization/workflows) — the workflow model and every hook+- [Carts](/v6/developer/core-concepts/carts) — checkout requirements and completion+- [Dashboard Customization](/developer/dashboard/customization/quickstart) — extending the admin