@spree/docs 0.1.239 → 0.1.241

package/dist/api-reference/store-api/metadata.md

@@ -6,7 +6,7 @@ description: "How to store and retrieve custom metadata on carts, orders, and li
 
 The Store API supports storing arbitrary key-value **metadata** on carts (orders) and line items. Metadata is useful for tracking custom information like gift messages, attribution data, or integration-specific fields.
 
-> **NOTE:** Metadata is different from [metafields](../../developer/core-concepts/metafields.md). Metadata is simple JSON storage (untyped, no schema), while metafields are structured, typed, and schema-defined. Use metadata for integration data and internal tracking. Use metafields for customer-facing custom attributes.
+> **NOTE:** Metadata is different from [custom fields](../../developer/core-concepts/metafields.md). Metadata is simple JSON storage (untyped, no schema), while custom fields are structured, typed, and schema-defined. Use metadata for integration data and internal tracking. Use custom fields for customer-facing custom attributes.
 
 ## Cart Metadata
 
@@ -146,18 +146,18 @@ Metadata is stored as a flat JSON object. You can use any keys and values:
 }
 ```
 
-## Metadata vs Metafields
+## Metadata vs Custom Fields
 
-Spree has two permanent, complementary systems for custom data — **metadata for machines, metafields for humans**.
+Spree has two permanent, complementary systems for custom data — **metadata for machines, custom fields for humans**.
 
-| | Metadata | Metafields |
+| | Metadata | Custom Fields |
 |-|----------|------------|
 | **Purpose** | Developer escape hatch — integration IDs, sync state | Merchant-defined structured attributes |
-| **Schema** | Schemaless JSON — no definition required | Defined via MetafieldDefinitions (typed, validated) |
+| **Schema** | Schemaless JSON — no definition required | Defined via CustomFieldDefinitions (typed, validated) |
 | **Validation** | None | Type-specific validation |
 | **Visibility** | Write-only in Store API, readable in Admin API | Configurable (admin-only or public) |
 | **Admin UI** | JSON preview | Dedicated form fields |
 | **Best for** | Integration data, tracking, attribution, write-and-forget | Product specs, custom attributes, customer-facing data |
 | **API access** | Write via Store API, read via Admin API | Read/write via both APIs |
 
-Both systems are here to stay. For more details on metafields, see the [Metafields guide](../../developer/core-concepts/metafields.md).
+Both systems are here to stay. For more details on custom fields, see the [Custom Fields guide](../../developer/core-concepts/metafields.md).

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

@@ -5,9 +5,10 @@ description: How Spree fits together — the catalog, the cart, the order, and f
 
 ## Overview
 
-Spree is a commerce engine you drive through a REST API. It holds the catalog, works out what a customer owes, takes the money, and tracks what was sent. You build the storefront, the mobile app, or the internal tool on top of it.
+Spree is a commerce engine you drive through a REST API. It holds the catalog, works out what a customer owes, takes the money, and tracks what was delivered. You build the storefront, the mobile app, Point of Sale or an internal tool on top of it.
 
-There is no built-in storefront you have to accept. Everything a customer-facing app needs is on the Store API, and everything a back office needs is on the Admin API. Both ship as typed TypeScript clients.
+There is no built-in storefront you have to accept, however we do provide a [reference one built in Next.js](../storefront/nextjs/quickstart.md). 
+Everything a customer-facing app needs is on the Store API, and everything a back office needs is on the Admin API. Both ship as fully typed TypeScript clients.
 
 ## The shape of a purchase
 
@@ -72,7 +73,7 @@ Three things in that diagram are worth calling out, because they're where Spree
 
 **Delivery is described by a profile, not a category.** A [delivery profile](fulfillments.md) says how a product travels — physically shipped, or digital — and which locations and methods serve it.
 
-**Stock lives per location.** A variant has a stock level at each [stock location](inventory.md), so availability is a real question about real warehouses rather than a single number.
+**Stock lives per location.** A variant can have a stock level at each [stock location](inventory.md), so availability is a real question about real warehouses rather than a single number.
 
 ## The two APIs
 
@@ -103,6 +104,7 @@ Spree assumes you'll extend it, and gives you three ways in that survive an upgr
 
 | Approach | Use it for | Guide |
 |---|---|---|
+| **Events** | Reacting inside your own app when something happens — indexing a record, calling an API with your credentials | [Events](events.md) |
 | **Webhooks** | Telling another system something happened — an ERP, a warehouse, an email tool | [Webhooks](webhooks.md) |
 | **Custom fields** | Storing your own data on a product, order or customer without changing the schema | [Custom Fields](metafields.md) |
 | **Providers** | Plugging in a real service for tax, delivery rates, payments or search | [Providers](../providers/overview.md) |
@@ -116,32 +118,26 @@ One Spree installation can run more than one business:
 - **[Stores](stores.md)** are separate businesses — their own catalog, orders, customers and settings. Data does not cross between them.
 - **[Channels](channels.md)** are the ways one store sells: a website, a mobile app, a retail till.
 - **[Markets](markets.md)** are the regions a store sells into, each with its currency, locale and tax treatment.
-- **[Sellers](products.md#seller-submissions)** let one store list goods from many vendors, for a marketplace.
+- **[Sellers](sellers.md)** let one store list goods from many vendors, for a marketplace.
 
 ## What you install
 
-| Package | What it is |
-|---|---|
-| `spree` | The engine — catalog, checkout, payments, both APIs |
-| `spree_emails` | Transactional email, if you don't send your own |
-| `spree_dashboard` | The back-office dashboard |
-
-Providers for search, delivery rates, tax and payments install separately, so you only carry what you use.
-
-**TypeScript:**
-
 | Package | What it is |
 |---|---|
 | [`@spree/sdk`](../sdk/quickstart.md) | Store API client — for your storefront |
 | [`@spree/admin-sdk`](../sdk/admin/quickstart.md) | Admin API client — for back-office and integrations |
 | [`@spree/cli`](../cli/quickstart.md) | Command line for local setup and calling the Admin API |
+| [`@spree/dashboard`](../dashboard/overview.md) | The admin interface, a React app you own and extend |
 
-> **INFO:** Spree runs on PostgreSQL, MySQL or SQLite. PostgreSQL is recommended for production — [database configuration](../deployment/database.md).
+> **INFO:** Spree runs on PostgreSQL, MySQL or SQLite. Check [database configuration](../deployment/database.md) for more details.
 
 ## Where to go next
 
+Two ways in, depending on how you prefer to learn.
+
+
+  - [Build something](../tutorial/introduction.md) — Add one feature end to end — a model with its own API, a screen in the dashboard, a page on the storefront, and the tests around it. Start here if you learn by doing.
+  - [Read the reference](products.md) — Every part of the platform, one page each: products and pricing, carts and orders, payments, fulfillment, promotions. Start here if you already know what you need.
+
 
-  - [Quickstart](../getting-started/quickstart.md) — Get an installation running.
-  - [Store SDK](../sdk/quickstart.md) — Build a storefront against the Store API.
-  - [Products](products.md) — How the catalog is modelled.
-  - [Carts](carts.md) — Cart, checkout, and what completion guarantees.
+Building a storefront rather than extending the backend? Go straight to the [Spree Next.js Storefront](../storefront/nextjs/quickstart.md).

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

@@ -131,10 +131,80 @@ A cart tells you what it still needs before it can be completed:
 }
 ```
 
