Skip to content

armgit / spree

Public Imported from GitHub
0

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.

Docs: Add build a marketplace guide

Damian Legawiecd79229087925
diff --git a/docs/.mintlify/Assistant.md b/docs/.mintlify/Assistant.md
index a334ac19b2..52ce1ca96c 100644
--- a/docs/.mintlify/Assistant.md
+++ b/docs/.mintlify/Assistant.md
@@ -2,4 +2,7 @@
- Store API v3 is the current stable release. Storefront API v2 is deprecated. DO NOT recommend using Storefront API v2 endpoints. ALWAYS look for Store API v3 endpoints first when recommending API endpoints for storefront use cases.
- Admin API v3 is the current stable release. Platform API v2 is deprecated. DO NOT recommend using Platform API v2 endpoints. ALWAYS look for Admin API v3 endpoints first when recommending API endpoints for admin use cases.
- Spree is headless platform. In the past there were some tightly coupled frontend gems, but they are deprecated and should not be used or recommended. Always recommend using Store API v3 for storefront development.
-- NEVER recommend using `spree_storefront` or `spree_frontend` gems - ALWAYS recommend using Next.js storefront or custom storefront built on top of Store API v3.
+- NEVER recommend using `spree_storefront` or `spree_frontend` gems - ALWAYS recommend using Next.js storefront or custom storefront built on top of Store API v3. Spree DOES NOT provide any storefront themes, visual page builder and so on. Spree is a headless platform and the frontend is up to the user to implement.
+- IGNORE all v5 prefixed docs unless user specifies they are using Spree 5. The current version is Spree 6.
+- CMS is outside of Spree scope, however Spree can be integrated with any headless CMS like Sanity, Strapi, Payload CMS, etc. Spree does not provide any CMS functionality out of the box.
+- DO NOT mention, recommend or provide any guidance on Spree API v2: Platform API v2 or Storefront API v2. They are deprecated and should not be used for any new development.
diff --git a/docs/developer/agentic/llm-docs.mdx b/docs/developer/agentic/llm-docs.mdx
index a3cf0777ee..ac92ef171b 100644
--- a/docs/developer/agentic/llm-docs.mdx
+++ b/docs/developer/agentic/llm-docs.mdx
@@ -29,7 +29,7 @@ https://spreecommerce.org/docs/developer/core-concepts/orders.md
The full developer documentation also ships as an npm package, so agents working in your repository can `Read` doc files locally — no network round-trips, works offline, and version-pinned to what you installed:
```bash
-npm install --save-dev @spree/docs
+pnpm add -D @spree/docs
```
```text
diff --git a/docs/developer/core-concepts/sellers.mdx b/docs/developer/core-concepts/sellers.mdx
index e6dfc673b1..4b6d95d0a0 100644
--- a/docs/developer/core-concepts/sellers.mdx
+++ b/docs/developer/core-concepts/sellers.mdx
@@ -324,19 +324,23 @@ The scheduler is the host app's. Two jobs fan out per seller and the interval lo
| `Spree::SellerPayouts::SweepDueJob` | daily | settles every seller who is due |
| `Spree::SellerTransfers::ExecutePendingDueJob` | hourly | retries earnings a provider refused — usually a passing thing |
+A project created with `create-spree-app` schedules both already, in
+`server/config/recurring.yml`. They are a cheap no-op on a store with no
+sellers, so there is nothing to turn off if you are not running a marketplace.
+
<Warning>
- **You have to schedule these yourself** — a new project does not ship them, so
- a marketplace that skips this step never pays a seller. Add both to your
- scheduler; with Solid Queue that is `server/config/recurring.yml`:
+ On an existing project, or one using a scheduler of its own, check both are
+ scheduled — a marketplace that never runs the sweep never pays a seller, and
+ nothing reports the omission.
```yaml server/config/recurring.yml
production:
sweep_due_seller_payouts:
class: Spree::SellerPayouts::SweepDueJob
- schedule: every day at 3am
+ schedule: at 3am every day
execute_pending_seller_transfers:
class: Spree::SellerTransfers::ExecutePendingDueJob
- schedule: every hour
+ schedule: every hour at minute 27
```
</Warning>
diff --git a/docs/developer/create-spree-app/quickstart.mdx b/docs/developer/create-spree-app/quickstart.mdx
index 604ea11720..55d8003a21 100644
--- a/docs/developer/create-spree-app/quickstart.mdx
+++ b/docs/developer/create-spree-app/quickstart.mdx
@@ -146,7 +146,7 @@ If you included the storefront, start it in a separate terminal:
```bash
cd my-store/apps/storefront
-npm run dev
+pnpm dev
```
Open [http://localhost:3001](http://localhost:3001) to see your store.
diff --git a/docs/developer/dashboard/customization/theming.mdx b/docs/developer/dashboard/customization/theming.mdx
new file mode 100644
index 0000000000..97258bfac9
--- /dev/null
+++ b/docs/developer/dashboard/customization/theming.mdx
@@ -0,0 +1,165 @@
+---
+title: Theming
+description: Restyle the dashboard by overriding its design tokens — colours, radius, fonts and the type scale — without forking a single component.
+---
+
+The dashboard is styled entirely from CSS custom properties. Components read
+tokens rather than hard-coded colours, so changing a token restyles everything
+that uses it — you never fork a component to recolour it.
+
+## Where your styles go
+
+Your app's `src/styles.css` imports the Spree stylesheet. Anything below that
+import wins, because it lands later at the same specificity:
+
+```css src/styles.css
+@import "@spree/dashboard/styles.css";
+
+:root {
+ --primary: oklch(0.55 0.22 264);
+ --radius: 0.25rem;
+}
+```
+
+That is the whole mechanism. No build config, no plugin, no component overrides.
+
+<Note>
+ The seller panel works the same way — its starter imports
+ `@spree/seller-dashboard/styles.css`, and the same tokens apply.
+</Note>
+
+## Dark mode
+
+Every token has a dark counterpart under `.dark`. A theme is only complete when
+you set both:
+
+```css src/styles.css
+@import "@spree/dashboard/styles.css";
+
+:root {
+ --primary: oklch(0.55 0.22 264);
+}
+
+.dark {
+ --primary: oklch(0.72 0.19 264);
+}
+```
+
+<Warning>
+ The theme provider decides *mode* — light, dark or system — and toggles a
+ `.dark` class. It holds no colours. Override only `:root` and your theme
+ breaks the moment someone switches to dark.
+</Warning>
+
+## The tokens
+
+### Surfaces and text
+
+| Token | What it colours |
+|---|---|
+| `--background` / `--foreground` | The page, and text on it |
+| `--card` / `--card-foreground` | Cards, and text on them |
+| `--popover` / `--popover-foreground` | Menus, dropdowns, popovers |
+| `--muted` / `--muted-foreground` | Recessed surfaces and secondary text |
+
+### Brand and interaction
+
+| Token | What it colours |
+|---|---|
+| `--primary` / `--primary-foreground` | Primary buttons and calls to action |
+| `--secondary` / `--secondary-foreground` | Secondary buttons |
+| `--accent` / `--accent-foreground` | Hovered rows, selected items |
+| `--accent-hover`, `--accent-strong`, `--accent-strong-hover` | Deeper accent steps |
+| `--link` / `--link-hover` | Inline text links |
+| `--ring` | Focus rings |
+
+### Status
+
+`--destructive` and `--destructive-foreground` for dangerous actions, plus four
+status families used by badges and callouts — each with `-bg`, `-border` and
+`-fg`:
+
+`--status-green-*`, `--status-amber-*`, `--status-red-*`, `--status-blue-*`
+
+### Borders and structure
+
+| Token | What it colours |
+|---|---|
+| `--border` | The default border, aliasing `--border-base` |
+| `--border-card`, `--border-subtle`, `--border-control` | Cards, dividers, inputs |
+| `--input` | Input borders |
+| `--radius` | Corner radius everywhere |
+
+### Sidebar
+
+The sidebar has its own family so you can give the chrome a different tone from
+the content: `--sidebar`, `--sidebar-foreground`, `--sidebar-primary`,
+`--sidebar-accent` and its hover steps, `--sidebar-border`, `--sidebar-ring`.
+
+### Charts
+
+`--chart-1` through `--chart-5`, in series order.
+
+## Tokens defined from other tokens
+
+Several tokens alias another rather than naming their own colour:
+
+```css
+--primary: var(--foreground);
+--popover: var(--card);
+--accent: var(--secondary);
+--muted: var(--background);
+```
+
+So overriding one base token cascades. Setting `--foreground` alone also moves
+primary buttons, because that is where `--primary` points. Override the alias
+directly when you want them to diverge.
+
+## Fonts and the type scale
+
+Typography is set in a `@theme inline` block and overridden the same way:
+
+```css src/styles.css
+@import "@spree/dashboard/styles.css";
+
+@theme inline {
+ --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
+ --text-base: 0.9375rem;
+}
+```
+
+The dashboard's scale is deliberately smaller than Tailwind's default, because
+admin screens are dense. Raising `--text-base` raises everything built on it.
+
+## Using tokens in your own pages
+
+Tailwind maps every token through `@theme inline`, so utilities follow your
+values with no extra work:
+
+```tsx
+<div className="bg-card text-card-foreground border-border rounded-lg border">
+ <p className="text-muted-foreground">Follows your theme.</p>
+</div>
+```
+
+Use the utilities rather than raw `var(--token)` — a page built from
+`bg-card` and `text-muted-foreground` inherits every future change, including
+dark mode.
+
+For inline text links there is a `.link` class carrying the canonical treatment:
+
+```tsx
+<Link to="/$storeId/settings/store" params={{ storeId }} className="link">
+ Store settings
+</Link>
+```
+
+It is for links in prose and help text. A link that is really a table row, a
+breadcrumb, a nav item or a button rendered as an anchor carries its own
+styling, and `.link` would fight it.
+
+## Related
+
+- [Dashboard overview](/developer/dashboard/overview) — the three packages and what each is for
+- [Translations](/developer/dashboard/customization/translations) — the other half of white-labelling
+- [Slots](/developer/dashboard/customization/slots) — adding your own UI to existing screens
diff --git a/docs/developer/dashboard/overview.mdx b/docs/developer/dashboard/overview.mdx
index d292be0f54..abc237289d 100644
--- a/docs/developer/dashboard/overview.mdx
+++ b/docs/developer/dashboard/overview.mdx
@@ -46,7 +46,7 @@ Your copy of the dashboard is a small Vite app (the "host app") that imports `<D
- **New project:** `npx create-spree-app my-store` — answer **Yes** to "Include React Dashboard?" and it lands in `apps/dashboard/`, pointed at your API.
- **Existing project:** run `npx spree add dashboard` from your project root — same result.
-Either way: `cd apps/dashboard && npm run dev`, open http://localhost:5173, and sign in with your admin email and password. No API keys to configure — admins authenticate interactively.
+Either way: `cd apps/dashboard && pnpm dev`, open http://localhost:5173, and sign in with your admin email and password. No API keys to configure — admins authenticate interactively.
## Choose your path
diff --git a/docs/developer/deployment/background_jobs.mdx b/docs/developer/deployment/background_jobs.mdx
index ca9ca6267d..ed8320d678 100644
--- a/docs/developer/deployment/background_jobs.mdx
+++ b/docs/developer/deployment/background_jobs.mdx
@@ -34,11 +34,12 @@ production:
### Marketplace payouts
-A marketplace has to schedule one more job, or its sellers are never paid:
+A marketplace settles its sellers on a recurring job, which a new project
+already schedules:
```yaml config/recurring.yml
production:
- sweep_seller_payouts:
+ sweep_due_seller_payouts:
class: Spree::SellerPayouts::SweepDueJob
schedule: at 3am every day
```
diff --git a/docs/developer/deployment/emails.mdx b/docs/developer/deployment/emails.mdx
index d6212d08b4..a3eff7e039 100644
--- a/docs/developer/deployment/emails.mdx
+++ b/docs/developer/deployment/emails.mdx
@@ -141,7 +141,7 @@ When `SMTP_HOST` is not set, emails are printed to the Rails log instead of bein
In development, no email provider is needed. Emails are rendered to HTML files in `.next/emails/` with a clickable `file://` link in the console. To preview and design templates:
```bash
-npm run email:dev
+pnpm email:dev
```
To test the full webhook flow locally, use [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/):
diff --git a/docs/developer/how-to/build-a-marketplace.mdx b/docs/developer/how-to/build-a-marketplace.mdx
index d998687eef..5f579c57db 100644
--- a/docs/developer/how-to/build-a-marketplace.mdx
+++ b/docs/developer/how-to/build-a-marketplace.mdx
@@ -1,13 +1,13 @@
---
title: Build a Multi-Vendor Marketplace
-description: Marketplace capabilities are part of Spree core — sellers, order splitting, commissions and payouts, without a separate extension.
+description: Learn how to extremely fast launch a marketplace on Spree
---
-This guide covers the open-source core.
+Spree fully supports multi-vendor marketplaces out of the box: sellers are first-class records, orders split per seller at completion, robust commission engine, and a payout ledger with pluggable payout providers.
-Spree brings multi-vendor marketplace support into the open-source core: sellers as first-class records, orders split per seller at completion, a commission engine, and a payout ledger with pluggable payout providers.
+So building a marketplace doesn't require weeks or months of development, it's just configuring your Spree application to admit sellers, review their submissions, and pay them. In most cases you don't need to customize Spree or write any code at all. This guide is a walkthrough of all elements that make a marketplace, and how to configure them.
-## What you will build
+## What you get
- **Sellers** — onboard sellers with an operator-configured requirements checklist, review submissions, and approve them for selling.
- **Order splitting** — a customer checks out once; completion produces per-seller orders grouped under one purchase.
@@ -15,11 +15,796 @@ Spree brings multi-vendor marketplace support into the open-source core: sellers
- **Payouts** — a transfer and payout ledger, with Stripe Connect payouts (Express onboarding, on-fulfillment transfers) shipping in the open-source monorepo.
- **Seller operations** — sellers work through their own dedicated API surface, scoped so a seller only ever sees their own trade.
-## Outline
+## Before you start
-1. Enable marketplace capabilities and configure the store
-2. Define seller onboarding requirements
-3. Invite and approve sellers
-4. Assign catalog to sellers and take a multi-seller order through checkout
-5. Configure commissions
-6. Connect Stripe for payouts
+You need a running Spree 6 project and admin credentials. The marketplace surfaces are:
+
+| Surface | Who uses it | Package |
+|---|---|---|
+| Admin dashboard | The marketplace operator | [`@spree/dashboard`](/developer/dashboard/overview) |
+| Seller panel | Each seller's own team | [`@spree/seller-dashboard`](#step-7-stand-up-the-seller-panel) |
+| Admin API | Operator-side integrations | [`@spree/admin-sdk`](/api-reference/admin-api/introduction) |
+| Seller API | A signed-in seller only | [`@spree/seller-sdk`](/api-reference/seller-api/introduction) |
+
+To try the flow quickly, you can seed a sample seller with an owner account, a pending invitation and a fund ledger:
+
+<CodeGroup>
+
+```bash Spree CLI
+spree run rake spree:sellers:sample_data
+```
+
+```bash Without CLI
+bin/rails spree:sellers:sample_data
+```
+
+</CodeGroup>
+
+The task refuses to run outside development and test, because it writes a known password. It signs in at `[email protected]` / `spree123` — override with `SELLER_EMAIL`, `SELLER_PASSWORD` and `SELLER_NAME`.
+
+## Configure the store for marketplace trading
+
+There is no single "marketplace mode" switch. A store becomes a marketplace when it has sellers; what you configure up front is how strictly it admits them and how it pays them.
+
+### Payout settings
+
+Three store preferences decide how sellers get paid. All three are writable through the Admin API, and they appear in the dashboard under **Settings → Marketplace**.
+
+| Preference | Default | What it decides |
+|---|---|---|
+| `preferred_payout_provider` | blank | Who moves the money. Blank means core's record-only provider: the ledger is kept correctly and the operator settles by hand. |
+| `preferred_default_payouts_schedule_interval` | `monthly` | How often sellers are settled. One of `daily`, `weekly`, `biweekly`, `monthly`, `manual`. A seller can carry its own interval, which wins. |
+| `preferred_default_minimum_payout_amount` | `0` | What a seller's balance must reach before a settlement is worth sending. Below it the balance carries to the next period. |
+
+<CodeGroup>
+
+```typescript Admin SDK
+await adminClient.store.update({
+ preferred_default_payouts_schedule_interval: 'weekly',
+ preferred_default_minimum_payout_amount: 25,
+})
+```
+
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/store' \
+ -H 'X-Spree-API-Key: sk_xxx' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "preferred_default_payouts_schedule_interval": "weekly",
+ "preferred_default_minimum_payout_amount": 25
+ }'
+```
+
+</CodeGroup>
+
+A mistyped provider key is refused at write time rather than silently ignored, so you cannot end up with a bookkeeping-only ledger and no indication that your choice was dropped. Ask the API which providers are registered before you set one:
+
+```bash
+curl 'https://api.mystore.com/api/v3/admin/payout_providers' \
+ -H 'X-Spree-API-Key: sk_xxx'
+```
+
+### Admission and review settings
+
+Four more preferences decide who gets to trade and what they hear from you. They
+sit on the same **Settings → Marketplace** screen, and are writable through the
+Admin API like the payout ones.
+
+| Preference | Default | What it decides |
+|---|---|---|
+| `preferred_auto_approve_sellers` | `false` | Admit a seller the moment they finish the checklist, with nobody looking at them. |
+| `preferred_auto_approve_seller_products` | `false` | Put a seller's product on sale the moment they submit it. |
+| `preferred_send_seller_transactional_emails` | `true` | Whether Spree emails sellers. Turn it off if you front seller communications yourself. |
+| `preferred_default_commission_tax_rate` | `0` | Tax on your commission when neither the rate nor the tax provider names one. |
+
+<CodeGroup>
+
+```typescript Admin SDK
+await adminClient.store.update({
+ preferred_auto_approve_sellers: false,
+ preferred_auto_approve_seller_products: false,
+ preferred_send_seller_transactional_emails: true,
+ preferred_default_commission_tax_rate: 0.23,
+})
+```
+
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/store' \
+ -H 'X-Spree-API-Key: sk_xxx' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "preferred_auto_approve_sellers": false,
+ "preferred_auto_approve_seller_products": false,
+ "preferred_send_seller_transactional_emails": true,
+ "preferred_default_commission_tax_rate": 0.23
+ }'
+```
+
+</CodeGroup>
+
+<Warning>
+Turning either auto-approve preference on removes a human decision from your marketplace. `auto_approve_sellers` lets any applicant who ticks every box start trading; `auto_approve_seller_products` puts their listings on sale without review. Both are appropriate for an invite-only marketplace where you already trust the sellers, and dangerous for an open one.
+</Warning>
+
+Commission tax is stored as a fraction — `0.23` means 23%. The dashboard asks for
+a percentage and converts, so you only meet the fraction through the API. See
+[Tax on commission](/developer/core-concepts/commissions#tax-on-commission) for
+when it applies and what overrides it.
+
+## Define what a seller must do before trading
+
+A seller requirement is one thing the marketplace asks of a seller before it will let them trade. The operator composes the checklist from registered **kinds** — rows are configuration, and only a genuinely new kind of check needs code.
+
+The checklist is enforced in exactly two places: when the seller asks to be reviewed, and when the operator approves them. Nothing else consults it.
+
+### The kinds that ship
+
+Thirteen kinds are registered by core. Seven of them are provisioned into a new store's default checklist, in the order a seller meets them.
+
+| `type` | What it asks | Default? | Seller submits? | Operator reviews? |
+|---|---|:---:|:---:|:---:|
+| `accept_terms` | Read and accept the marketplace terms | ✅ | — | — |
+| `complete_profile` | Fill in the public profile shoppers see | ✅ | — | — |
+| `billing_address` | The address commission invoices are addressed to | ✅ | — | — |
+| `returns_address` | Where customer returns are sent | ✅ | — | — |
+| `delivery_method` | At least one way to ship | ✅ | — | — |
+| `package_type` | The box they ship orders in, with measurements | ✅ | — | — |
+| `minimum_products` | List at least this many products | ✅ | — | — |
+| `payout_account` | An account the payout provider will pay | — | — | — |
+| `required_custom_fields` | Named custom fields filled in (VAT number, registration number) | — | — | — |
+| `policy` | Publish a policy with this name | — | — | — |
+| `attestation` | Confirm something in their own right | — | ✅ | — |
+| `operator_review` | Something a person at the marketplace checks by hand | — | ✅ | ✅ |
+| `document` | Upload a file for the marketplace to review | — | ✅ | ✅ |
+
+The first ten are **computed**: Spree reads the seller's own data and answers for itself, so there is nothing for the seller to submit. The last three take a **submission** — a row recording what the seller said and when — and the bottom two wait for someone to accept it.
+
+Four kinds may be configured more than once per store, because their meaning comes from the operator's own wording: `attestation`, `operator_review`, `document` and `policy`. Those four require a `name`. The rest are one per store.
+
+<Note>
+The generic kinds are deliberately absent from the default checklist. An attestation or a document means nothing until the operator has written what they are asking for, so Spree does not guess.
+</Note>
+
+### Build the checklist from the registry, never a hardcoded list
+
+Always read the kinds from `types()` rather than shipping your own list — a marketplace's own registered kinds then appear for free. The endpoint returns each kind's `preference_schema`, which is what a configuration form renders from.
+
+<CodeGroup>
+
+```typescript Admin SDK
+// What an operator can add, and the shape of each one's config form
+const { data: kinds } = await adminClient.sellerRequirements.types()
+
+// Ask every seller for a business registration
+await adminClient.sellerRequirements.create({
+ type: 'document',
+ name: 'Business registration',
+ description: 'A certificate of incorporation or equivalent.',
+ required: true,
+})
+
+// Collect a VAT number through a custom field definition on Spree::Seller
+await adminClient.sellerRequirements.create({
+ type: 'required_custom_fields',
+ custom_field_definition_ids: ['cfd_xxx'],
+ required: true,
+})
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/admin/seller_requirements/types' \
+ -H 'X-Spree-API-Key: sk_xxx'
+
+curl -X POST 'https://api.mystore.com/api/v3/admin/seller_requirements' \
+ -H 'X-Spree-API-Key: sk_xxx' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "type": "document",
+ "name": "Business registration",
+ "description": "A certificate of incorporation or equivalent.",
+ "required": true
+ }'
+```
+
+</CodeGroup>
+
+Each kind takes its own configuration through `preferences`. `accept_terms` carries `terms_body`, `terms_url` and `terms_effective_from` — setting that date is how you ask everyone again after rewriting the terms, since anyone who accepted before it falls back to unmet. `minimum_products` carries `minimum_count`. `complete_profile` carries `require_about`, `require_logo`, `require_cover_photo` and `require_contact_email`.
+
+Two flags govern every row regardless of kind. `required: false` makes a line advisory — it appears on the seller's checklist but does not gate approval. `active: false` retires it without deleting the submissions that answered it. Position is the order sellers work through, and the list is drag-ordered in the dashboard.
+
+<Note>
+`type` is write-once. The API strips it on update, because a saved row's submissions answered the old kind. To change a kind, delete the row and create a new one.
+</Note>
+
+**Read more:** [Onboarding requirements](/developer/core-concepts/sellers#onboarding-requirements) for the model, and [Seller Requirements](/user/settings/seller-requirements) for the operator's screen.
+
+## Invite a seller and approve them
+
+A seller moves through its life on the marketplace by **workflow**, never by assigning a status. Each transition is its own Admin API action because each carries its own arguments, sends its own mail and runs its own extension hooks — mass assignment would skip all three.
+
+```mermaid
+stateDiagram-v2
+ [*] --> pending : sellers.create
+ pending --> invited : sellers.invite
+ invited --> onboarding : invitation accepted
+ onboarding --> ready_for_review : seller submits
+ ready_for_review --> approved : sellers.approve
+ ready_for_review --> onboarding : sellers.reopenOnboarding
+ onboarding --> rejected : sellers.reject
+ ready_for_review --> rejected : sellers.reject
+ rejected --> approved : sellers.approve
+ approved --> suspended : sellers.suspend
+ suspended --> approved : sellers.approve
+```
+
+| Status | Meaning |
+|---|---|
+| `pending` | Created; nothing sent yet |
+| `invited` | Someone has been asked to run it, and has not accepted |
+| `onboarding` | Somebody accepted and is working through the checklist |
+| `ready_for_review` | The seller says they are done; waiting on the operator |
+| `approved` | Trading |
+| `rejected` | An applicant turned away |
+| `suspended` | A trading seller halted; reversible |
+| `canceled` | Closed |
+
+### Create and invite
+
+Creating a seller through the workflow provisions a stock location for them, which is where their inventory lives and where customer returns land. A seller without one cannot finish onboarding, so this is not a step an operator can forget.
+
+<CodeGroup>
+
+```typescript Admin SDK
+const seller = await adminClient.sellers.create({
+ name: 'Bright Sparks',
+ contact_email: '[email protected]',
+})
+
+// Opens the seller's own team to someone; they join when they accept
+await adminClient.sellers.invite(seller.id, { email: '[email protected]' })
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/sellers' \
+ -H 'X-Spree-API-Key: sk_xxx' \
+ -H 'Content-Type: application/json' \
+ -d '{ "name": "Bright Sparks", "contact_email": "[email protected]" }'
+
+curl -X POST 'https://api.mystore.com/api/v3/admin/sellers/sel_xxx/invite' \
+ -H 'X-Spree-API-Key: sk_xxx' \
+ -H 'Content-Type: application/json' \
+ -d '{ "email": "[email protected]" }'
+```
+
+</CodeGroup>
+
+The invited person accepts through the seller panel — the emailed link carries a prefixed ID and a token, which together are the credential. Accepting creates the membership and starts onboarding, so the seller reaches `onboarding` without the operator doing anything more.
+
+Re-inviting is deliberate: invitations expire, and the first one goes to the wrong address often enough. What cannot be re-opened is a seller already trading or already turned away.
+
+`role_id` names a role the seller owns; leave it out and they accept into the seller's own admin role. A seller's roles are the same permission machinery the store's back office uses, pointed at the seller — see [Staff & Roles](/developer/core-concepts/staff-roles).
+
+### Review submissions
+
+The two reviewed kinds (`operator_review`, `document`) leave a submission for someone to decide. Accepting one satisfies that line of the checklist; rejecting sends it back with a note the seller reads.
+
+<CodeGroup>
+
+```typescript Admin SDK
+const { data: submissions } = await adminClient.sellers.requirementSubmissions.list('sel_xxx')
+
+await adminClient.sellers.requirementSubmissions.accept('sel_xxx', 'selsub_xxx')
+
+await adminClient.sellers.requirementSubmissions.reject('sel_xxx', 'selsub_xxx', {
+ review_note: 'The certificate has expired — please upload a current one.',
+})
+
+// Excuse this seller from something the store asks of everyone
+await adminClient.sellers.requirementSubmissions.waive('sel_xxx', {
+ requirement_id: 'selreq_xxx',
+ review_note: 'Verified against Companies House by hand.',
+})
+```
+
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/sellers/sel_xxx/requirement_submissions/selsub_xxx/reject' \
+ -H 'X-Spree-API-Key: sk_xxx' \
+ -H 'Content-Type: application/json' \
+ -d '{ "review_note": "The certificate has expired — please upload a current one." }'
+```
+
+</CodeGroup>
+
+A submission is `pending`, `accepted`, `rejected` or `waived`. A waiver is the operator recording that they dealt with this outside the marketplace — it reads as met without pretending the seller did it. Submissions accumulate rather than overwrite: the latest row for a (seller, requirement) pair decides the standing, and the ones before it are the record of how you got there.
+
+Uploaded documents are stored privately and served only through the admin and seller branches. They are business registrations and identity documents, and Spree identifies them from their bytes rather than trusting the uploaded filename — a script named `certificate.pdf` is refused.
+
+### Approve, suspend, reject
+
+<CodeGroup>
+
+```typescript Admin SDK
+// Where this seller stands against the checklist
+const onboarding = await adminClient.sellers.onboarding('sel_xxx')
+// → { status, progress: { done, total }, requirements: [...] }
+
+await adminClient.sellers.approve('sel_xxx')
+
+// Admit them anyway, despite an unfinished checklist
+await adminClient.sellers.approve('sel_xxx', { override_requirements: true })
+
+// Send them back to fix something
+await adminClient.sellers.reopenOnboarding('sel_xxx', {
+ note: 'Your returns address is a PO box — we need a street address.',
+})
+
+await adminClient.sellers.suspend('sel_xxx', { reason: 'Unresolved delivery complaints' })
+await adminClient.sellers.reject('sel_xxx', { reason: 'Outside our categories' })
+```
+
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/sellers/sel_xxx/approve' \
+ -H 'X-Spree-API-Key: sk_xxx' \
+ -H 'Content-Type: application/json' \
+ -d '{ "override_requirements": true }'
+```
+
+</CodeGroup>
+
+Approval is refused while a required requirement is unmet, unless `override_requirements` says the operator means it. The override is recorded on the `seller.approved` event along with what was outstanding — the operator can step over the checklist, but not without saying so.
+
+**Suspend and reject are not the same thing.** Reject turns away an applicant who never traded; it refuses an approved seller outright. Suspend halts a trading seller: their catalog stops selling, their record and history stay, and `approve` is the way back. A suspended seller being reinstated is not re-measured against the checklist, because they were admitted once already.
+
+A seller can also take themselves off sale without any operator involvement, by setting `holiday_mode_until`. The catalog stays visible; what stops is selling.
+
+**Read more:** [The seller lifecycle](/developer/core-concepts/sellers#the-seller-lifecycle), [Onboarding](/user/sellers/onboarding), [Managing sellers](/user/sellers/managing-sellers).
+
+## Review what sellers list
+
+Products belong to sellers through `seller_id` on `Spree::Product`. A product with no seller is the marketplace's own.
+
+A marketplace adds two statuses to the product lifecycle that a single-merchant store never sees: `proposed` and `rejected`. A seller never assigns a status — they ask, and the marketplace decides.
+
+```mermaid
+stateDiagram-v2
+ draft --> proposed : seller submits
+ proposed --> active : operator approves
+ proposed --> rejected : operator rejects
+ rejected --> proposed : seller resubmits
+ active --> draft : seller takes it down
+ active --> archived : seller withdraws it
+```
+
+| Status | Meaning | Storefront |
+|---|---|:---:|
+| `draft` | The seller is still working on it | Hidden |
+| `proposed` | Submitted, waiting on the marketplace | Hidden |
+| `rejected` | Sent back with a reason, awaiting changes | Hidden |
+| `active` | Approved and on sale | **Visible** |
+| `archived` | Withdrawn | Hidden |
+
+A seller can always take their own listing down — that is not a review decision. Putting one up is.
+
+### How it relates to the submission record
+
+The product's `status` is the operational truth; a `Spree::ProductSubmission` row is the record of how it got there — who asked, who decided, when, and what they told the seller. Its statuses are `pending`, `approved`, `rejected` and `withdrawn`.
+
+Rows accumulate: a seller sent back three times leaves three rows, and the latest one is live. Taking a listing back to `draft` before anyone ruled on it closes the open row as `withdrawn`, so a `pending` row always means the marketplace still owes an answer rather than "abandoned".
+
+<Warning>
+A rejection reason belongs on the submission, never on the product. A seller can write their own product's `metadata`, so a note kept there is erased the next time they save. Send it as `reason` to the reject endpoint and Spree puts it where the seller cannot overwrite it.
+</Warning>
+
+### Both sides of the review
+
+<CodeGroup>
+
+```typescript Seller SDK
+// The seller asks for their listing to go on sale
+await sellerClient.products.submit(productId)
+
+// Or a selection of them
+await sellerClient.products.bulkSubmit({ ids: [id1, id2] })
+```
+
+```typescript Admin SDK
+// The operator decides
+await adminClient.products.approve('prod_xxx')
+await adminClient.products.reject('prod_xxx', {
+ reason: 'The lead photo has a competitor watermark.',
+})
+```
+
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/products/prod_xxx/reject' \
+ -H 'X-Spree-API-Key: sk_xxx' \
+ -H 'Content-Type: application/json' \
+ -d '{ "reason": "The lead photo has a competitor watermark." }'
+```
+
+</CodeGroup>
+
+Filter the review queue with a Ransack query on status: `adminClient.products.list({ status_eq: 'proposed' })`.
+
+With `preferred_auto_approve_seller_products` on, submitting chains straight into approval. The submission row still gets written and carries an `auto_approved` marker, so a blank reviewer reads as "this store does not review listings" rather than as a lost name.
+
+There is no bulk route onto `active` for sellers, and that is deliberate: reaching it is the operator's decision on one listing at a time.
+
+**Read more:** [Seller submissions](/developer/core-concepts/products#seller-submissions), [Seller products](/user/sellers/products).
+
+## Set what the marketplace charges
+
+Commission is what the marketplace takes from a sale. You configure **rates**; Spree records what was actually charged as immutable **commission lines**, frozen when the order was placed.
+
+### Rates and precedence
+
+**The list is the precedence.** Rates are walked top-down and the first whose targeting matches the sale wins. A rate with no rules matches every sale, so anything below it is unreachable — the marketplace default belongs at the bottom of the list. A new rate is placed at the top by default, ahead of anything more general already there.
+
+<CodeGroup>
+
+```typescript Admin SDK
+// Discover the rule kinds this marketplace has registered
+const { data: ruleTypes } = await adminClient.commissionRates.ruleTypes()
+
+// 8% on one seller's electronics, with a floor and a cap per currency
+await adminClient.commissionRates.create({
+ name: 'Electronics — Bright Sparks',
+ kind: 'percentage',
+ value: 8,
+ rules: [
+ { type: 'seller_rule', preferences: { seller_ids: ['sel_xxx'] } },
+ ],
+})
+
+// The marketplace default, at the bottom, matching everything
+await adminClient.commissionRates.create({
+ name: 'Standard commission',
+ kind: 'percentage',
+ value: 15,
+ position: 99,
+})
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/commission_rates' \
+ -H 'X-Spree-API-Key: sk_xxx' \
+ -H 'Content-Type: application/json' \
+ -d '{ "name": "Standard commission", "kind": "percentage", "value": 15, "position": 99 }'
+```
+
+</CodeGroup>
+
+A rate is either `percentage` (a share of the sale) or `fixed` (a flat fee). A flat fee states its `amounts` per currency — a rate is skipped for a currency it names no amount in, so that sale falls through to the next matching rate rather than being charged a converted figure nobody set.
+
+Rules ride the regular payload as `rules: [...]`, and the server replaces the rate's rules with exactly what it is sent. Every rule must hold for the rate to apply, and a rule naming several records means any of them — so "(Cameras OR Audio) AND that seller" is a category rule holding two ids beside a seller rule holding one.
+
+### Lines are read-only
+
+<CodeGroup>
+
+```typescript Admin SDK
+const { data: lines } = await adminClient.commissionLines.list({ seller_id_eq: 'sel_xxx' })
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/admin/commission_lines?q[seller_id_eq]=sel_xxx' \
+ -H 'X-Spree-API-Key: sk_xxx'
+```
+
+</CodeGroup>
+
+There is no write path. Correcting a charge is a reversal, not an edit.
+
+In the EU the fee is a separate supply from the sale, so it is taxed separately — that is what `preferred_default_commission_tax_rate` from step 1 is for, and a rate or a tax provider can name its own.
+
+**Read more:** [Commissions](/developer/core-concepts/commissions) covers the four rule types, gross-versus-net, how delivery is treated, currency floors and caps, and commission tax in full. [Commission rates](/user/sellers/commission-rates) is the operator's screen.
+
+## Understand what a split checkout produces
+
+This is the part that makes a marketplace different from a shop, and a storefront has to handle it.
+
+A customer fills one basket, enters one address, and pays once. But each seller needs their own order — they fulfil separately, get paid separately, and must never see each other's business. So at completion, a checkout spanning several sellers becomes an **order group**: one container holding one order per seller.
+
+```mermaid
+erDiagram
+ OrderGroup ||--o{ Order : "one per seller"
+ OrderGroup ||--o{ Payment : "one payment"
+ Payment ||--o{ PaymentSplit : "apportioned"
+ Order }o--|| Seller : "belongs to"
+ Order ||--o{ Fulfillment : "shipped by that seller"
+```
+
+| Level | Owns |
+|---|---|
+| **Order group** | The customer, the addresses, the payment, the combined totals |
+| **Order** | One seller's items, fulfillments and money lines |
+
+The single payment is apportioned across the child orders as **payment splits**, so each seller's share of one charge is recorded exactly — which is what makes per-seller refunds and settlement possible later.
+
+Two details worth knowing:
+
+- **Group totals are added up, not divided.** The group's total is the sum of its children, so it always agrees with them.
+- **Delivery and order-level fees are shared out by item value**, so a seller whose goods made up most of the basket carries most of the delivery charge.
+
+<Warning>
+**A storefront must handle the possibility of an order group.** Completing a cart yields either one order or a group, depending on how many sellers the basket reached. A customer's order history should show the group as one purchase rather than confronting them with three orders they don't remember placing separately.
+</Warning>
+
+A single-seller checkout produces no group at all — just the order, exactly as a normal store does. Nothing about a marketplace changes the shape of a single-seller sale.
+
+Operators can read groups back; there is no write path, because everything an operator acts on lives on the orders inside them.
+
+<CodeGroup>
+
+```typescript Admin SDK
+const { data: groups } = await adminClient.orderGroups.list()
+const group = await adminClient.orderGroups.get('ogrp_xxx', { expand: ['orders'] })
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/admin/order_groups/ogrp_xxx?expand=orders' \
+ -H 'X-Spree-API-Key: sk_xxx'
+```
+
+</CodeGroup>
+
+**Read more:** [One checkout, several sellers](/developer/core-concepts/sellers#one-checkout-several-sellers), [Orders](/developer/core-concepts/orders).
+
+## Pay your sellers
+
+The fund ledger has two levels, and both are written by fulfilment and by the scheduled sweep rather than by a caller.
+
+| Level | Model | Written when |
+|---|---|---|
+| **Transfer** | `Spree::SellerTransfer` | One order earned one seller something — credited as the goods went out |
+| **Payout** | `Spree::SellerPayout` | A settlement was swept up and sent |
+
+A seller's balance is derived from the two rather than stored, per currency, because nothing is ever converted: a seller trading in two currencies accrues two balances and is paid twice. Only settlements known to have completed count against the balance, so one whose outcome was never established still reads as owed — the honest answer while nobody knows, and it cannot be paid twice by mistake.
+
+### The sweep jobs
+
+Two recurring jobs keep the ledger moving. A project created with
+`create-spree-app` schedules both already:
+
+```yaml server/config/recurring.yml
+production:
+ sweep_due_seller_payouts:
+ class: Spree::SellerPayouts::SweepDueJob
+ schedule: at 3am every day
+ execute_pending_seller_transfers:
+ class: Spree::SellerTransfers::ExecutePendingDueJob
+ schedule: every hour at minute 27
+```
+
+<Warning>
+On an existing project, or one running a scheduler of its own, confirm both are
+scheduled. A marketplace that never runs the sweep never pays a seller, and
+nothing reports the omission.
+</Warning>
+
+| Job | Run it | Does |
+|---|---|---|
+| `Spree::SellerPayouts::SweepDueJob` | daily | settles every seller who is due |
+| `Spree::SellerTransfers::ExecutePendingDueJob` | hourly | retries earnings a provider refused — usually a passing thing |
+
+### Settling by hand
+
+A seller on the `manual` interval is skipped by the sweep. That is what the interval means: the operator decides when. The same endpoint also pays any seller early.
+
+<CodeGroup>
+
+```typescript Admin SDK
+// Where the seller stands, one row per currency
+const { data: balances } = await adminClient.sellers.balances('sel_xxx')
+
+// Settle them now, whatever their schedule says — 422 if there is nothing owed
+await adminClient.sellers.settle('sel_xxx')
+
+// The built-in provider: record that the bank transfer went out
+await adminClient.sellerPayouts.complete('vpo_xxx', { reference: 'TRN-2026-0912-0042' })
+
+// Read the ledger
+const { data: transfers } = await adminClient.sellerTransfers.list({ seller_id_eq: 'sel_xxx' })
+const { data: payouts } = await adminClient.sellerPayouts.list({ seller_id_eq: 'sel_xxx' })
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/admin/sellers/sel_xxx/balances' \
+ -H 'X-Spree-API-Key: sk_xxx'
+
+curl -X POST 'https://api.mystore.com/api/v3/admin/sellers/sel_xxx/payouts' \
+ -H 'X-Spree-API-Key: sk_xxx'
+```
+
+</CodeGroup>
+
+### Payout providers
+
+A provider is a stateless class registered in `Spree.payout_providers` and chosen per store with `preferred_payout_provider`.
+
+| Provider | Moves money? | Completion |
+|---|---|---|
+| `Spree::PayoutProvider::System` (default) | No — keeps the books | The operator marks each payout paid, with the bank reference |
+| Stripe Connect (`spree_stripe`) | Yes — transfers each earning to the seller's connected account as goods ship | A Stripe webhook, when the money lands |
+
+Providers that need a seller to hold an account with them answer `requires_payout_account?` and implement `onboarding_url` — which is what the `payout_account` requirement from step 2 drives. Those links are short-lived and single-use, so the seller panel asks for a fresh one at the moment of clicking rather than minting one while drawing the checklist.
+
+A connected provider confirms settlements through `POST /api/v3/webhooks/payouts/:payment_method_id` — separate from the payment webhook, because providers scope seller-account events to their own subscription and signing secret.
+
+**Read more:** [Payouts](/developer/core-concepts/sellers#payouts) for the ledger, [Stripe Connect for marketplaces](/integrations/payments/stripe-connect) for the shipped provider, [Seller payouts](/developer/providers/payouts) to write your own, and [Payouts settings](/user/settings/marketplace) for the operator's screen.
+
+<Note>
+Refund clawbacks and netting across settlements, reconciliation, KYC operations and seller tax reporting (DAC7) are Spree Enterprise.
+</Note>
+
+## Stand up the seller panel
+
+Sellers get their own application — never access to the marketplace's dashboard. It is a separate React SPA against a separate API, shipped as `@spree/seller-dashboard`.
+
+It shares its foundations with the admin dashboard: components from `@spree/dashboard-ui`, framework pieces (registries, providers, hooks) from `@spree/dashboard-core`. The two panels therefore stay visually and behaviourally consistent, and anything you learn customizing one applies to the other.
+
+### Scaffold and run it
+
+The panel ships as a shell you render from a thin host app that you own. Two ways to get one:
+
+<CodeGroup>
+
+```bash New project
+npx create-spree-app my-marketplace
+# Both panels are scaffolded automatically — no prompt to answer
+```
+
+```bash Existing project
+npx spree add seller-dashboard
+```
+
+</CodeGroup>
+
+A new project always gets both admin SPAs, so the starter's Docker image bakes both in; a store that never invites a seller simply leaves `/sellers` unvisited. Either way the host app lands at `apps/seller-dashboard/` with its own `package.json`, Vite config and a `src/plugins.ts` for your customizations. Then:
+
+```bash
+cd apps/seller-dashboard && pnpm dev
+```
+
+It serves on port **5174** (the admin dashboard is on 5173, so both run side by side).
+
+`.env.local` holds one setting — the Rails server the dev proxy forwards `/api` to:
+
+```bash apps/seller-dashboard/.env.local
+VITE_API_PROXY_TARGET=http://localhost:3000
+```
+
+<Warning>
+Do **not** set `VITE_SPREE_API_URL` in development. It switches the SDK to absolute cross-origin URLs and bypasses the proxy, which breaks the seller refresh-token cookie: the cookie rides under `SameSite=Lax`, and that only works while the panel is same-origin with the API.
+</Warning>
+
+### What sellers get out of the box
+
+| Area | Pages |
+|---|---|
+| Onboarding | The checklist, submissions, payout-account link |
+| Products | List, create, edit, submit for review |
+| Orders | List, detail, fulfillments, deliveries, labels, returns, exchanges, claims |
+| Money | Earnings, payouts |
+| Profile | Public profile, tax identifiers |
+| Settings | Team, delivery methods, package types, stock locations, policies |
+| Auth | Login, forgot/reset password, invitation acceptance |
+
+Sellers cannot see other sellers, the marketplace's own catalog, or anything belonging to the store at large.
+
+### Deploying it
+
+By default the seller panel, same as dashboard is build with Spree docker image and is server via `/sellers` path. You can also deploy it as a static bundle on a CDN or static host. The entire process is baked into the default `Dockerfile` which you get when you scaffold a new project with `create-spree-app`. The `spree build --production` command builds both panels and bakes them into the image, so you can run it as-is. This also automatically resolves CORS issues, since the panel is served from the same origin as the API.
+
+### Customizing it
+
+`src/plugins.ts` in your host app is where customizations are registered — the same `defineDashboardPlugin` API the admin dashboard uses, because both panels sit on `@spree/dashboard-core`.
+
+```tsx apps/seller-dashboard/src/plugins.ts
+import { defineDashboardPlugin } from '@spree/seller-dashboard'
+import { PayoutsPage } from './pages/payouts'
+
+defineDashboardPlugin({
+ nav: {
+ add: [{ key: 'payouts', label: 'Payouts', path: '/payouts', position: 300 }],
+ remove: ['team'],
+ },
+ slots: {
+ 'seller.team.after': [{ id: 'audit', component: TeamAuditCard }],
+ },
+})
+```
+
+Import everything from `@spree/seller-dashboard` — it re-exports both the framework and the design system, so you never have to work out which package an export lives in.
+
+| What you want | How |
+|---|---|
+| Add or remove a nav entry | `nav.add` / `nav.remove` in `defineDashboardPlugin` |
+| Inject a widget into a built-in page | A [slot](/developer/dashboard/customization/slots) |
+| Add a page | A [route](/developer/dashboard/customization/routes) plus a nav entry |
+| Add a table column | The [table registry](/developer/dashboard/customization/tables) |
+| Change wording | [Translations](/developer/dashboard/customization/translations) merged with `i18n.addResourceBundle` |
+| Install a third-party plugin | `npm add <plugin>` and restart — the Vite plugin picks it up from your dependencies |
+
+The seller panel currently exposes just two slots, both on its team page: `seller.team.actions` and `seller.team.after`. (`seller.form_main` and `seller.form_sidebar` sound related but belong to the *admin* dashboard's seller detail page — they are for the operator's view of a seller, not the seller's own.) See the [slots catalog](/developer/dashboard/slots-catalog) for their contexts. To put a widget anywhere else in the panel, add a route rather than looking for a slot that is not there yet.
+
+<Note>
+**White-labelling is theming and copy, not a branding config object.** There is no logo or brand-name setting to fill in. You restyle by owning the Tailwind layer in your host app, and you re-word by overriding translation keys. Both are real customization paths — there is simply no shortcut that skips them.
+</Note>
+
+<Warning>
+**`@spree/seller-dashboard` ships English only.** The admin dashboard ships several locales; the seller panel ships `en.json` and nothing else. A marketplace serving sellers in another language supplies that locale itself, through `i18n.addResourceBundle` in the host app.
+</Warning>
+
+**Read more:** [Dashboard overview](/developer/dashboard/overview) for the package split and both customization paths, [Dashboard customization](/developer/dashboard/customization/quickstart) for the registries in detail, and [Plugins](/developer/dashboard/plugins/overview) for shipping a redistributable one.
+
+## Build against the Seller API
+
+If you are not using the shipped panel — a native seller app, an ERP integration, a bespoke portal — the Seller API is the surface, and `@spree/seller-sdk` is the client.
+
+**Every request is scoped to the seller making it. No endpoint takes a seller ID.** That is the security property worth relying on: a seller cannot ask for another seller's data, because there is nowhere in the request to name one.
+
+```bash
+npm install @spree/seller-sdk
+```
+
+```typescript
+import { createSellerClient } from '@spree/seller-sdk'
+
+const sellerClient = createSellerClient({ baseUrl: 'https://marketplace.example.com' })
+
+const tokens = await sellerClient.auth.login({
+ email: '[email protected]',
+ password: '…',
+})
+sellerClient.setToken(tokens.access_token)
+
+// A user who runs several sellers picks which one they are acting as
+sellerClient.setSeller('sel_xxx')
+```
+
+Authentication is JWT only. **There is deliberately no secret-key equivalent**: a key that acts as a seller without a seller signing in is exactly what the Seller API's design exists to prevent. Sign-in fails for a store staff member who runs no seller, even though staff share the same user class.
+
+The chosen seller travels as `X-Spree-Seller-Id`. The store is derived from the seller server-side and never sent alongside, so no header a client can set widens what it reaches.
+
+### What the client covers
+
+| Namespace | Notable methods |
+|---|---|
+| `auth` | `login`, `refresh`, `logout`, `providers`, `lookupInvitation`, `acceptInvitation`, `requestPasswordReset` |
+| `onboarding` | `get`, `submitForReview`, `payoutAccount` |
+| `requirementSubmissions` | `create` — create only; the seller submits again rather than editing |
+| `profile`, `taxIdentifiers`, `policies` | The seller's own identity and legal documents |
+| `team`, `invitations` | The seller hires and manages their own staff |
+| `products` | Full CRUD plus `submit`, `draft`, `archive` and their bulk equivalents |
+| `orders` | List and detail, plus `cancel`, `address`, nested `fulfillments`, `deliveries`, `labels`, `returns`, `exchanges`, `claims`, `notes` |
+| `balances`, `transfers`, `payouts` | Read-only — written by fulfilment and the sweep, never by the seller |
+| `deliveryMethods`, `packageTypes`, `stockLocations` | How and from where they ship |
+| `imports`, `exports`, `directUploads` | Bulk listing by CSV, and CSV of what they sold |
+| `productTypes`, `deliveryProfiles`, `deliveryZones`, `returnReasons`, `claimReasons`, `trackingCarriers`, `countries` | Read-only marketplace vocabulary a seller picks from |
+
+Two asymmetries are worth noticing, because both are deliberate:
+
+- **A seller cannot set a product's status.** They call `submit`, and the marketplace decides. Bulk moves exist only for the transitions a seller may make alone.
+- **A seller cannot mark an order delivered.** That a parcel arrived is the buyer's word, not the sender's, so confirming receipt stays with the operator and the carrier feed.
+
+What a seller's staff may do within all this is governed by [roles the seller owns](/developer/core-concepts/staff-roles) — the same permission system as the back office, with a narrower set of keys, so a seller role can never reach store settings.
+
+**Read more:** [Seller API introduction](/api-reference/seller-api/introduction), [Seller API authentication](/api-reference/seller-api/authentication), [Seller API errors](/api-reference/seller-api/errors).
+
+## Related
+
+- [Sellers](/developer/core-concepts/sellers) — the full model: lifecycle, ownership, order splitting, ledger
+- [Commissions](/developer/core-concepts/commissions) — rates, rules, precedence, currency handling, commission tax
+- [Products](/developer/core-concepts/products#seller-submissions) — the listing review flow in detail
+- [Orders](/developer/core-concepts/orders) — orders and their statuses
+- [Customers](/developer/core-concepts/customers) — who buys, across every seller
+- [Delivery setup](/developer/core-concepts/delivery-setup#on-a-marketplace) — how a seller's goods ship and what they ship in
+- [Staff & Roles](/developer/core-concepts/staff-roles) — how seller teams are governed
+- [Seller payouts](/developer/providers/payouts) — writing your own payout provider
+- [Stripe Connect](/integrations/payments/stripe-connect) — the shipped payout provider
+- [Seller API](/api-reference/seller-api/introduction) — the full endpoint reference
+- [Dashboard overview](/developer/dashboard/overview) — customizing either panel
+- [Sellers (operator guide)](/user/sellers/sellers) — running a marketplace from the dashboard
+- [Seller requirements (operator guide)](/user/settings/seller-requirements) — building the checklist
+- [Payouts settings (operator guide)](/user/settings/marketplace) — who pays sellers and how often
diff --git a/docs/developer/storefront/nextjs/deployment.mdx b/docs/developer/storefront/nextjs/deployment.mdx
index 8ee2de08b8..8f9aa53d47 100644
--- a/docs/developer/storefront/nextjs/deployment.mdx
+++ b/docs/developer/storefront/nextjs/deployment.mdx
@@ -10,7 +10,7 @@ At minimum, set `SPREE_API_URL` and `SPREE_PUBLISHABLE_KEY` in your hosting plat
## Production Build
```bash
-npm run build
+pnpm build
npm start
```
@@ -104,8 +104,8 @@ For any platform that supports Node.js (Render, Railway, Fly.io, AWS, etc.):
1. Install dependencies and build:
```bash
-npm ci
-npm run build
+pnpm install --frozen-lockfile
+pnpm build
```
2. Start the production server:
@@ -132,13 +132,15 @@ jobs:
steps:
- uses: actions/checkout@v4
+ - uses: pnpm/action-setup@v4
+
- uses: actions/setup-node@v4
with:
node-version: 20
- cache: npm
+ cache: pnpm
- - run: npm ci
- - run: npm run build
+ - run: pnpm install --frozen-lockfile
+ - run: pnpm build
# Add your deployment step here
# Example for Vercel:
diff --git a/docs/developer/storefront/nextjs/emails.mdx b/docs/developer/storefront/nextjs/emails.mdx
index a54e384b24..172561357d 100644
--- a/docs/developer/storefront/nextjs/emails.mdx
+++ b/docs/developer/storefront/nextjs/emails.mdx
@@ -28,7 +28,7 @@ Customize a template by editing its file directly — they use `@react-email/com
Run the storefront in development and open [http://localhost:3001/dev/emails](http://localhost:3001/dev/emails):
```bash
-npm run dev
+pnpm dev
```
Each template renders with sample data via `@react-email/render`. The route is gated to non-production environments.
diff --git a/docs/developer/storefront/nextjs/quickstart.mdx b/docs/developer/storefront/nextjs/quickstart.mdx
index fbe98e9dee..b12676d8e3 100644
--- a/docs/developer/storefront/nextjs/quickstart.mdx
+++ b/docs/developer/storefront/nextjs/quickstart.mdx
@@ -51,7 +51,7 @@ To run the storefront on its own — against an existing Spree backend, or to wo
```bash
git clone https://github.com/spree/storefront.git
cd storefront
-npm install
+pnpm install
```
Then follow [Configuration](#configuration) to point it at your Spree API. If you plan to customize and track upstream changes, [fork first](/developer/storefront/nextjs/customization#tracking-upstream-updates).
@@ -80,7 +80,7 @@ See [Deployment](/developer/storefront/nextjs/deployment) for all optional envir
## Development
```bash
-npm run dev
+pnpm dev
```
Open [http://localhost:3001](http://localhost:3001) in your browser.
@@ -92,7 +92,7 @@ Open [http://localhost:3001](http://localhost:3001) in your browser.
## Production Build
```bash
-npm run build
+pnpm build
npm start
```
diff --git a/docs/developer/storefront/nextjs/testing.mdx b/docs/developer/storefront/nextjs/testing.mdx
index 84c0f81b04..e4fa12a260 100644
--- a/docs/developer/storefront/nextjs/testing.mdx
+++ b/docs/developer/storefront/nextjs/testing.mdx
@@ -9,12 +9,12 @@ The storefront ships two test layers: fast unit/integration tests with Vitest, a
```bash
npm test # one-shot
-npm run test:watch # watch mode
+pnpm test:watch # watch mode
```
## End-to-end (Playwright)
-The E2E suite drives a browser against a real Spree backend. `npm run e2e:up` boots the backend — Postgres, Redis, and the official `ghcr.io/spree/spree:latest` image from `e2e-backend/docker-compose.yml` — then seeds it and mints an API key through the official [`@spree/cli`](/developer/cli/quickstart) (`spree seed`, `spree sample-data`, `spree api-key create`), installed as a dev dependency. No `create-spree-app` setup is required.
+The E2E suite drives a browser against a real Spree backend. `pnpm e2e:up` boots the backend — Postgres, Redis, and the official `ghcr.io/spree/spree:latest` image from `e2e-backend/docker-compose.yml` — then seeds it and mints an API key through the official [`@spree/cli`](/developer/cli/quickstart) (`spree seed`, `spree sample-data`, `spree api-key create`), installed as a dev dependency. No `create-spree-app` setup is required.
```bash
# 1. Export a Stripe test-mode key pair from your own Stripe sandbox.
@@ -26,16 +26,16 @@ export STRIPE_SECRET_KEY=sk_test_…
# 2. Boot Spree + Postgres + Redis, seed sample data, register a Stripe
# payment gateway, mint a publishable key, and write .env.e2e.
-npm run e2e:up
+pnpm e2e:up
# 3. Run the suite. Playwright boots `next dev` against .env.e2e.
-npm run test:e2e
+pnpm test:e2e
# Optional: interactive UI mode.
-npm run test:e2e:ui
+pnpm test:e2e:ui
# Tear everything down.
-npm run e2e:down
+pnpm e2e:down
```
The checkout test pays with card `4242 4242 4242 4242` through Stripe's [test mode](https://docs.stripe.com/keys). PaymentIntents land in whichever Stripe test account owns the keys you exported.
@@ -57,8 +57,8 @@ The E2E stack reads a `SPREE_IMAGE` env var and falls back to the stock image wh
If you already publish a customized Spree image:
```bash
-SPREE_IMAGE=ghcr.io/your-org/your-spree:latest npm run e2e:up
-npm run test:e2e
+SPREE_IMAGE=ghcr.io/your-org/your-spree:latest pnpm e2e:up
+pnpm test:e2e
```
### A `create-spree-app` project's backend
@@ -71,9 +71,9 @@ docker build -t project-spree:e2e ./backend
# From apps/storefront — run E2E against it
cd apps/storefront
-SPREE_IMAGE=project-spree:e2e npm run e2e:up
-npm run test:e2e
-npm run e2e:down
+SPREE_IMAGE=project-spree:e2e pnpm e2e:up
+pnpm test:e2e
+pnpm e2e:down
```
<Note>
@@ -82,4 +82,4 @@ npm run e2e:down
### Interactive / manual
-To click through the storefront against a running backend (no E2E harness), point it there directly: set `SPREE_API_URL` and `SPREE_PUBLISHABLE_KEY` in `.env.local` (see [Environment Variables](/developer/storefront/nextjs/environment-variables)) and run `npm run dev`.
+To click through the storefront against a running backend (no E2E harness), point it there directly: set `SPREE_API_URL` and `SPREE_PUBLISHABLE_KEY` in `.env.local` (see [Environment Variables](/developer/storefront/nextjs/environment-variables)) and run `pnpm dev`.
diff --git a/docs/developer/storefront/nextjs/wallet-payments.mdx b/docs/developer/storefront/nextjs/wallet-payments.mdx
index 7f17910346..cb83257412 100644
--- a/docs/developer/storefront/nextjs/wallet-payments.mdx
+++ b/docs/developer/storefront/nextjs/wallet-payments.mdx
@@ -16,7 +16,7 @@ Apple Pay and Google Pay require HTTPS **and a publicly-reachable URL** — Stri
2. Start the dev server normally (HTTP on port 3001):
```bash
- npm run dev
+ pnpm dev
```
3. In a second terminal, expose it through a quick tunnel:
diff --git a/docs/developer/upgrades/5.6-to-6.0.mdx b/docs/developer/upgrades/5.6-to-6.0.mdx
index 78b67e4d26..9bfc4b6e2f 100644
--- a/docs/developer/upgrades/5.6-to-6.0.mdx
+++ b/docs/developer/upgrades/5.6-to-6.0.mdx
@@ -1,7 +1,6 @@
---
title: Upgrading to Spree 6.0
description: Guide to upgrading a Spree 5.6 application to Spree 6.0
-hidden: true
---
<Info>
diff --git a/docs/docs.json b/docs/docs.json
index c5a261f902..03457a4ff5 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -721,6 +721,7 @@
"developer/dashboard/customization/slots",
"developer/dashboard/customization/tables",
"developer/dashboard/customization/translations",
+ "developer/dashboard/customization/theming",
"developer/dashboard/customization/permissions",
"developer/dashboard/customization/backend"
]
@@ -952,7 +953,13 @@
"group": "Upgrading",
"pages": [
"developer/upgrades/quickstart",
- "developer/upgrades/5.6-to-6.0"
+ "developer/upgrades/5.6-to-6.0",
+ "v5/developer/upgrades/5.5-to-5.6",
+ "v5/developer/upgrades/5.4-to-5.5",
+ "v5/developer/upgrades/5.3-to-5.4",
+ "v5/developer/upgrades/5.2-to-5.3",
+ "v5/developer/upgrades/5.1-to-5.2",
+ "v5/developer/upgrades/5.0-to-5.1"
]
},
{
@@ -2301,6 +2308,7 @@
"developer/dashboard/customization/slots",
"developer/dashboard/customization/tables",
"developer/dashboard/customization/translations",
+ "developer/dashboard/customization/theming",
"developer/dashboard/customization/permissions",
"developer/dashboard/customization/backend"
]
diff --git a/docs/v5/developer/upgrades/5.6-to-6.0.mdx b/docs/v5/developer/upgrades/5.6-to-6.0.mdx
deleted file mode 100644
index 39b8f7a60d..0000000000
--- a/docs/v5/developer/upgrades/5.6-to-6.0.mdx
+++ /dev/null
@@ -1,653 +0,0 @@
----
-title: Upgrading to Spree 6.0
-description: Guide to upgrading a Spree 5.6 application to Spree 6.0
-hidden: true
-canonical: "https://spreecommerce.org/docs/developer/upgrades/5.6-to-6.0"
----
-
-<Info>
- Before proceeding to upgrade, please ensure you're at [Spree 5.6](/v5/developer/upgrades/5.5-to-5.6). Spree 6.0 requires **Rails 8.1** and is the designated breaking-change window for the platform — read the behavioral changes section even if your upgrade runs clean.
-</Info>
-
-Spree 6.0 is a major release. The headline changes:
-
-- **Cart and Order are separate models.** `Spree::Cart` owns shopping and checkout; completing checkout copies the cart into an immutable `Spree::Order`. The order state machine is gone.
-- **Checkout has no server-side state machine.** Steps are advisory metadata for your frontend; the backend enforces exactly one hard gate — completion.
-- **Adjustments are typed rows.** The polymorphic `Spree::Adjustment` is replaced by `Spree::TaxLine`, `Spree::Discount` and `Spree::Fee`.
-- **Master Variant** is gone, replaced by a `default_variant_id` foreign key on `Spree::Product`. There's no hidden/dummy Variant created now, the default variant is a real Variant with its own SKU, price, stock, etc.
-- **Fulfillment vocabulary.** `Shipment` → `Fulfillment`, `ShippingMethod` → `DeliveryMethod`, `Zone` → `DeliveryZone`, with a pluggable `FulfillmentProvider` strategy.
-- **Two-tier services.** Plain services in `app/services`, plus `Spree::Workflow` classes in `app/workflows` for the curated multi-step flows (completion, cancellation, recalculation) — with named steps, instrumentation and extension hooks.
-
-The upgrade is completed in four steps:
-
-1. **Update the Ruby gems**
-2. **Run database migrations**
-3. **Run data backfills** — convert your existing records into the new schema
-4. **Review behavioral changes** — this release changes runtime behavior, not just schema
-
-## How to upgrade
-
-<CodeGroup>
-
-```bash Spree CLI (Docker)
-spree upgrade
-```
-
-```bash Without Spree CLI
-# cd backend if you're in the monorepo root
-bundle update
-bundle exec rake spree:install:migrations && bin/rails db:migrate
-bundle exec rake spree:upgrade
-```
-
-</CodeGroup>
-
-Skipping versions and re-running are both safe — `bundle exec rake spree:upgrade` figures out what still needs to happen and does nothing on data that's already migrated.
-
-## What the upgrade does
-
-Reference material — the data backfills `bundle exec rake spree:upgrade` executes. Every task is idempotent.
-
-### Convert incomplete orders into carts
-
-```bash
-bundle exec rake spree:migrate_incomplete_orders_to_carts
-```
-
-Every order that never completed and was never canceled becomes a `Spree::Cart` with the same token, so in-flight guest and customer checkouts survive the deploy. The cart re-owns the order's line items, fulfillments, payments, payment sessions, reservations and coupon codes; the hollow order row is deleted. Completed and canceled orders are untouched. Orders holding payment sessions convert last, so an interrupted run leaves the riskiest rows for the retry.
-
-### Convert legacy adjustments into typed rows
-
-```bash
-bundle exec rake spree:migrate_adjustments_to_typed_rows
-```
-
-Rebuilds `spree_adjustments` into `Spree::TaxLine`, `Spree::Discount` and `Spree::Fee` rows. Orders whose typed sums do not reconcile with the stored totals are left untouched and flagged (`private_metadata['typed_adjustments_frozen']`) for manual review instead of silently changing money.
-
-### Backfill fulfillment and delivery naming
-
-```bash
-bundle exec rake spree:migrate_shipping_to_delivery
-bundle exec rake spree:migrate_zones_to_delivery_zones
-bundle exec rake spree:migrate_calculator_bounds_to_delivery_method_rules
-```
-
-Moves stored strings, statuses and class names to the fulfillment/delivery vocabulary, converts delivery-referenced `Spree::Zone` records into `Spree::DeliveryZone` with typed members, and converts FlatRate calculator eligibility bounds into `Spree::DeliveryMethodRule` records.
-
-### Remove master variants
-
-```bash
-bundle exec rake spree:remove_master_variant
-```
-
-Products now carry a `default_variant_id` foreign key; `is_master` is gone from the models. (The physical column drop lands in 6.1.)
-
-### Categories and collections
-
-```bash
-bundle exec rake spree:migrate_taxons_to_categories_and_collections
-```
-
-Taxons become `Spree::Category` (hierarchy) and automatic taxons become `Spree::Collection` (flat, rule-based). `Spree::Taxon` remains as an alias for one release.
-
-### Move rich text out of Action Text
-
-```bash
-bundle exec rake spree:migrate_rich_text_to_columns
-```
-
-Category and collection descriptions, policy bodies, and order and customer internal notes move from `action_text_rich_texts` into text columns on their own tables. Per-locale rows land in the model's translation table.
-
-Run this **after** two earlier steps, both load-bearing: the categories step re-points the rows from `Spree::Taxon` to `Spree::Category` so this one can still find them, and the customers step populates `spree_customers` — a note is copied onto the customer row it belongs to, so running before those rows exist would treat every legacy customer note as orphaned and skip it for good. Following the manifest order handles this for you.
-
-Content is sanitized on the way in, and **the 6.0 allowlist is much narrower than 5.6's**: it permits only what the dashboard's editor emits — paragraphs, headings, `strong`/`em`/`s`/`u`/`code`, `pre`, `blockquote`, lists, `hr`, `br` and links. Tables, images, `div`/`span`, inline `style` and arbitrary `class` attributes are no longer permitted. Text inside a stripped tag survives; its formatting does not. The exceptions are `script` and `style`, which are removed along with their contents — a script body would otherwise reappear as visible text.
-
-If your descriptions rely on richer markup, permit it in an initializer **before** running the task and before saving anything under 6.0:
-
-```ruby
-# config/initializers/spree.rb
-Spree::RichTextSanitizer.allowed_tags += %w[table thead tbody tr th td img]
-Spree::RichTextSanitizer.allowed_attributes += %w[src alt colspan rowspan]
-```
-
-The Action Text rows are left in place as a rollback path and are dropped with the tables in 6.1.
-
-Once this has run, **Spree no longer loads Action Text.** `spree_core` dropped `require 'action_text/engine'` — along with `action_cable/engine`, which nothing in Spree used — and a fresh install no longer creates the tables. The rake task requires Action Text itself, so the upgrade works either way. If your own code uses `has_rich_text`, Action Text view helpers, or Action Cable, require what you need in `config/application.rb` (apps generated from the Spree starter already do):
-
-```ruby
-require 'action_text/engine'
-require 'action_cable/engine'
-```
-
-### Backfill order coupon codes
-
-```bash
-bundle exec rake spree:backfill_order_coupon_codes
-```
-
-`spree_orders` gains a `coupon_code` column (parity with carts). Historical placed orders applied coupons only through the promotion join tables — this fills the column from the attached coupon-code record (or the applied single-code promotion) so admin filtering and the serializer answer consistently for old orders.
-
-### Markets on orders
-
-```bash
-bundle exec rake spree:backfill_order_markets
-```
-
-Orders missing a market get the store default — `market` is required on carts and orders in 6.0.
-
-## The Cart/Order split
-
-The single biggest change. What used to be one `Spree::Order` living through checkout and beyond is now two models:
-
-- **`Spree::Cart`** (`spree_carts`, prefixed IDs `cart_...`) owns the shopping and checkout phase: line items, addresses, payments-in-progress, delivery proposals, promotions, stock reservations. Carts have **no status column** — `completed_at` is the only lifecycle marker.
-- **`Spree::Order`** is created *by completion* — the cart is copied into it (line items, fulfillments, addresses, typed money rows — **copies, never shared rows**). Orders carry `status` (`draft` / `placed` / `canceled`) and are money-frozen once placed.
-
-Consequences to review:
-
-- **Completed carts are read-only.** The cart is retained after completion (abandonment analytics, idempotent replay) but rejects every write. Post-checkout life belongs to the order.
-- **Completion is idempotent.** `Spree::Carts::Complete` guards with a unique `spree_orders.cart_id` index and a `completing_at` lock: a double-clicked Place Order returns the same order, a crashed completion replays safely, and a pre-capture payment failure rolls the draft order back and re-points payments to the cart.
-- **The guest token carries over** from cart to order, so confirmation pages keep working with the credential the guest already holds.
-- **Dual concrete FKs, not polymorphism.** Records owned by either side (`LineItem`, `Fulfillment`, `TaxLine`, `Discount`, `Fee`, `Payment`, `StockReservation`) carry nullable `cart_id` + `order_id` with an exactly-one rule and an `#owner` method. Code that assumed `line_item.order` is always present must read `line_item.owner`.
-- **Shared model surface** lives in `Spree::Purchase::*` concerns (addresses, taxation, store credits, gift cards, digital items, payment processing, market/channel/currency/locale resolution) — included by both Cart and Order. Decorators targeting `Spree::Order` methods that moved should decorate the concern or the new owner.
-
-## Checkout without a state machine
-
-`Spree::Order` no longer has a `state` column, a state machine, or the `checkout_flow` DSL. If your app customized checkout with `checkout_flow`, `go_to_state`, `insert_checkout_step`, `remove_checkout_step` or `remove_transition` — those APIs are gone (not deprecated: the machine they configured no longer exists).
-
-The replacement model:
-
-- **Steps are advisory.** `cart.checkout_steps`, `current_checkout_step` and `completed_checkout_steps` are *derived* from cart data — there is no stored step and no server-side sequencing. Clients may write any checkout field in any order. "Steps" are a grouping label telling your frontend which page an unmet requirement belongs to.
-- **One hard gate.** `Spree::Carts::Complete` is the only place checkout is enforced. It validates the full requirement battery (line items, email, addresses, delivery selection, payment coverage, per-item stock, discontinued products, guest policy) and returns structured `{ step, field, code, message }` errors.
-- **`Spree::Checkout::Registry` is the extension surface.** One declaration serves both the advisory feed and the completion gate:
-
-```ruby
-# config/initializers/spree.rb
-Rails.application.config.to_prepare do
- Spree::Checkout::Registry.add_requirement(
- step: :payment,
- field: :po_number,
- message: 'PO number is required',
- satisfied: ->(cart) { cart.metadata['po_number'].present? },
- applicable: ->(cart) { cart.customer.present? }
- )
-end
-```
-
- The requirement appears in the Cart API's `requirements` array (so a storefront rendering the feed generically needs zero changes) *and* blocks completion. `register_step` adds whole steps (spliced into `checkout_steps` at `before:`/`after:` anchors); built-in steps are customized through `Registry.base_steps` — an ordered `{ name => applicability }` hash you can mutate directly (`base_steps.delete('confirm')`).
-- **The API `requirements` array now carries a stable `code`** on every entry (`email_required`, `out_of_stock`, `guest_checkout_not_allowed`, ...). Additive change — existing consumers keep working.
-- **The delivery requirement is keyed `delivery_method`, not `shipping_method`.** Its entry is now `{ step: 'delivery', field: 'delivery_method', code: 'delivery_method_required' }`. A storefront that renders the feed generically needs no change; one that keys off the field or code to highlight a specific input must switch both tokens. The `Spree.t('checkout_requirements.shipping_method_required')` translation key was renamed to `checkout_requirements.delivery_method_required` — override it under the new key.
-- **"Logic between steps" has no backend home by design.** Side effects hang off data writes (workflow hooks such as `Carts::Complete`'s `before_finalize` and `Carts::AddItem`'s `after_item_added`) and events (`cart.updated`, `order.placed`) — not step transitions.
-
-## Statuses: derived, then persisted
-
-`payment_state` and `shipment_state` machine columns are replaced by `payment_status` and `fulfillment_status` — stored, indexed, and recomputed from payment/refund/fulfillment records by a single writer, `Spree::Orders::UpdateStatuses`. The legacy names remain as read aliases for one release.
-
-Behavior to review:
-
-- Nothing else writes these columns. If your code assigned `order.payment_state = 'paid'`, replace it with the underlying records (payments/refunds) and let the recompute derive.
-- The `payment_status` domain gains `overcharged` and `voided`; `fulfillment_status` includes `backorder`. Money comparisons are quantized to currency precision and refunds are netted before comparing.
-- A completed payment updates **only the payment side of the ledger** (`payment_total` + statuses). It never re-sums item or adjustment money.
-- Fulfillment is a fact: a fulfilled fulfillment is never downgraded by later payment-state changes.
-
-## Recalculation on write
-
-Transition-triggered recalculation is gone with the machine. Instead:
-
-- **`Spree::Carts::RecalculateTotals`** is the single totals seam: money inputs, typed-row regeneration (promotions via the winner-only adjuster, tax via `Spree.tax_provider`), folding and one persist. It runs on the writes that matter — item changes, address/market changes (which also re-price items and rebuild delivery proposals) — not on step transitions.
-- Promotion eligibility is evaluated against **current** totals in the same recalculation — a cart crossing a coupon threshold gets the discount on that recalculation, not the next one.
-- **Completed orders are money-frozen.** Typed rows are never regenerated post-placement; recalculation only re-sums them. Post-placement money edits go through the explicit admin services (`Orders::Discounts::*`, `Orders::Fees::*`), which write rows and re-sum.
-- `Spree::OrderUpdater` and `Spree::CartUpdater` remain as deprecated shells — every method warns and runs the full recalculation. Removed in 6.1.
-
-## Completion, in one workflow
-
-`Spree::Orders::Complete` is the one home for everything that happens when an order becomes placed — payment processing (when needed), fulfillment finalization, placement, coupon/gift-card redemption, digital auto-fulfillment, statuses, and the `order.placed` event. Checkout reaches it through `Carts::Complete`; admin/B2B draft completion calls it directly (`payment_pending: true` places without processing payments for invoice-later flows).
-
-- **`Order#finalize!` is deprecated** (removed in 6.1) and delegates to the workflow. Behavioral change: finalizing an **already-completed order is now a no-op** — the workflow halts idempotently instead of re-running side effects.
-- **Completion side effects moved out of the model.** Newsletter subscription, checkout account creation and risk assessment run in the synchronous `Spree::OrderPlacedSubscriber` on the `order.placed` event. Decorators that patched `finalize!` should become event subscribers or `before_finalize` hook handlers.
-- **`order.placed` is the completion event.** `order.completed` still fires as a deprecated alias for one release (webhook consumers should migrate; wildcard subscribers can dedupe on the `deprecated_alias_of` metadata marker).
-- `Order.register_update_hook` no longer runs during completion.
-
-## Addresses
-
-The full address surface is shared by Cart and Order through `Spree::Purchase::Addresses`, which means cart checkout regains behavior that 5.x orders had:
-
-- Address writes **deduplicate** against the customer's address book and **promote** checkout addresses to the customer's defaults (quick-checkout wallet addresses excluded).
-- `ship_address_id=` / `bill_address_id=` are **ownership-guarded**: an address not owned by the record's customer resolves to `nil`.
-- A signed-in customer entering checkout gets blank address slots **auto-filled from their saved defaults**.
-- **`use_billing` is deprecated** (removed in 6.1): the shipping address is canonical — use `use_shipping` to copy ship → bill.
-
-## Returns, exchanges and claims
-
-The `ReturnAuthorization → CustomerReturn → Reimbursement` chain is replaced by three first-class records that each belong directly to an order: **`Spree::Return`** (items come back, money goes back), **`Spree::Exchange`** (items come back, different items go out), and **`Spree::Claim`** (something went wrong in delivery — no items required back).
-
-The old classes are **gone with no bridge**, so calls raise `NameError`:
-
-| Removed | Use instead |
-|---|---|
-| `Spree::ReturnAuthorization` | `Spree::Return` or `Spree::Exchange` |
-| `Spree::CustomerReturn` | `Spree::Return` — receiving is a status on the same record |
-| `Spree::Reimbursement`, `Spree::ReimbursementType` | `Spree::Returns::Refund` (a workflow, not a model) |
-| `Spree::ReturnItem` | `Spree::ReturnLineItem` / `Spree::ExchangeLineItem` / `Spree::ClaimLineItem` |
-| `Spree::ReturnItem::EligibilityValidator::*` | the `validate` hook — see below |
-| `Spree::ReturnAuthorizationReason` | `Spree::ReturnReason` (constant alias kept until 6.1, with a warning) |
-
-<Note>
- **The legacy tables are not dropped.** They stay through 6.1 as the data migration's source and rollback path. Run `spree:upgrade:migrate_returns` to copy the history onto the new models — it's resumable, and it aborts if any row fails so an upgrade can't silently proceed on partial history.
-</Note>
-
-### No state machines
-
-New records carry a plain `status` string with an inclusion validation. Every transition is a workflow — `Spree::Returns::Approve`, `Returns::Receive`, `Returns::Refund`, `Exchanges::Fulfill`, `Claims::Resolve`, and so on. **Nothing happens in a model callback or transition callback**, so code that hooked `before_transition` on the old machines has no equivalent; move it to a workflow hook or an event subscriber.
-
-Statuses are extensible but additive only, through `Spree::HasStatus`:
-
-```ruby
-Spree::Return.add_status('inspecting', after: 'received')
-```
-
-### Eligibility is a hook, not a validator chain
-
-`ReturnItem::EligibilityValidator::Default` chained five validators. Only one was policy; the rest were invariants, so they moved to different places:
-
-| Old validator | Where the rule lives now |
-|---|---|
-| `TimeSincePurchase` | `Spree::Returns::EligibilityValidator`, registered on the `validate` hook |
-| `OrderCompleted` | inline guard in `Returns::Create` |
-| `InventoryShipped` | structural — only fulfillment items can be returned, and quantities are checked against what shipped |
-| `NoReimbursements` | quantity math — prior return line items are subtracted, so units can't come back twice |
-| `RMARequired` | gone: the `Return` **is** the request, so there is nothing to require |
-
-Core ships exactly one policy rule — a return window read from `market.preferred_return_window_days` (default 30), per market because return windows are a regional legal matter. **Staff can override it**: when `created_by` is present the window is advisory, so a supervisor can accept a late return without a code change.
-
-<Warning>
- Four returns settings are **deprecated and read by nothing** — they still exist so applications don't crash at boot, but they have no effect and now emit a deprecation warning when read or written:
-
- | Deprecated setting | Use instead |
- |---|---|
- | `return_eligibility_number_of_days` | `preferred_return_window_days` on `Spree::Market`, or a `returns.create.validate` hook |
- | `restock_inventory` | `Spree::ReturnLineItem#resellable`, decided per line item at receiving |
- | `expedited_exchanges`, `expedited_exchanges_days_window` | `Spree::Exchange` and the `Exchanges::Fulfill` workflow |
-</Warning>
-
-Replace it by swapping the handler:
-
-```ruby
-Spree.hooks.unregister('returns.create.validate', 'Spree::Returns::EligibilityValidator')
-Spree.hooks.register('returns.create.validate', 'MyStore::ReturnPolicy')
-```
-
-A handler receives the workflow (so it can read `order`, `items`, `created_by`, `order.market`) and calls `workflow.reject!(message)` to veto. Every one of the fifteen transitions has a leading `validate` hook, so the same seam gates approving, receiving and refunding.
-
-<Warning>
- `requires_manual_intervention?` has no equivalent. The old validators could mark an item eligible-but-flagged for manual review; a handler now either accepts or vetoes. If you relied on that middle state, model it explicitly — an added status, or a metafield your handler sets.
-</Warning>
-
-### Other behavioral changes
-
-- **`Return#refunded_total` counts store credits.** Store credit is a separate ledger and never creates a `Spree::Refund` row, so the old sum reported zero for a store-credit refund.
-- **`Order#outstanding_balance` dropped its reimbursement term** rather than replacing it — refunds already net out of `payment_total`, so that term was double-counting.
-- **The reimbursement email is now `Spree::ReturnMailer#refunded_email`**, sent on `return.refunded` (in the optional `spree_emails` gem, like the other transactional mail).
-- **`Refund#originator`** points at the new records.
-- Events are `return.requested` / `.approved` / `.received` / `.refunded` / `.canceled`, and the matching `exchange.*` and `claim.*` families.
-
-## Dependency injection changes
-
-6.0 introduces `*_workflow` keys for the flows that graduated to the workflow tier. The old `*_service` keys **stay settable and readable one release so applications don't crash at boot — but a legacy write is stashed, not applied**: a class written against the old service contract is not interchangeable with the workflow the new call sites consume. Reads return your stashed class (legacy code calling its own override keeps working), falling back to the workflow. Removed in 6.1.
-
-| Legacy key (stash-only) | 6.0 key | Resolves to |
-|---|---|---|
-| `cart_add_item_service` | `cart_add_item_workflow` | `Spree::Carts::AddItem` |
-| `cart_recalculate_service` | `cart_recalculate_workflow` | `Spree::Carts::Recalculate` |
-| `carts_complete_service` | `carts_complete_workflow` | `Spree::Carts::Complete` |
-| `order_cancel_service` | `order_cancel_workflow` | `Spree::Orders::Cancel` |
-| `order_complete_service` | `order_complete_workflow` | `Spree::Orders::Complete` |
-| `shipment_update_service` | `fulfillment_update_service` | `Spree::Fulfillments::Update` |
-
-New seams with no legacy counterpart:
-
-| Key | Resolves to | Purpose |
-|---|---|---|
-| `cart_recalculate_totals_workflow` | `Spree::Carts::RecalculateTotals` | the single totals seam |
-| `order_recalculate_totals_workflow` | `Spree::Orders::RecalculateTotals` | order twin (post-placement re-sum) |
-| `order_resume_workflow` | `Spree::Orders::Resume` | resume canceled orders |
-| `order_discount_create_service` | `Spree::Orders::Discounts::Create` | renamed from `order_add_manual_discount_service` (never released) |
-| `order_update_statuses_service` | `Spree::Orders::UpdateStatuses` | the sole status writer |
-
-Removed keys (their classes no longer exist): `carts_validate_service` (completion validation is `Spree::Checkout::Requirements` directly), plus the dead legacy `Spree::Cart::*` service namespace registrations.
-
-If you override a workflow seam, subclass the shipped workflow (or implement the same `perform` keyword contract) — workflow arguments are plain Ruby keywords, so a mismatch raises `ArgumentError` at call time, not silently.
-
-## Removed in 6.0
-
-These were deprecated in 5.x and are **gone now** — there is no bridge, so calls raise `NoMethodError`. Most were one-line delegations to a replacement that already exists.
-
-| Removed | Use instead |
-|---|---|
-| `Product#default_image`, `#featured_image`, `#primary_image` | `#primary_media` |
-| `Variant#default_image`, `#primary_image` | `#primary_media` |
-| `Address#user_default_billing?`, `#user_default_shipping?` | `#is_default_billing?`, `#is_default_shipping?` |
-| `OptionType#color?` | `#color_swatch?` |
-| `Category#set_store` | `#ensure_store` |
-| `Category.for_taxonomy` | `.for_store` |
-| `Store#admin_users` | `#users` |
-| `Store#supported_shipping_zones` | `#countries_with_shipping_coverage` |
-| `Spree.searcher_class` | `Spree.search_provider` |
-| `Spree.admin_user_class.spree_admin_created?` | `.spree_admin.exists?` |
-| `BaseMailer#set_email_locale` | wrap the action body in `with_store_locale(store) { ... }` |
-| `Asset#styles`, `ImageMethods#generate_url`, `#original_url` | Active Storage variants with `cdn_image_url` |
-| `Spree::ImageMethods`, `Spree::NumberAsParam` (concerns) | deleted — `NumberAsParam` was already a no-op; prefixed IDs come from `Spree::PrefixedId` |
-| `Product.with_option`, `.with`, `.in_name`, `.in_name_or_keywords`, `.in_name_or_description`, `.with_ids`, `.for_user` | `.with_option_value`, `.search`, `where(id: ids)` |
-| `Product.add_search_scope` | plain `scope :name, -> { ... }` |
-| `Spree::Image::Configuration::ActiveStorage` | deleted — an empty no-op module; all logic lives in `Spree::Asset` |
-| `Spree::OrderRouting::Strategy::Legacy` | `Spree::OrderRouting::Strategy::Rules` (see below) |
-| `private_metafields` association | read `custom_fields` and filter, or query `Spree::CustomField.admin_only` |
-
-### Custom fields replace metafields
-
-The metafields system is now custom fields: `Spree::CustomField` and `Spree::CustomFieldDefinition`, stored in `spree_custom_fields` and `spree_custom_field_definitions`. The legacy class names, the concern, and the reader methods all keep working for one release with a deprecation warning (see the table further down), so most applications need no code change to upgrade.
-
-Two things do change under you, both handled by `db:migrate`:
-
-- **Visibility is a boolean.** The tri-state `display_on` column collapses into `storefront_visible`. Definitions that were `back_end` become `storefront_visible: false`; everything else becomes `true`. The `front_end`-only value never meant hidden-from-staff and folds into `true`.
-- **Two columns are renamed.** `name` becomes `label`, and `metafield_type` becomes `field_type`. Reading `field_type` returns the API token (`short_text`) rather than the Ruby class name; use `field_type_class_name` when you need the class.
-- **Rich-text values leave Action Text.** `Spree::CustomFields::RichText` stores sanitized HTML in the same `value` column as every other type, so reading `value` returns a String rather than an `ActionText::RichText`. Existing bodies are copied across by the migration; the Action Text rows stay behind as a rollback path until 6.1. Code calling `custom_field.value.body` should read `value` directly.
-
-Two behavior notes for extension authors: `Spree::Metadata` no longer includes the custom-fields concern (metadata is the private, schemaless system — include `Spree::HasCustomFields` explicitly if a model needs both), and rich-text values are now sanitized on save, so markup outside the allowlist is stripped rather than stored.
-
-**BREAKING — product CSV.** Custom-field columns are now prefixed `custom_field.` instead of `metafield.` (for example `custom_field.custom.material`). Exports emit the new prefix and imports only recognise the new prefix, so update any saved import templates and any integration that reads the export. A file still using the old prefix imports without its custom-field values rather than failing.
-
-### The Legacy order-routing strategy is gone
-
-`Spree::OrderRouting::Strategy::Legacy` — the pre-5.5 escape hatch that delegated straight to `Spree::Stock::Coordinator` and consulted no routing rules — is removed and no longer registered in `Spree.order_routing.strategies`.
-
-A store or channel still carrying `preferred_order_routing_strategy: 'Spree::OrderRouting::Strategy::Legacy'` **keeps working**: `Order#order_routing_strategy` ignores unregistered classes, logs a warning, and falls back to `Strategy::Rules`. Clear the stale preference to silence the warning — note that saving such a record now fails validation, since the value is no longer in the registry.
-
-`Spree::Stock::Coordinator` itself stays — cart fulfillment building, exchanges, and claims still use it.
-
-### `belongs_to` is required by default
-
-Spree models followed Rails' pre-5 rule, where a `belongs_to` was optional
-unless you said otherwise. They now follow the modern default: a `belongs_to`
-is **required** unless it is declared `optional: true`.
-
-Two consequences for an application built on Spree:
-
-- **Your own models change with it.** Anything inheriting from `Spree::Base`
- picks up the new default, so an association that is legitimately blank now
- needs `optional: true` on it. A model that relied on the old behaviour will
- start failing validation until you say which associations are optional.
-- **The message changed.** A missing association reports `"must exist"` rather
- than `"can't be blank"`. Code that matches on the old wording — a test, or a
- client reading `details` out of a 422 — needs updating.
-
-Setting a record's association to `nil` and saving it is the quickest way to
-tell whether an association is required.
-
-### `Store.default` no longer builds a store
-
-`Spree::Store.default` returned an **unpersisted** `Store.new(default: true)` when no default store existed. It now returns `nil`.
-
-This matters more than it looks: `Spree::Current.store` falls back to `Store.default`, and every `Spree::SingleStoreResource` model resolves its own `store` from `Spree::Current.store`. Without a default store, those records now fail validation with "Store must exist" instead of silently attaching to a throwaway store.
-
-Make sure a default store exists before creating store-scoped records, and set `Spree::Current.store` in jobs, rake tasks, and tests that run outside a request.
-
-### The `DefaultPrice` concern is gone — `price_in` / `set_price` is the interface
-
-`Spree::DefaultPrice` and the `enable_legacy_default_price` setting are removed, along with the `has_one :default_price` association on `Variant`. Prices live in `spree_prices`, one row per currency, and a price is always an **amount plus a currency** — there is no longer an implicit "the" price.
-
-The single-currency accessors are gone from both `Variant` and `Product`:
-
-| Removed | Use instead |
-|---|---|
-| `variant.price`, `product.price` | `variant.price_in(currency).amount` or `amount_in(currency)` |
-| `variant.price = x`, `product.price = x` | `variant.set_price(currency, x)` |
-| `variant.default_price` | `variant.price_in(currency)` |
-| `variant.currency`, `product.currency` | the currency is an argument now — pass the one you mean |
-| `display_price`, `display_amount` | `price_in(currency).display_amount` |
-| `compare_at_price=` | `set_price(currency, amount, compare_at_amount)` |
-| `display_compare_at_price` | `price_in(currency).display_compare_at_amount` |
-| `price_including_vat_for(opts)` | `price_in(currency).price_including_vat_for(opts)` |
-| `has_default_price?` | `prices.base_prices.exists?(currency: currency)` |
-
-The `compare_at_price` **reader** (which resolves against `cost_currency`) is unchanged on both `Variant` and `Product` — only the writer is gone. So are the `price_in` / `amount_in` / `compare_at_amount_in` readers.
-
-Also note:
-
-- **Ransack:** `default_price` is no longer a searchable association on `Variant`; query `prices` instead.
-- **Prices in permitted params:** the dead `:price` and `:compare_at_price` entries are gone. Prices were already written as nested `prices: [{ amount:, currency: }]` under variants — the top-level keys had no writer behind them. (`Spree::PermittedAttributes` itself is removed in 6.0 — see below.)
-- Localized number parsing still happens: `Spree::Price#amount=` runs `Spree::LocalizedNumber.parse`, so `set_price(currency, '1,599.99')` works as `price=` did.
-- The variant validation that inferred a missing price from the product's default variant is gone. Set prices explicitly (the product and variant factories already do).
-
-### `Spree::PermittedAttributes` is removed
-
-The global permitted-attributes registry is gone, with no deprecation bridge. It
-existed so the Rails admin and storefront could share one allowlist; both are
-removed in 6.0, and API v3 declares its attributes in the controller.
-
-Removed alongside it: `Spree::Core::ControllerHelpers::StrongParameters` (the
-`permitted_*_attributes` helper methods it mixed into controllers) and the
-fallback that inferred an attribute list from the model name.
-
-Attributes you pushed from an initializer are now declared on the model, and
-standard resource endpoints append them to their own allowlist — so one
-declaration still covers the model's create and update endpoints.
-
-#### How to migrate
-
-**1. Find every call site.** The constant and the helper methods are both gone,
-so a missed reference raises `NameError` or `NoMethodError` the first time that
-code runs — loudly, but not necessarily at boot:
-
-```bash
-grep -rn "PermittedAttributes" app config lib
-grep -rnE "permitted_[[:alnum:]_]+_attributes" app config lib
-```
-
-The second pattern is deliberately broad: the helper module generated one
-`permitted_*_attributes` method per registry key, so there were dozens of them.
-
-**2. Decide what each attribute actually is.** Most fall into one of three
-buckets, and only the last needs this hook:
-
-| What you were adding | Where it goes in 6.0 |
-| --- | --- |
-| A merchant-managed field (text, number, dropdown) | [Custom Fields](/developer/core-concepts/custom-fields) — no code, and filterable/sortable |
-| Config for an STI type you register (promotion rule, delivery method rule, …) | `additional_permitted_attributes` on that subclass, as before — unchanged |
-| A real database column your extension added to a core model | `additional_permitted_attributes` on the model |
-
-**3. Point each declaration at the model.** It stays in your initializer — only
-the receiver changes, from the global registry to the model itself:
-
-```ruby config/initializers/spree.rb
-# Before
-Spree::PermittedAttributes.product_attributes << :brand_id
-
-# After
-Spree::Product.additional_permitted_attributes += [:brand_id]
-```
-
-Use `+=`, not `=` — the list is per model, and assigning replaces whatever
-another extension already added. `<<` raises a `FrozenError`: the default is a
-frozen shared array, so mutating it in place would leak your attribute onto every
-other model.
-
-Declare only attributes of your own. Redeclaring a key the controller already
-permits (`metadata`, `prices`) does not widen it — strong parameters keeps the
-last filter for that key, so the controller's own would be replaced by yours.
-
-Entries are `params.permit` fragments, so collections and nested structures keep
-the shapes you already know: `[:brand_id, { region_ids: [] }]`.
-
-**4. Fix your own controllers.** If you subclassed a Spree v3 resource
-controller and relied on the attribute list being inferred from the model name,
-declare it now:
-
-```ruby
-class BrandsController < Spree::Api::V3::Admin::ResourceController
- protected
-
- def model_class
- Spree::Brand
- end
-
- # Before: no such method — the base class inferred `brand_attributes`
- # from the model name. Now you say what you accept.
- def resource_permitted_attributes
- [:name, :slug, :description]
- end
-end
-```
-
-Declaring neither `resource_permitted_attributes` nor `permitted_params` raises
-`NotImplementedError` on the first write, so this surfaces in your test suite
-rather than silently permitting a stale list.
-
-**5. Verify a write actually persists.** A declaration that never reaches a
-controller fails silently — strong parameters drop the unpermitted key, the
-request still returns 200, and the column keeps its old value. Assert on the
-saved record, not the response status:
-
-```ruby
-patch "/api/v3/admin/products/#{product.prefixed_id}",
- params: { brand_id: brand.id }, headers: headers
-
-expect(product.reload.brand_id).to eq(brand.id)
-```
-
-If that assertion fails, the endpoint is not consulting your declaration. Check
-whether the controller overrides `permitted_attributes` — that method is where
-the extension attributes are appended, so overriding it replaces them. Override
-`resource_permitted_attributes` instead.
-
-<Warning>
- Two endpoints deliberately ignore the hook because their parameters are
- authorization data rather than resource data: API keys (`scopes`, `key_type`)
- and invitations (`role_id`). Adding attributes there needs a controller
- decorator, not a model declaration.
-</Warning>
-
-STI types registered through a Spree registry (promotion rules and actions,
-delivery method rules, commission rules) already used
-`additional_permitted_attributes` and need no changes — the hook simply moved up
-to `Spree::Base`.
-
-### `StateChange` and `LogEntry` are gone
-
-`Spree::StateChange` and `Spree::LogEntry` are removed — the models, the `state_changes` associations on `Order`, `Payment` and `Fulfillment`, the `log_entries` associations on `Payment` and `Refund`, and everything that wrote to them. Both were write-only: nothing in Spree read the rows back, and the admin screens that displayed them are gone.
-
-**Events are the audit trail now.** Instead of querying state-change rows, subscribe to the lifecycle events that already fire on every meaningful transition: `order.placed`, `order.canceled`, `payment.completed`, `payment.voided`, `fulfillment.ready`, `fulfillment.fulfilled`, `fulfillment.canceled`, `fulfillment.resumed`, and the rest. If you need a persistent history, write it from a subscriber.
-
-**Gateway responses are no longer stored in your database.** `LogEntry` kept every gateway response as serialized YAML. For transaction forensics, use your payment provider's dashboard — `Payment#gateway_dashboard_payment_url` links straight to the transaction — or `Spree::PaymentSession`, which holds the gateway-side state for session-based providers.
-
-The `spree_state_changes` and `spree_log_entries` tables are **not dropped until 6.1**, so your existing rows survive the upgrade. If you want the history long-term, export it before upgrading to 6.1.
-
-## Deprecated in 6.0, removed in 6.1
-
-Every rename keeps the legacy name working for one release with a deprecation warning. The notable ones:
-
-| Deprecated | Use instead |
-|---|---|
-| `Order#finalize!` | `Spree.order_complete_workflow` |
-| `Order#updater`, `Spree::OrderUpdater`, `Spree::CartUpdater` | `#recalculate_totals!` / `#update_statuses!` |
-| `Order#shipping_discount` | `#fulfillment_discount` |
-| `Order#special_instructions` | `#customer_note` (column renamed) |
-| `Order#promo_total`, `#item_count`, `#ship_total` | `#discount_total`, `#total_quantity`, `#delivery_total` (columns renamed) |
-| `use_billing` / `clone_billing_address` | `use_shipping` (shipping address is canonical) |
-| `Fulfillment#ship`, `#ship!`, `#shipped?`, `#can_ship?`, `#shipping_method`, `#add_shipping_method` | `#fulfill`, `#fulfill!`, `#fulfilled?`, `#can_fulfill?`, `#delivery_method`, `#add_delivery_method` |
-| `LineItem#target_shipment` | `#target_fulfillment` |
-| `Order#create_proposed_shipments` / `#create_proposed_fulfillments` | `#rebuild_fulfillments!` (Cart ships with the new name only) |
-| `Order#remove_out_of_stock_items!` | cart-side only (`Spree::Carts::RemoveOutOfStockItems`) |
-| `Order#delivery_required?` | `#delivery_step_required?` — digital and pickup are deliveries too; this asks whether the customer must choose a delivery option |
-| `Order#requires_ship_address?` | `#shipping_address_required?` — decided by the selected delivery methods (`DeliveryMethod#requires_address?`); digital, pickup, and pickup-point deliveries need no customer address |
-| `requirements[].field` / `.code` `shipping_method` (Store API) | `delivery_method` / `delivery_method_required` — no bridge; clients keying off the delivery requirement must switch both tokens |
-| `Cart#number` (Store API field) | `id` — carts have no order-style number; the field mirrors the prefixed ID for one release |
-| `order.completed` event | `order.placed` |
-| Calling cart services with `order:` kwargs | `cart:` kwargs |
-| `OrderWalkthrough` (testing support) | factories: `:cart_ready_for_delivery`, `:cart_ready_to_complete`, `:completed_order_with_totals` |
-| `Spree::Metafield`, `Spree::MetafieldDefinition`, `Spree::Metafields::*` | `Spree::CustomField`, `Spree::CustomFieldDefinition`, `Spree::CustomFields::*` |
-| `include Spree::Metafields` | `include Spree::HasCustomFields` |
-| `#set_metafield`, `#get_metafield`, `#has_metafield?` | `#set_custom_field`, `#get_custom_field`, `#has_custom_field?` |
-| `metafields` / `public_metafields` associations | `custom_fields` / `storefront_custom_fields` |
-| `.with_metafield_key`, `.with_metafield_key_value` | `.with_custom_field_key`, `.with_custom_field_key_value` |
-| `Spree.metafields` | `Spree.custom_fields` |
-| `CustomFieldDefinition#name`, `#metafield_type`, `#display_on` | `#label`, `#field_type`, `#storefront_visible` (columns renamed) |
-| `Spree::SearchProvider::Meilisearch` | `SpreeMeilisearch::SearchProvider` (moved to the `spree_meilisearch` gem) |
-| `Spree::SearchProvider::ProductPresenter` | `SpreeMeilisearch::ProductPresenter` (moved to the `spree_meilisearch` gem) |
-
-## Meilisearch moved to its own gem
-
-Meilisearch is no longer part of `spree_core`. Stores using the Database provider (the default) need to do nothing.
-
-If you set `Spree.search_provider` to the Meilisearch provider, add the gem and update the class name:
-
-```ruby
-# Gemfile
-gem 'spree_meilisearch'
-
-# config/initializers/spree.rb
-Spree.search_provider = 'SpreeMeilisearch::SearchProvider'
-```
-
-Your `MEILISEARCH_URL` and `MEILISEARCH_API_KEY` settings are unchanged, and **no reindex is needed** — the documents have the same shape. Applications that subclassed the document presenter should inherit from `SpreeMeilisearch::ProductPresenter` instead.
-
-The old class names keep working for one release, so an application that only names them in an initializer boots with a deprecation warning rather than an error — but the gem must be installed either way, since the classes now live there.
-
-## Staff permissions: roles are data
-
-Permission sets are **removed with no bridge**. Staff roles now hold flat permission keys from one catalog — the same `read_<resource>` / `write_<resource>` vocabulary secret API keys use — and are managed as data: in the dashboard (Settings → Roles), through the Admin API (`/api/v3/admin/roles`), or in seeds. Code no longer defines what a role can do.
-
-| Removed | Use instead |
-|---|---|
-| `Spree::PermissionSets::*` (all classes) | catalog keys on the role row: `Spree::Role#permissions` |
-| `Spree.permissions.assign(:role, [sets])` | the role editor, `POST /api/v3/admin/roles`, or plain ActiveRecord in seeds |
-| Custom permission sets with record-level rules | Replace the ability class: `Spree::Dependencies.ability_class = 'MyApp::Ability'` |
-| `Spree::ApiKey::SCOPES` | `Spree::ApiKey.known_scopes` (derived from the catalog) |
-
-Old initializers fail loudly at boot: the set constants raise `NameError`, and `Spree.permissions.assign` raises with directions. **Recreate your custom roles before deploying** — a pre-existing role row comes up with no permissions, so staff holding it are locked out (fail closed) until its permissions are filled in:
-
-```ruby
-# db/seeds.rb — "roles as code" is plain ActiveRecord now
-Spree::Role.find_or_create_by!(name: 'support')
- .update!(permissions: %w[read_orders read_customers])
-```
-
-Storefront customers are not part of this system: the old `:default` role and `DefaultCustomer` set are gone, customers never resolve roles, and the Store API no longer consults CanCanCan at all — customer authorization is ownership-scoped queries plus `Spree::Storefront::AccessPolicy` (swappable via `Spree::Dependencies.storefront_access_policy_class`). If an extension added storefront `can` rules, move them into an access-policy subclass or a checkout workflow `validate` hook. Extensions register their resources into the catalog once, which makes them grantable to roles **and** mintable as API-key scopes:
-
-```ruby
-Spree.permissions.register_scope(:reviews, group: :catalog, resources: -> { [SpreeReviews::Review] })
-```
-
-Two enforcement changes on the Admin API:
-
-- **JWT staff pass the same per-controller key gate as secret keys.** A request whose principal lacks `<read|write>_<resource>` gets a 403 with `details.required_permission` naming the missing key.
-- **Staff endpoints moved out of the `settings` scope.** `/admin_users`, `/invitations`, and `/roles` now require the new `read_staff` / `write_staff` scopes; secret keys minted with `settings` before 6.0 lose those endpoints. `/countries` and `/locales` became scope-exempt reference data.
-
-### Rich-text fields read as plain text plus HTML
-
-**Writes are unchanged.** `description` and `internal_note` still take the value, and that value is still HTML — the same as 5.6, so no integration needs updating.
-
-Reads are where 6.0 differs. Every rich-text field now returns both shapes:
-
-| Resource | Plain text | HTML |
-| --- | --- | --- |
-| Product, Category, Collection | `description` | `description_html` |
-| Order, Customer | `internal_note` | `internal_note_html` |
-
-Two consequences worth checking in your own code:
-
-- **Hydrate editors from `*_html`.** The plain field is tag-stripped, so binding an editor to `description` and saving it back would flatten the markup on every save.
-- **The field holds HTML.** That is true of every writer — the Admin API, CSV import, the console — so send markup, not plain text with newlines in it.
-
-Both internal-note serializers now return the pair. Previously orders exposed only plain text and customers only HTML.
-
-Stored markup is also held to a narrower allowlist than 5.6 — see [the rich-text migration](#move-rich-text-out-of-action-text) for what is permitted and how to widen it.
-
-## For extension authors
-
-- **Don't reach for model business methods from services** — 6.0 code style writes behavior inline in service/workflow steps; models keep data, validations, predicates and persistence primitives. Extensions patching removed model methods (`finalize!` internals, updater hooks) should move to workflow hooks (`Spree.hooks.register('carts.complete.before_finalize') { |flow| ... }` — handlers receive the workflow instance) or event subscribers.
-- **Store-scoped data is single-owner.** `Product`, `Promotion` and `PaymentMethod` `belongs_to :store`; the `stores: [...]` writers are gone. Multi-store sharing lives in the `spree_multi_store` extension.
-- The Store API v3 contract is stable across the split — cart endpoints keep their shapes; `requirements` gains `code` (and renames the delivery entry's field/code to `delivery_method`, see above), and serializer `number` on carts is bridged as described above.
-
-<Warning>
- This guide tracks the 6.0 development line and will grow until release. If a behavioral change you hit isn't documented here, treat it as a documentation bug and report it.
-</Warning>