@spree/docs 0.1.247 → 0.1.249

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

@@ -33,7 +33,7 @@ await adminClient.products.update('prod_86Rf07xd4z', {
 curl -X PATCH 'https://api.mystore.com/api/v3/admin/products/prod_86Rf07xd4z' \
   -H 'X-Spree-API-Key: sk_xxx' \
   -H 'Content-Type: application/json' \
-  -d '{ "delivery_profile_id": "dp_digital" }'
+  -d '{ "delivery_profile_id": "fp_digital" }'
 ```
 
 

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

@@ -25,7 +25,7 @@ All data is fully isolated besides the staff users, which can manage multiple te
 ## Prerequisites
 
 * You need to be on Spree 5.1+, we recommend using [CLI](../getting-started.md) to setup your Spree application.
-* You need to set 2 environment variables in your `backend` directory:
+* You need to set 2 environment variables in your `server` directory:
   * `KEYGEN_ACCOUNT_ID`
   * `KEYGEN_LICENSE_KEY`
 * Both PostgreSQL and MySQL are supported
@@ -84,7 +84,7 @@ spree eject
     ```yaml docker-compose.yml
     x-app: &app
       build:
-        context: ./backend
+        context: ./server
         dockerfile: Dockerfile
         target: dev
         secrets: # [!code ++]

package/dist/developer/providers/payouts.md

@@ -130,10 +130,14 @@ end
 ### Register it
 
 ```ruby server/config/initializers/spree.rb
-Spree.integrations << 'MyApp::AcmeIntegration'
-Spree.payout_providers << MyApp::PayoutProvider
+Rails.application.config.after_initialize do
+  Spree.integrations << 'MyApp::AcmeIntegration'
+  Spree.payout_providers << MyApp::PayoutProvider
+end
 ```
 
+Register inside `after_initialize`: Spree sets up its own integrations list after your initializers run, so an entry added at the top level of the file would be dropped.
+
 The operator then picks it under **Settings → Marketplace**, which is the store's `payout_provider` preference. The picker is built from the registry, so your provider appears alongside the built-in one and reports whether the store can use it today:
 
 

package/dist/developer/sdk/admin/querying-and-errors.md

@@ -10,7 +10,7 @@ Collection endpoints support [Ransack](https://activerecord-hackery.github.io/ra
 
 ```typescript
 const { data: orders } = await client.orders.list({
-  status_eq: 'complete',          // exact match
+  status_eq: 'placed',          // exact match
   total_gteq: 100,                // greater than or equal
   email_cont: '@example.com',     // substring match
   customer_id_eq: 'cus_xxx',      // prefixed IDs work directly

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

@@ -6,12 +6,12 @@ description: "Install and configure @spree/admin-sdk, the official TypeScript cl
 
 [`@spree/admin-sdk`](https://www.npmjs.com/package/@spree/admin-sdk) is the official TypeScript SDK for the [Admin API v3](../../../api-reference/admin-api/introduction.md) — the back-office counterpart to [`@spree/sdk`](../quickstart.md). Use it to build integrations, automations, internal tools, and custom admin UIs: manage products, orders, customers, stock, promotions, webhooks, and more.
 
-> **WARNING:** The Admin SDK is in **Developer Preview** on the `0.x` line and published under the `next` dist-tag. The API surface may change between minor versions — check the [changelog](https://github.com/spree/spree/blob/main/packages/admin-sdk/CHANGELOG.md) when updating. It requires Spree 5.5 or newer.
+> **NOTE:** `@spree/admin-sdk` 1.x works with the Spree 6.0 Admin API. Check the [changelog](https://github.com/spree/spree/blob/main/packages/admin-sdk/CHANGELOG.md) when updating.
 
 ## Installation
 
 ```bash
-npm install @spree/admin-sdk@next
+npm install @spree/admin-sdk
 ```
 
 ## Quick start
@@ -26,9 +26,9 @@ const client = createAdminClient({
   secretKey: process.env.SPREE_SECRET_KEY, // sk_xxx — server-side only
 })
 
-// List recent completed orders
+// List recently placed orders
 const { data: orders, meta } = await client.orders.list({
-  status_eq: 'complete',
+  status_eq: 'placed',
   sort: '-completed_at',
   limit: 25,
 })

package/dist/developer/sdk/authentication.md

@@ -41,8 +41,11 @@ const orders = await client.customer.orders.list({}, { token })
 
 
 ```typescript
-// Refresh token when needed
-const newTokens = await client.auth.refresh({ token })
+// Exchange the refresh_token returned by login for a new access token.
+// The refresh token rotates, so store the new one as well.
+const { token: newToken, refresh_token: newRefreshToken } = await client.auth.refresh({
+  refresh_token: refreshToken,
+})
 ```
 
 ## Register New Customer

package/dist/developer/sdk/store/cart-checkout.md

@@ -28,7 +28,7 @@ const carts = await client.carts.list();
 await client.carts.delete(cartId, { spreeToken: cart.token });
 
 // Associate guest cart with authenticated user
-// (after user logs in, merge their guest cart with their account)
+// (after user logs in, assign the guest cart to their account — carts are not merged)
 await client.carts.associate(cartId, {
   token: jwtToken,         // User's JWT token
   spreeToken: cart.token,  // Guest cart token
@@ -112,8 +112,8 @@ await client.carts.update(cartId, {
     city: 'New York',
     postal_code: '10001',
     phone: '+1 555 123 4567',
-    country_iso: 'US',
-    state_abbr: 'NY',
+    country_code: 'US',
+    state_code: 'NY',
   },
   billing_address_id: 'addr_xxx', // Or use existing address by ID
 }, { spreeToken: cart.token });
@@ -177,7 +177,7 @@ The cart and order responses break the amount the customer pays into these total
 ### Get a Completed Order
 
 ```typescript
-const order = await client.orders.get('R123456789', {
+const order = await client.orders.get('or_xxx', { // prefixed order ID (or the cart ID)
   expand: ['items', 'fulfillments'],
 }, { spreeToken: cart.token });
 ```

package/dist/developer/storefront/nextjs/emails.md

@@ -23,6 +23,8 @@ Email templates are React components in `src/lib/emails/`:
 
 Customize a template by editing its file directly — they use `@react-email/components` for email-safe layout primitives.
 
+> **NOTE:** The storefront listens for `order.completed` and `order.shipped`, the names these events had before Spree 6.0. Spree 6.0 still sends them alongside the new names, `order.placed` and `order.fulfilled`, but stops in Spree 6.1. Before upgrading to 6.1, switch the storefront handlers and your webhook endpoint subscriptions to the new names.
+
 ## Previewing
 
 Run the storefront in development and open [http://localhost:3001/dev/emails](http://localhost:3001/dev/emails):
@@ -68,11 +70,11 @@ To add a new email type:
 1. Create a template in `src/lib/emails/`.
 2. Add a handler function in `src/lib/webhooks/handlers.ts`.
 3. Register the event in `route.ts`.
-4. Subscribe to the event in **Spree Admin → Settings → Developers → Webhooks**.
+4. Subscribe to the event in **Spree Admin → Settings → Developer → Webhooks**.
 
 ## Setup
 
-1. **Create a webhook endpoint** in Spree Admin → Settings → Developers → Webhooks. Subscribe to `order.completed`, `order.canceled`, `order.shipped`, and `customer.password_reset_requested`, and copy the secret key into `SPREE_WEBHOOK_SECRET`.
+1. **Create a webhook endpoint** in Spree Admin → Settings → Developer → Webhooks. Subscribe to `order.completed`, `order.canceled`, `order.shipped`, and `customer.password_reset_requested`, and copy the secret key into `SPREE_WEBHOOK_SECRET`.
 
 2. **Receive webhooks locally.** Expose the storefront with a public URL so Spree can reach it — the simplest option is a [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/):
 

package/dist/developer/storefront/nextjs/testing.md

@@ -65,7 +65,7 @@ A project scaffolded with [`create-spree-app`](../../create-spree-app/quickstart
 
 ```bash
 # From the project root — build the customized backend image
-docker build -t project-spree:e2e ./backend
+docker build -t project-spree:e2e ./server
 
 # From apps/storefront — run E2E against it
 cd apps/storefront

package/dist/developer/upgrades/5.6-to-6.0.md

@@ -36,7 +36,14 @@ bundle exec rake spree:upgrade
 ```
 
 
-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.
+Before running `bundle update`, update your `Gemfile`: the Rails admin (`spree_admin`) and Rails storefront (`spree_storefront`) are not part of Spree 6.0. Remove both and add `spree_dashboard`, which serves the new React admin dashboard at `/dashboard`.
+
+```ruby
+# Gemfile
+gem 'spree_dashboard'
+```
+
+Re-running is safe — `bundle exec rake spree:upgrade` figures out what still needs to happen and does nothing on data that's already migrated. It also runs every data backfill from earlier upgrades (5.4 → 5.5 and 5.5 → 5.6), so any you missed along the way are caught up. That does not remove the requirement above: upgrade your application to 5.6 first.
 
 ## What the upgrade does
 
@@ -56,7 +63,7 @@ Every order that never completed and was never canceled becomes a `Spree::Cart`
 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.
+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 (`metadata['typed_adjustments_frozen']`) for manual review instead of silently changing money.
 
 ### Backfill fulfillment and delivery naming
 
@@ -94,14 +101,14 @@ Category and collection descriptions, policy bodies, and order and customer inte
 
 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.
+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`, links and images. Tables, `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]
+Spree::RichTextSanitizer.allowed_tags += %w[table thead tbody tr th td]
+Spree::RichTextSanitizer.allowed_attributes += %w[colspan rowspan]
 ```
 
 The Action Text rows are left in place as a rollback path and are dropped with the tables in 6.1.
@@ -153,6 +160,24 @@ Rows written before the upgrade carry an id and an empty type; this task fills
 the type in. Until it runs they still read as the staff member they always
 were, with a deprecation warning. Safe to re-run at any time.
 
+### Move users onto the Customer and AdminUser models
+
+```bash
+bundle exec rake spree:upgrade:migrate_users_to_customers
+```
+
+Copies your legacy Devise customer table (default `spree_users`) into `spree_customers`, keeping the same ids, and carries existing passwords over so customers and staff can keep signing in. The source table is left in place as a safety net.
+
+> **WARNING:** Passwords carry over only if your application **never configured a Devise pepper**. The task stops if it finds one. Because Devise is no longer loaded in 6.0, the task usually cannot check for itself — it stops until you confirm no pepper was used by re-running it with `CONFIRM_NO_PEPPER=true`. If you did use a pepper, single sign-on, or a non-bcrypt password format, skip this step and keep your own customer model by setting `Spree.customer_class`.
+
+### Name countries and states by ISO code
+
+```bash
+bundle exec rake spree:upgrade:migrate_country_state_codes
+```
+
+Countries and states are no longer database records in 6.0. Addresses, delivery zone members, market countries, stock locations and stores now name them by ISO code (`country_code`, `state_code`), and this task fills those columns from the old `country_id` / `state_id` references. The old `country_iso` / `state_abbr` names still work on addresses for one release.
+
 ## The Cart/Order split
 
 The single biggest change. What used to be one `Spree::Order` living through checkout and beyond is now two models:
@@ -180,17 +205,17 @@ The replacement model:
 
 ```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
+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? }
+)
 ```
 
+  Register at the top level of the initializer, not inside `to_prepare`: the registry is never reset, so a `to_prepare` block would add the requirement again on every code reload in development.
+
   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.
@@ -211,7 +236,7 @@ Behavior to review:
 
 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.
+- **`Spree::Carts::RecalculateTotals`** is the single totals seam: money inputs, typed-row regeneration (promotions via the winner-only adjuster, tax via the market's tax provider, falling back to `Spree.default_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.
@@ -287,10 +312,15 @@ Core ships exactly one policy rule — a return window read from `market.preferr
 Replace it by swapping the handler:
 
 ```ruby
-Spree.hooks.unregister('returns.create.validate', 'Spree::Returns::EligibilityValidator')
-Spree.hooks.register('returns.create.validate', 'MyStore::ReturnPolicy')
+# config/initializers/spree.rb
+Rails.application.config.after_initialize do
+  Spree.hooks.unregister('returns.create.validate', 'Spree::Returns::EligibilityValidator')
+  Spree.hooks.register('returns.create.validate', 'MyStore::ReturnPolicy')
+end
 ```
 
+Wrap the swap in `after_initialize`: core registers the default validator after your initializers load, so an `unregister` at the top level of an initializer would run too early and do nothing.
+
 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.
@@ -319,7 +349,7 @@ A handler receives the workflow (so it can read `order`, `items`, `created_by`,
 | `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` |
+| `shipment_update_service`, `fulfillment_update_service` | `fulfillment_update_workflow` | `Spree::Fulfillments::Update` |
 
 New seams with no legacy counterpart:
 
@@ -581,7 +611,7 @@ to `Spree::Base`.
 
 `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.
+**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.fulfilled`, `fulfillment.delivered`, `fulfillment.canceled`, 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.
 
@@ -620,7 +650,8 @@ Every rename keeps the legacy name working for one release with a deprecation wa
 | `Spree::PresentationTranslatable` | `Spree::LabelTranslatable` |
 | `Spree::WishedItem`, `Wishlist#wished_items`, `#wished_items_count` | `Spree::WishlistItem`, `#wishlist_items`, `#wishlist_items_count` (class and table renamed; the `wi_` prefixed IDs are unchanged, so client-held IDs keep resolving) |
 | `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` |
+| `Fulfillment#ship`, `#ship!` | `Spree.fulfillment_fulfill_workflow.call(fulfillment:)` (`Spree::Fulfillments::Fulfill`) |
+| `Fulfillment#shipped?`, `#can_ship?`, `#shipping_method`, `#add_shipping_method` | `#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`) |

package/dist/integrations/search/meilisearch.md

@@ -5,7 +5,7 @@ description: "Set up Meilisearch in Spree for fast, typo-tolerant product search
 
 ## Overview
 
-[Meilisearch](https://www.meilisearch.com/) is a fast, open-source search engine that provides typo tolerance, relevance ranking, faceted filtering, and sub-50ms search responses. Spree includes a built-in Meilisearch search provider that replaces the default SQL-based search.
+[Meilisearch](https://www.meilisearch.com/) is a fast, open-source search engine that provides typo tolerance, relevance ranking, faceted filtering, and sub-50ms search responses. The official `spree_meilisearch` gem provides a Meilisearch search provider that replaces the default SQL-based search.
 
 **When to use Meilisearch:**
 - Catalogs with 1,000+ products
@@ -48,7 +48,7 @@ docker run -d --name meilisearch \
 ### 2. Add the gem to your Gemfile
 
 ```ruby
-gem 'meilisearch', '>= 0.28'
+gem 'spree_meilisearch'
 ```
 
 
@@ -77,7 +77,7 @@ MEILISEARCH_URL=http://localhost:7700
 
 ```ruby
 # config/initializers/spree.rb
-Spree.search_provider = 'Spree::SearchProvider::Meilisearch'
+Spree.search_provider = 'SpreeMeilisearch::SearchProvider'
 ```
 
 ### 5. Index your products
@@ -216,7 +216,7 @@ The Meilisearch provider automatically configures these filterable attributes:
 - `name` — product name (in document locale)
 - `description` — product description (in document locale)
 - `sku` — variant SKU
-- `option_values` — option value presentations (e.g., "Red", "Small")
+- `option_values` — option value labels (e.g., "Red", "Small")
 - `category_names` — category names
 - `tags` — product tags
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.247",
+  "version": "0.1.249",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",