-An empty `requirements` array means the cart is ready.
+Every entry has the same four fields. Branch on `code` — `message` is translated prose
+meant for a person, and `step` is only a grouping hint.
 
 This is what lets you design your own checkout. Spree tells you what's missing; you decide how and when to ask for it — one long page, a few steps, or whatever suits your storefront.
 
+Seven checks run on every cart read:
+
+| `code` | `step` | Raised when |
+|---|---|---|
+| `line_items_required` | `cart` | The cart is empty |
+| `email_required` | `address` | No email address |
+| `ship_address_required` | `address` | Something needs shipping and there is no address |
+| `delivery_method_required` | `delivery` | A delivery method hasn't been chosen |
+| `payment_required` | `payment` | The total isn't covered by payments |
+| `po_number_required` | `address` | A company requires a purchase-order number |
+| `order_minimum_not_met` | `cart` | Below the order minimum, with the shortfall in the message |
+
+> **WARNING:** **An empty `requirements` array does not guarantee completion will succeed.** What a
+>   cart reports is the *advisory* set. Completing one additionally checks stock
+>   (`out_of_stock`, `discontinued`), negotiated quantity rules
+>   (`quantity_rule_violated`) and the guest-checkout policy
+>   (`guest_checkout_not_allowed`) — each of which has to load line items, so they are
+>   held back to keep reading a cart cheap. Treat a failed completion as a normal path,
+>   not an exception.
+
+### Checkout steps
+
+A cart also reports a step list, so you can render a progress indicator:
+
+
+```typescript Store SDK
+const cart = await client.carts.get(cartId)
+
+cart.current_step     // "delivery"
+cart.completed_steps  // ["address"]
+```
+
+```json Response
+{
+  "current_step": "delivery",
+  "completed_steps": ["address"]
+}
+```
+
+
+Spree has no checkout state machine. The list is computed from the cart's own data,
+and nothing on the server refuses a write because of where the customer appears to be
+— you can set an address, choose delivery and attach a payment in any order.
+`current_step` is simply the step of the first unmet requirement.
+
+Five steps are built in, and three only appear when they apply:
+
+| Step | Present when |
+|---|---|
+| `address` | Always |
+| `delivery` | The cart has items and isn't entirely digital |
+| `payment` | The total is above zero |
+| `confirm` | A payment method asks for one, or the store always wants one |
+| `complete` | Always |
+
+So a free digital order reports `address` then `complete`. A storefront that hardcodes
+five steps will show two that never apply.
+
+> **NOTE:** Requirements use one grouping name that is not a step: **`cart`**. Missing line
+>   items, the order minimum and stock problems are filed under it, and there is no
+>   `cart` entry in the step list — `current_step` reports those as `address`. If you
+>   group requirements by `step` to place them on screens, give `cart` a home.
+
+Checkout introspection lives on the cart, not the order. An order has already been
+placed, so `current_step` and `requirements` do not appear on it.
+
+To add your own step or requirement, see
+[Customizing checkout](../customization/checkout.md).
+
 ## Checkout
 
 **Step 1: Add the customer's details**

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

@@ -9,8 +9,6 @@ Sooner or later you need to store something Spree doesn't have a field for. A fa
 
 Custom fields are how you do that without changing the database. You declare a field once — its name, its type, who can see it — and from then on it can be set on any record of that kind, edited in the dashboard, returned by the API, and searched or filtered like any built-in field.
 
-> **NOTE:** Custom fields are also known as **metafields** in the dashboard. The API and SDK call them custom fields throughout.
-
 ## Definitions and values
 
 There are two halves, and it helps to keep them straight:

package/dist/developer/create-spree-app/quickstart.md

@@ -18,7 +18,7 @@ The CLI walks you through an interactive setup:
 
 Once complete, your store is running at [http://localhost:3000](http://localhost:3000) — setup pulls the latest Spree image, seeds the database, and configures API keys, then prints a summary with your admin credentials and keys. If you skipped starting services, the first `pnpm dev` completes setup automatically.
 
-The **React Dashboard** (Developer Preview of the next-generation admin) is available with the `--react-dashboard` flag, or later via `spree add dashboard`.
+The **dashboard** and the marketplace **seller panel** are included in every project — there is no flag to add them.
 
 ## Prerequisites
 
@@ -35,7 +35,7 @@ npx create-spree-app@latest my-store --no-storefront --no-sample-data --no-start
 
 | Flag | Description |
 |------|-------------|
-| `--react-dashboard` | Include the React Dashboard (Developer Preview — also available later via `spree add dashboard`) |
+| `--react-dashboard` | No-op — the dashboard is always included. Kept so existing scripts keep working |
 | `--no-storefront` | Skip Next.js storefront setup |
 | `--no-sample-data` | Skip loading sample products and categories |
 | `--no-start` | Don't start Docker services after scaffolding |
@@ -52,29 +52,32 @@ npx create-spree-app@latest my-store --no-storefront --no-sample-data --no-start
 
 ```text
 my-store/
+├── server/                   # The Spree API — a full Rails app from spree/spree-starter
+│   ├── app/                  # Your models, controllers, serializers and jobs
+│   ├── config/
+│   ├── Dockerfile            # Also builds the production image (API + dashboard)
+│   └── Gemfile
+├── apps/
+│   ├── dashboard/            # Admin dashboard (React)
+│   │   └── .env.local        # Dev proxy target — no credentials
+│   ├── seller-dashboard/     # Seller panel, for marketplaces (React)
+│   └── storefront/           # Next.js storefront (unless --no-storefront)
+│       └── .env.local        # API URL + publishable key
+├── .env                      # SECRET_KEY_BASE, SPREE_PORT, SPREE_VERSION_TAG, SPREE_SAMPLE_DATA
+├── .spree/                   # CLI credentials — gitignored, created on first run
 ├── docker-compose.yml        # Spree backend (prebuilt image) + Postgres + Meilisearch
 ├── docker-compose.dev.yml    # Alternative: build from local server/
 ├── render.yaml               # Render Blueprint — one Docker service built from this repo
-├── .env                      # SECRET_KEY_BASE, SPREE_PORT, SPREE_VERSION_TAG, SPREE_SAMPLE_DATA
 ├── .dockerignore             # Keeps the production build context to sources
 ├── .gitignore
-├── package.json              # Convenience scripts
-├── README.md
-├── server/                  # Full Rails app — the Spree API (from spree/spree-starter)
-│   ├── Gemfile
-│   ├── Dockerfile            # Also builds the production image (API + dashboard)
-│   ├── config/
-│   ├── app/
-│   └── ...
-└── apps/
-    ├── storefront/           # Next.js storefront (unless --no-storefront)
-    │   ├── .env.local        # API URL + API key
-    │   └── ...
-    └── dashboard/            # React Dashboard (with --react-dashboard)
-        ├── .env.local        # Dev proxy target — no credentials
-        └── ...
+├── package.json              # Scripts and the pinned @spree/cli
+├── AGENTS.md                 # Instructions for coding agents
+├── CLAUDE.md                 # Project layout and conventions
+└── README.md                 # How to run everything
 ```
 
+**`server/` is the only part that is Spree's.** The apps under `apps/` are ordinary Vite and Next.js projects you own — restyle, restructure or replace them without forking anything. Each carries its own instructions (`server/CLAUDE.md`, `apps/dashboard/AGENTS.md`), which is also what a coding agent reads.
+
 ### What's in docker-compose.yml
 
 - **Spree** — one `web` container running the `ghcr.io/spree/spree:latest` image on the configured port (default `3000`); background jobs run in-process via Solid Queue (stored in Postgres — job dashboard at `/jobs`)
@@ -127,7 +130,7 @@ Open [http://localhost:3000/admin](http://localhost:3000/admin) and log in with:
 | **Email** | `spree@example.com` |
 | **Password** | `spree123` |
 
-With `--react-dashboard`, the React Dashboard's dev server is the admin instead: `spree dev` starts it alongside the API at [http://localhost:5173](http://localhost:5173) — same credentials, live-reloading from `apps/dashboard/` (the classic admin remains at `/admin`). See the [React Dashboard docs](../dashboard/overview.md).
+The dashboard runs as its own dev server: `spree dev` starts it alongside the API at [http://localhost:5173](http://localhost:5173), with the same credentials, live-reloading from `apps/dashboard/`. See the [dashboard docs](../dashboard/overview.md).
 
 ### Store API
 

package/dist/developer/customization/api.md

@@ -5,7 +5,7 @@ description: Add new Store API endpoints, customize existing JSON responses with
 
 Before you start customizing Spree API endpoints, make sure you reviewed all existing API endpoints in the [Spree API docs](../../api-reference/admin-api/endpoints.md).
 
-For a step-by-step walkthrough of adding a complete new resource (model, serializer, controller, routes), see the [API tutorial](../tutorial/admin-api.md).
+For a step-by-step walkthrough of adding a complete new resource (model, serializer, controller, routes), see the [API tutorial](../tutorial/model-and-api.md).
 
 ## Customizing JSON Responses
 
@@ -35,7 +35,7 @@ Restart the server and the Product API will include your new attribute.
 
 ### Adding an Association
 
-Let's say you've created a `Spree::Brand` model that belongs to `Product` (see the [tutorial](../tutorial/admin-api.md) for the full example).
+Let's say you've created a `Spree::Brand` model that belongs to `Product` (see the [tutorial](../tutorial/model-and-api.md) for the full example).
 
 Create a serializer for the new model:
 

package/dist/developer/customization/checkout.md

@@ -0,0 +1,117 @@
+---
+title: Customizing Checkout
+description: Add your own checkout step or requirement, and reorder or remove the built-in ones.
+---
+
+Spree does not run your checkout — your storefront does. What Spree owns is the list
+of things a cart still needs, which it reports on cart reads and enforces when you
+complete one. Adding to that list is how you make checkout require something of your
+own.
+
+> **NOTE:** For what a cart reports and how to read it, see
+>   [Carts](../core-concepts/carts.md#checkout-requirements). This page is about
+>   adding to it.
+
+## Requirements are the gate, steps are a label
+
+Two things are easy to confuse:
+
+- A **requirement** is enforced. It appears on cart reads while unmet, and completing
+  a cart recomputes the list and refuses if anything is outstanding.
+- A **step** is descriptive. It exists so a storefront can render a progress
+  indicator. Nothing on the server checks which step a customer is on.
+
+So a requirement is what you reach for when something must be true before an order
+exists. A step is only worth adding when your checkout genuinely has a stage the
+built-in five don't describe.
+
+## Adding a requirement
+
+When the flow is unchanged and you only need one more condition:
+
+```ruby server/config/initializers/spree.rb
+Spree::Checkout::Registry.add_requirement(
+  step: :address,
+  field: :vat_number,
+  message: 'VAT number is required for business orders',
+  satisfied: ->(cart) { cart.custom_fields['vat_number'].present? }
+)
+```
+
+While `satisfied:` returns false the cart reports the requirement and refuses to
+complete. Its `code` is derived as `<field>_required` — `vat_number_required` here.
+
+Pass `applicable:` to scope it. It is checked before `satisfied:`, so a requirement
+that doesn't apply never appears at all:
+
+```ruby
+applicable: ->(cart) { cart.customer&.company.present? }
+```
+
+`message` is stored verbatim — wrap it in `Spree.t` yourself if it needs translating.
+
+## Adding a step
+
+A step bundles its own requirements and says when it is satisfied:
+
+```ruby server/config/initializers/spree.rb
+Spree::Checkout::Registry.register_step(
+  name: :loyalty,
+  before: :payment,
+  satisfied: ->(cart) { cart.custom_fields['loyalty_number'].present? },
+  requirements: ->(cart) {
+    [{ step: 'loyalty', field: 'loyalty_number',
+       message: 'Loyalty number is required' }]
+  }
+)
+```
+
+The step now shows up in the cart's `current_step` and `completed_steps`, its
+requirements appear in `requirements` while unsatisfied, and completion refuses the
+cart until they are met.
+
+Each lambda receives the cart. Placement is controlled by two keywords:
+
+| Keyword | Effect |
+|---|---|
+| `before:` / `after:` | Place the step next to an existing one. `before:` wins if both are given |
+| `applicable:` | Whether the step exists for this cart at all — checked before `satisfied:` |
+
+An unanchored step lands immediately before `complete`. An anchor naming a step this
+particular cart doesn't have — `before: :payment` on a free cart — falls back to the
+same place.
+
+Unlike an added requirement, a step's `requirements:` lambda may set its own `code:`.
+
+## Reordering or removing built-in steps
+
+```ruby server/config/initializers/spree.rb
+# Drop a step from the reported list
+Spree::Checkout::Registry.base_steps.delete('confirm')
+
+# Or change when one applies
+Spree::Checkout::Registry.base_steps['payment'] = ->(cart) { cart.total > 0 }
+
+# Or reorder wholesale — known names keep their own applicability
+Spree::Checkout::Registry.base_step_names = %w[address payment delivery complete]
+```
+
+> **WARNING:** Removing a step removes it from the reported list. It does **not** remove the
+>   requirements filed under it — dropping `payment` does not let an unpaid cart
+>   complete. Requirements and steps are separate on purpose.
+
+## Prefer a requirement to a workflow hook
+
+A [workflow hook](workflows.md) on `carts.complete.validate`
+can also reject a cart, and there are cases for it — anything needing a network call, or a
+decision that only makes sense at the moment of completion.
+
+For anything a customer has to fix, a requirement is better: it is reported on every
+cart read, so the storefront can show it while they can still act, rather than failing
+at the last step with an error they have to interpret.
+
+## Related
+
+- [Carts](../core-concepts/carts.md) — reading requirements and completing a cart
+- [Custom fields](../core-concepts/metafields.md) — storing your own data on a cart
+- [Services & Workflows](workflows.md) — hooks that run during completion