@spree/docs 0.1.247 → 0.1.249

package/dist/developer/contributing/developing-spree.md

@@ -23,7 +23,7 @@ You need **Node.js 20+** to run the workspace scripts (including `pnpm server:se
 
 Spree is a monorepo with three main areas:
 
-- **`spree/`** — Ruby gems (core, api, admin, emails) distributed as separate packages via RubyGems
+- **`spree/`** — Ruby gems (core, api, dashboard, emails, opentelemetry, and provider gems under `spree/providers/`) distributed as separate packages via RubyGems
 - **`packages/`** — TypeScript packages (SDKs, CLI, project scaffolding, docs, React dashboard)
 - **`server/`** — A Rails application cloned from [spree-starter](https://github.com/spree/spree-starter) that mounts the local Spree gems (not checked in — `pnpm server:setup` creates it)
 
@@ -38,9 +38,9 @@ pnpm server:setup   # ~5–10 min on first run; idempotent
 
 `pnpm server:setup` clones [spree-starter](https://github.com/spree/spree-starter) into `./server/`, wires it to load Spree gems from the monorepo via a Docker compose overlay, builds the dev image, starts the stack (Postgres + Meilisearch + a single Rails `web` container — background jobs run in-process via Solid Queue), and prepares the database. The full sequence lives in `scripts/server-setup.sh`.
 
-When it's done, the backend is up at [http://localhost:3000](http://localhost:3000) and the admin is at [http://localhost:3000/admin](http://localhost:3000/admin). Sign in with the seed admin: **`spree@example.com`** / **`spree123`** (override at seed time with `ADMIN_EMAIL` / `ADMIN_PASSWORD` env vars — see `spree/core/app/services/spree/seeds/admin_user.rb`).
+When it's done, the backend is up at [http://localhost:3000](http://localhost:3000). The React dashboard runs as its own development server — start it with `pnpm dashboard:dev` and open [http://localhost:5173](http://localhost:5173). The setup script prints a one-time link for creating the first admin account; open it once the dashboard is running. To seed an admin account instead, set the `ADMIN_EMAIL` and `ADMIN_PASSWORD` environment variables before seeding (see `spree/core/app/services/spree/seeds/admin_user.rb`).
 
-Optionally load sample products, taxonomies, and option types:
+Optionally load sample products, categories, and option types:
 
 ```bash
 pnpm server:load_sample_data
@@ -110,8 +110,12 @@ The Spree [Rails engines](https://guides.rubyonrails.org/engines.html) live insi
 |---|---|---|
 | `core` | `spree_core` | Models, services, business logic |
 | `api` | `spree_api` | REST APIs |
-| `admin` | `spree_admin` | Admin dashboard |
-| `emails` | `spree_emails` | Transactional emails |
+| `dashboard` | `spree_dashboard` | Serves a built React dashboard and seller panel from your Rails server |
+| `emails` | `spree_emails` | Transactional emails (optional) |
+| `opentelemetry` | `spree_opentelemetry` | OpenTelemetry tracing (optional) |
+| `providers/stripe` | `spree_stripe` | Stripe payments (optional) |
+| `providers/easypost` | `spree_easypost` | EasyPost delivery rates and shipping labels (optional) |
+| `providers/meilisearch` | `spree_meilisearch` | Meilisearch product search (optional) |
 
 ### Spree namespace
 
@@ -133,7 +137,7 @@ bundle exec rake test_app
 bundle exec rspec
 ```
 
-Replace `core` with `api`, `admin`, or `emails` to test other engines.
+Replace `core` with `api`, `dashboard`, `emails`, `opentelemetry`, or a provider path such as `providers/stripe` to test other engines.
 
 By default engine tests run against SQLite3. To run against PostgreSQL, set the `DB` environment variable:
 
@@ -181,15 +185,7 @@ bundle exec parallel_rspec -n 4 spec
 
 After schema changes, re-run `bundle exec rake parallel_setup` to update the worker databases.
 
-### Integration tests (legacy Rails admin)
-
-The legacy Rails admin (`spree/admin`) ships feature specs that run in a real browser via chromedriver. You only need this if you're touching the legacy admin UI.
-
-Install chromedriver on macOS:
-
-```bash
-brew install chromedriver
-```
+### Integration tests
 
 The React dashboard (`packages/dashboard`) has its own end-to-end test suite running on Playwright against a real Rails backend — see [Dashboard E2E tests](#dashboard-e2e-tests) under TypeScript Development.
 
@@ -216,7 +212,7 @@ The backend setup is the same as for Ruby work — see [Setup](#setup) above. Wi
 | `@spree/cli` | `packages/cli` | yes | CLI for managing Spree Commerce projects |
 | `create-spree-app` | `packages/create-spree-app` | yes | Project scaffolding (`npm create spree-app`) |
 | `@spree/docs` | `packages/docs` | yes | Developer documentation for AI agents and local reference |
-| `@spree/dashboard` | `packages/dashboard` | no | React SPA admin dashboard (replaces the legacy Rails admin) |
+| `@spree/dashboard` | `packages/dashboard` | no | React SPA admin dashboard |
 | `@spree/dashboard-core` | `packages/dashboard-core` | no | Framework: registries, providers, generic infra hooks for the dashboard |
 | `@spree/dashboard-ui` | `packages/dashboard-ui` | no | Design system used by the dashboard |
 | `@spree/sdk-core` | `packages/sdk-core` | no | Shared HTTP/retry/error layer used by both SDKs |
@@ -259,7 +255,7 @@ cd packages/dashboard
 pnpm dev   # http://localhost:5173
 ```
 
-Sign in with `spree@example.com` / `spree123`. To point at a non-default backend, set `VITE_SPREE_API_URL` (also needs to be set at build time for production bundles, not just dev):
+Sign in with the admin account you created from the setup link (see [Setup](#setup)). To point at a non-default backend, set `VITE_SPREE_API_URL` (also needs to be set at build time for production bundles, not just dev):
 
 ```bash
 VITE_SPREE_API_URL=https://my-spree.example.com pnpm dev

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

@@ -136,7 +136,7 @@ A [Channel](channels.md) is not assigned — it names its catalog directly via `
 ```typescript Admin SDK
 await adminClient.catalogs.assign(catalog.id, {
   assignable_type: 'customer_group',
-  assignable_id: 'cgrp_xxx',
+  assignable_id: 'cg_xxx',
 })
 ```
 
@@ -144,7 +144,7 @@ await adminClient.catalogs.assign(catalog.id, {
 curl -X POST 'https://api.mystore.com/api/v3/admin/catalogs/cat_xxx/assign' \
   -H 'X-Spree-API-Key: sk_xxx' \
   -H 'Content-Type: application/json' \
-  -d '{ "assignable_type": "customer_group", "assignable_id": "cgrp_xxx" }'
+  -d '{ "assignable_type": "customer_group", "assignable_id": "cg_xxx" }'
 ```
 
 

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

@@ -38,7 +38,7 @@ erDiagram
 | `default` | Exactly one channel per store is the default. Used as a fallback when no channel header is present and as the auto-publish target for new products | `true` |
 | `storefront_access` | Controls what an anonymous visitor may see: `public`, `prices_hidden`, or `login_required`. Unset inherits the store's setting. See [Storefront Access Gating](#storefront-access-gating) | `login_required` |
 | `guest_checkout` | Whether an order may be placed without an account on this channel. Unset inherits the store's setting | `false` |
-| `preferred_order_routing_strategy` | Optional per-channel override of the store's [Order Routing](fulfillments.md#order-routing) strategy | `Spree::OrderRouting::Strategy::Rules` |
+| `preferred_order_routing_strategy` | Optional per-channel override of the store's [Order Routing](../how-to/custom-order-routing.md) strategy | `Spree::OrderRouting::Strategy::Rules` |
 
 `code` is normalized to a URL-safe slug on save — `POS` becomes `pos`, `Point of Sale!` becomes `point-of-sale`. Leaving `code` blank derives it from `name`.
 
@@ -105,7 +105,7 @@ Product status (`draft` / `active` / `archived`) is the **outer gate**: a Draft
 
 Every order is attributed to one channel. The channel is set from the `X-Spree-Channel` header on cart creation, from the merchant's selection on the "New order" form, or defaults to the store's primary channel.
 
-This attribution drives reporting (best-selling by channel, revenue per channel) and per-channel order routing — see [Order Routing](fulfillments.md#order-routing).
+This attribution drives reporting (best-selling by channel, revenue per channel) and per-channel order routing — see [Order Routing](../how-to/custom-order-routing.md).
 
 ### Storefront Access Gating
 
@@ -232,7 +232,7 @@ The write contract is **full-set**: the array represents the complete desired st
 - [Stores](stores.md) — Channels belong to a store
 - [Markets](markets.md) — Different from channels: markets segment geography/currency, channels segment selling surfaces
 - [Products](products.md) — Product catalog and publication
-- [Order Routing](fulfillments.md#order-routing) — Channels can override the store's routing strategy
+- [Order Routing](../how-to/custom-order-routing.md) — Channels can override the store's routing strategy
 - [Store SDK: Products](../sdk/store/products.md) — Channel-scoped product listing and filtering
 - [Admin SDK: Resources](../sdk/admin/resources.md) — How `adminClient.channels.addProducts` and other resource methods are structured
 - [Wholesale Portal](../storefront/nextjs/wholesale.md) — A gated channel driving the Next.js storefront's B2B surface

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

@@ -212,7 +212,8 @@ await adminClient.companies.taxIdentifiers.create('comp_xxx', {
   value: 'NL123456789B01',
 })
 
-// Validation runs against the official registry, in the background
+// Out of the box this checks the number's format and checksum only.
+// Registry lookups (such as VIES) come from an extension that re-registers the validator.
 await adminClient.companies.taxIdentifiers.validate('comp_xxx', 'txid_xxx')
 ```
 

package/dist/developer/core-concepts/delivery-setup.md

@@ -72,7 +72,7 @@ const profiles = await adminClient.deliveryProfiles.list()
 
 // Ship a product as a download
 await adminClient.products.update('prod_xxx', {
-  delivery_profile_id: 'dp_digital',
+  delivery_profile_id: 'fp_digital',
 })
 ```
 
@@ -85,7 +85,7 @@ curl 'https://api.mystore.com/api/v3/admin/delivery_profiles' \
 curl -X PATCH 'https://api.mystore.com/api/v3/admin/products/prod_xxx' \
   -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/core-concepts/discounts.md

@@ -60,7 +60,7 @@ Note the difference between `value` and `amount`. `value` is the rule — "10 pe
 
 ## Reading discounts on an order
 
-Whatever produced them, the rows read the same way:
+The Store API summarizes the promotions applied to a cart or order under `discounts` — one entry per promotion, with its name, code and total amount. The individual discount rows, including manual ones, are read through the Admin API (`GET /api/v3/admin/orders/{id}/discounts`).
 
 
 ```typescript Store SDK
@@ -69,10 +69,10 @@ const cart = await client.carts.get(cartId)
 cart.display_discount_total // "-$12.00"
 
 cart.discounts.forEach((discount) => {
-  discount.label          // "Summer Sale"
-  discount.kind           // "promotion" or "manual"
+  discount.name           // "Summer Sale"
   discount.code           // "SUMMER20", when a code was used
   discount.display_amount // "-$12.00"
+  discount.promotion_id   // "promo_xxx"
 })
 ```
 

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

@@ -44,12 +44,14 @@ On top of that, meaningful business moments get their own events:
 | `order.placed` | A customer completed checkout |
 | `order.paid` | Payment is settled in full |
 | `order.canceled` | The order was cancelled |
-| `order.shipped` / `order.delivered` | Everything has shipped / arrived |
+| `order.fulfilled` / `order.delivered` | Everything has shipped / arrived |
 | `payment.completed` / `payment.voided` | A payment succeeded / was released |
-| `fulfillment.shipped` / `fulfillment.canceled` | A parcel went out / was stood down |
+| `fulfillment.fulfilled` / `fulfillment.canceled` | A parcel went out / was stood down |
 | `product.out_of_stock` / `product.back_in_stock` | Availability flipped |
 | `return.received` / `return.refunded` | A return arrived / was refunded |
-| `import.completed` / `export.completed` | Bulk work finished |
+| `import.completed` | An import finished |
+
+For the full list of events and their payloads, see [Webhook Events & Payloads](../../api-reference/webhooks-events.md).
 
 The distinction matters when choosing what to listen for. `order.updated` fires whenever anything about an order changes — including an admin editing a note. `order.placed` fires once, when a customer actually bought something. Sending a confirmation email on the wrong one is how customers receive nine copies.
 
@@ -61,7 +63,6 @@ An event carries the record it's about, serialized:
 {
   "id": "or_86Rf07xd4z",
   "number": "R123456789",
-  "status": "placed",
   "payment_status": "paid",
   "total": "135.60",
   "email": "customer@example.com"
@@ -128,7 +129,7 @@ That's almost always what you want. If you genuinely need to run inside the same
 subscribes_to 'order.placed', async: false
 ```
 
-> **WARNING:** A synchronous subscriber runs while the customer waits, and an exception in it can fail their checkout. Reserve it for work that must be atomic with the order, and keep it fast.
+> **WARNING:** A synchronous subscriber runs while the customer waits, so a slow one slows their checkout. An exception in it is reported to `Rails.error` and swallowed in production, but re-raised in development and test so you notice it. Reserve it for work that must happen immediately, and keep it fast.
 
 ## Publishing your own events
 

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

@@ -14,7 +14,7 @@ Four pieces make that work, and none of them disturb retail shipping:
 
 | Piece | Question it answers |
 |---|---|
-| **Carton details** on a product | How do these units pack? |
+| **Carton details** on a variant | How do these units pack? |
 | **Freight summary** on a cart or order | How big is the whole load? |
 | **Volume and company rules** on a delivery method | Which shipment tier is this? |
 | **Unpriced rates** | What does a buyer see before a price exists? |
@@ -35,7 +35,8 @@ weight**.
 
 The geometry lives on a shared carton, because merchants reuse a handful of
 standard sizes across hundreds of products and one edit should fix all of
-them. What varies per product stays on the product:
+them. What varies per product is set on each variant (the product's only variant
+for products without options):
 
 | Field | What it says |
 |---|---|

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

@@ -57,7 +57,7 @@ erDiagram
 | `delivery_rates` | The options the customer can choose from |
 | `selected_delivery_rate_id` | The chosen option |
 | `fulfilled_at` | When it went out |
-| `delivered_at` | When the customer got it — what return windows count from |
+| `delivered_at` | When the customer got it |
 
 ## Statuses
 
@@ -104,9 +104,9 @@ only delivered when the third one lands. That rollup is recomputed whenever
 deliveries are added, removed or corrected — including when a tracking number
 is fixed, which starts that consignment's journey over.
 
-`delivered_at` is what return windows and the EU withdrawal period count from,
-so it records when the carrier says the parcel arrived rather than when you
-heard about it.
+`delivered_at` records when the carrier says the parcel arrived rather than
+when you heard about it. (The default return window counts from when the order
+was placed, not from delivery — see [returns](returns-exchanges-claims.md).)
 
 Carriers report this through their provider's webhook, matched to the delivery
 by tracking number. With no carrier integration, staff mark receipt by hand —
@@ -216,11 +216,11 @@ Each fulfillment on a cart offers delivery rates. The customer picks one per ful
 const cart = await client.carts.get(cartId)
 
 cart.fulfillments[0].delivery_rates
-// => [{ id: 'rate_xxx', name: 'DHL Express', display_cost: '$12.00',
+// => [{ id: 'dr_xxx', name: 'DHL Express', display_cost: '$12.00',
 //       estimated_delivery_date: '2026-08-07' }, ...]
 
 await client.carts.fulfillments.update(cartId, cart.fulfillments[0].id, {
-  selected_delivery_rate_id: 'rate_xxx',
+  selected_delivery_rate_id: 'dr_xxx',
 })
 ```
 
@@ -229,7 +229,7 @@ curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/fulfillments/
   -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: abc123' \
   -H 'Content-Type: application/json' \
-  -d '{ "selected_delivery_rate_id": "rate_xxx" }'
+  -d '{ "selected_delivery_rate_id": "dr_xxx" }'
 ```
 
 
@@ -286,7 +286,9 @@ await adminClient.orders.fulfillments.markDelivered('or_xxx', 'ful_xxx')
 
 // Split it when only part can go now
 await adminClient.orders.fulfillments.split('or_xxx', 'ful_xxx', {
-  items: [{ fulfillment_item_id: 'fi_xxx', quantity: 1 }],
+  variant_id: 'variant_xxx',
+  quantity: 1,
+  stock_location_id: 'sloc_xxx', // optional; defaults to the fulfillment's location
 })
 
 // Cancel

package/dist/developer/core-concepts/imports-exports.md

@@ -45,8 +45,8 @@ const exportJob = await adminClient.exports.create({
 
 // Poll until it's done
 const status = await adminClient.exports.get(exportJob.id)
-status.status       // "pending" → "processing" → "completed"
-status.download_url // available once completed
+status.done         // true once the file is ready
+status.download_url // available once done
 ```
 
 ```bash CLI
@@ -63,7 +63,7 @@ An export can carry the same filters as the listing it came from, so "export wha
 ```typescript Admin SDK
 await adminClient.exports.create({
   type: 'orders',
-  filters: { completed_at_gteq: '2026-01-01' },
+  search_params: { completed_at_gteq: '2026-01-01' },
 })
 ```
 
@@ -71,7 +71,7 @@ await adminClient.exports.create({
 curl -X POST 'https://api.mystore.com/api/v3/admin/exports' \
   -H 'X-Spree-API-Key: sk_xxx' \
   -H 'Content-Type: application/json' \
-  -d '{ "type": "orders", "filters": { "completed_at_gteq": "2026-01-01" } }'
+  -d '{ "type": "orders", "search_params": { "completed_at_gteq": "2026-01-01" } }'
 ```
 
 
@@ -113,8 +113,8 @@ Importing has an extra step, because a file from somewhere else won't have Spree
 
     status.status         // "processing" → "completed"
     status.rows_count     // total
-    status.processed_count
-    status.failed_count
+    status.completed_rows_count
+    status.failed_rows_count
     ```
 
 
@@ -167,9 +167,12 @@ Imports and exports emit [events](events.md) as they progress, which also reach
 
 | Event | When |
 |---|---|
+| `import.created` | An import has been uploaded |
+| `import.progress` | A batch of rows has been processed |
 | `import.completed` | Every row has been attempted |
-| `import.failed` | The import could not run |
-| `export.completed` | The file is ready to download |
+| `export.created` | An export has been requested (generation starts in the background) |
+
+There is no event when an export's file is ready — poll the export until `done` is `true`.
 
 ## Permissions
 

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

@@ -240,7 +240,7 @@ await adminClient.stockTransfers.stockReceipts.create(transfer.id, {
 curl -X POST 'https://api.mystore.com/api/v3/admin/stock_transfers' \
   -H 'X-Spree-API-Key: sk_xxx' \
   -H 'Content-Type: application/json' \
-  -d '{ "source_location_id": "sl_a", "destination_location_id": "sl_b" }'
+  -d '{ "source_location_id": "sloc_xxx", "destination_location_id": "sloc_yyy" }'
 ```
 
 
@@ -283,7 +283,7 @@ await adminClient.purchaseOrders.stockReceipts.create(order.id, {
 curl -X POST 'https://api.mystore.com/api/v3/admin/purchase_orders' \
   -H 'X-Spree-API-Key: sk_xxx' \
   -H 'Content-Type: application/json' \
-  -d '{ "supplier_id": "sup_xxx", "stock_location_id": "sl_xxx" }'
+  -d '{ "supplier_id": "sup_xxx", "destination_location_id": "sloc_xxx" }'
 ```
 
 

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

@@ -28,7 +28,7 @@ Every file in a store is in the library, whether or not it's currently placed on
 const { data: media } = await adminClient.media.list()
 
 // Where is this file being used?
-const { data: usage } = await adminClient.media.usage('med_xxx')
+const { data: usage } = await adminClient.media.usage('media_xxx')
 ```
 
 ```bash cURL
@@ -37,7 +37,7 @@ curl 'https://api.mystore.com/api/v3/admin/media' \
   -H 'X-Spree-API-Key: sk_xxx'
 
 # Where is this file being used?
-curl 'https://api.mystore.com/api/v3/admin/media/med_xxx/usage' \
+curl 'https://api.mystore.com/api/v3/admin/media/media_xxx/usage' \
   -H 'X-Spree-API-Key: sk_xxx'
 ```
 
@@ -58,7 +58,7 @@ Placing a library file on a product creates a **new media row that shares the sa
 
 ```typescript Admin SDK
 await adminClient.products.media.create('prod_xxx', {
-  source_media_id: 'med_xxx',
+  source_media_id: 'media_xxx',
   alt: 'Worn over a navy jumper',
   position: 2,
 })
@@ -68,7 +68,7 @@ await adminClient.products.media.create('prod_xxx', {
 curl -X POST 'https://api.mystore.com/api/v3/admin/products/prod_xxx/media' \
   -H 'X-Spree-API-Key: sk_xxx' \
   -H 'Content-Type: application/json' \
-  -d '{ "source_media_id": "med_xxx", "alt": "Worn over a navy jumper", "position": 2 }'
+  -d '{ "source_media_id": "media_xxx", "alt": "Worn over a navy jumper", "position": 2 }'
 ```
 
 
@@ -83,19 +83,19 @@ A file in use can't be deleted by accident:
 
 ```typescript Admin SDK
 // Returns 422 with the list of places it's used
-await adminClient.media.delete('med_xxx')
+await adminClient.media.delete('media_xxx')
 
 // Remove it from everywhere, then delete
-await adminClient.media.delete('med_xxx', { detach: true })
+await adminClient.media.delete('media_xxx', { detach: true })
 ```
 
 ```bash cURL
 # Returns 422 with the list of places it is used
-curl -X DELETE 'https://api.mystore.com/api/v3/admin/media/med_xxx' \
+curl -X DELETE 'https://api.mystore.com/api/v3/admin/media/media_xxx' \
   -H 'X-Spree-API-Key: sk_xxx'
 
 # Remove it from everywhere, then delete
-curl -X DELETE 'https://api.mystore.com/api/v3/admin/media/med_xxx?detach=true' \
+curl -X DELETE 'https://api.mystore.com/api/v3/admin/media/media_xxx?detach=true' \
   -H 'X-Spree-API-Key: sk_xxx'
 ```
 
@@ -271,8 +271,8 @@ const video = await client.products.media.create('prod_86Rf07xd4z', {
 ```
 
 ```bash cURL
-curl -X POST 'https://api.mystore.com/api/v3/store/products/prod_86Rf07xd4z/media' \
-  -H 'X-Spree-API-Key: pk_xxx' \
+curl -X POST 'https://api.mystore.com/api/v3/admin/products/prod_86Rf07xd4z/media' \
+  -H 'X-Spree-API-Key: sk_xxx' \
   -H 'Content-Type: application/json' \
   -d '{
     "media_type": "video",
@@ -293,8 +293,8 @@ await client.products.media.update('prod_86Rf07xd4z', 'media_k5nR8xLq', {
 ```
 
 ```bash cURL
-curl -X PATCH 'https://api.mystore.com/api/v3/store/products/prod_86Rf07xd4z/media/media_k5nR8xLq' \
-  -H 'X-Spree-API-Key: pk_xxx' \
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/products/prod_86Rf07xd4z/media/media_k5nR8xLq' \
+  -H 'X-Spree-API-Key: sk_xxx' \
   -H 'Content-Type: application/json' \
   -d '{ "poster_signed_id": "SIGNED_POSTER_BLOB_ID" }'
 ```
@@ -327,8 +327,8 @@ await client.products.media.update('prod_86Rf07xd4z', 'media_k5nR8xLq', {
 ```
 
 ```bash cURL
-curl -X PATCH 'https://api.mystore.com/api/v3/store/products/prod_86Rf07xd4z/media/media_k5nR8xLq' \
-  -H 'X-Spree-API-Key: pk_xxx' \
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/products/prod_86Rf07xd4z/media/media_k5nR8xLq' \
+  -H 'X-Spree-API-Key: sk_xxx' \
   -H 'Content-Type: application/json' \
   -d '{ "focal_point_x": 0.25, "focal_point_y": 0.4 }'
 ```

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

@@ -141,11 +141,11 @@ await adminClient.orders.cancel('or_grouped_xxx', {
 })
 
 // Take an authorized payment
-await adminClient.orders.payments.capture('or_xxx', 'pay_xxx')
+await adminClient.orders.payments.capture('or_xxx', 'py_xxx')
 
 // Refund against a specific payment
 await adminClient.orders.refunds.create('or_xxx', {
-  payment_id: 'pay_xxx',
+  payment_id: 'py_xxx',
   amount: '25.00',
 })
 ```

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

@@ -109,7 +109,6 @@ erDiagram
 - **Payment Setup Session** manages saving payment methods for future use without an immediate charge (e.g., Stripe SetupIntent)
 - **Source** is polymorphic - can be a Credit Card, Payment Source (for alternative methods like Klarna, iDEAL), or Store Credit
 - **Gateway Customer** stores the provider-specific customer profile (e.g., Stripe Customer ID)
-- **Log Entries** record gateway responses for debugging
 - **Refunds** track money returned to customers
 
 ## Payment Methods
@@ -597,7 +596,7 @@ cannot start one from your storefront:
 await adminClient.orders.refunds.create(orderId, {
   payment_id: 'py_abc123',
   amount: '25.00',
-  reason_id: 'rr_xyz789',
+  refund_reason_id: 'rr_xyz789',
 })
 ```
 

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

@@ -49,12 +49,12 @@ erDiagram
 
     OptionType {
         string name
-        string presentation
+        string label
     }
 
     OptionValue {
         string name
-        string presentation
+        string label
     }
 ```
 
@@ -607,9 +607,9 @@ erDiagram
 ```typescript Admin SDK
 const shoes = await adminClient.productTypes.create({
   name: 'Footwear',
-  option_type_ids: ['optt_size', 'optt_color'],
+  option_type_ids: ['opt_size', 'opt_color'],
   category_ids: ['ctg_footwear'],
-  delivery_profile_id: 'dp_standard',
+  delivery_profile_id: 'fp_standard',
   custom_field_definitions: [
     { id: 'cfdef_material', required: true, sort_order: 0 },
   ],
@@ -628,9 +628,9 @@ curl -X POST 'https://api.mystore.com/api/v3/admin/product_types' \
   -H 'Content-Type: application/json' \
   -d '{
     "name": "Footwear",
-    "option_type_ids": ["optt_size", "optt_color"],
+    "option_type_ids": ["opt_size", "opt_color"],
     "category_ids": ["ctg_footwear"],
-    "delivery_profile_id": "dp_standard"
+    "delivery_profile_id": "fp_standard"
   }'
 ```
 

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

@@ -62,16 +62,17 @@ not a partial result computed from the half the server understood.
 
 ## Metrics
 
-A metric is an aggregate over one **base** relation. Core registers four, in
-three families:
+A metric is an aggregate over one **base** relation. Core registers five, in
+four families:
 
 | Family | Bases | Anchored on |
 |--------|-------|-------------|
 | `sales` | `:orders`, `:line_items` | when the order completed |
 | `payments` | `:payments` | when the payment was taken |
 | `inventory` | `:stock_movements` | when the stock moved |
+| `carts` | `:carts` | when the cart was started |
 
-A query draws from **one family only**. The three answer different questions on
+A query draws from **one family only**. The families answer different questions on
 different clocks, so a payment total beside a units-received count is two
 reports wearing one table — the query refuses the mix rather than inventing a
 join between grains that have no honest relationship.

package/dist/developer/core-concepts/returns-exchanges-claims.md

@@ -56,7 +56,7 @@ Customers can open a return or a claim on their own order and follow its progres
 // Request a return — items refer to units that shipped, not cart line items
 const returnRequest = await client.orders.returns.create('or_xxx', {
   items: [{ fulfillment_item_id: 'fi_xxx', quantity: 1 }],
-  reason_id: 'rsn_xxx',
+  reason_id: 'rar_xxx',
   memo: 'Too small',
 })
 
@@ -80,7 +80,7 @@ curl -X POST 'https://api.mystore.com/api/v3/store/orders/or_xxx/returns' \
 ```
 
 
-Claim types are `damaged`, `missing`, `wrong_item` and `other` out of the box, and a store can add its own.
+Claim reasons are records each store owns. New stores are seeded with *Arrived damaged*, *Never arrived*, *Wrong item sent*, *Missing item from order* and *Item not as described*, and merchants can add, rename or remove their own.
 
 ## Processing a return
 
@@ -165,9 +165,9 @@ What to do about a claim is decided when you resolve it, not when the customer o
 
 
 ```typescript Admin SDK
-await adminClient.orders.claims.approve('or_xxx', 'clm_xxx')
+await adminClient.orders.claims.approve('or_xxx', 'claim_xxx')
 
-await adminClient.orders.claims.resolve('or_xxx', 'clm_xxx', {
+await adminClient.orders.claims.resolve('or_xxx', 'claim_xxx', {
   resolution: 'refund_and_replacement',   // or 'refund', 'replacement'
   refund_method: 'store_credit',
   replacement_line_item_ids: ['li_xxx'],
@@ -175,10 +175,10 @@ await adminClient.orders.claims.resolve('or_xxx', 'clm_xxx', {
 ```
 
 ```bash cURL
-curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/claims/clm_xxx/approve' \
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/claims/claim_xxx/approve' \
   -H 'X-Spree-API-Key: sk_xxx'
 
-curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/claims/clm_xxx/resolve' \
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/claims/claim_xxx/resolve' \
   -H 'X-Spree-API-Key: sk_xxx' \
   -H 'Content-Type: application/json' \
   -d '{
@@ -240,7 +240,7 @@ curl 'https://api.mystore.com/api/v3/admin/claims?q[created_at_gt]=2026-08-01' \
 
 ## Return policy
 
-Spree ships no built-in return window. Whether a customer may open a return is store policy, and it's checked when the return is created — so you can hold customers to a 30-day window while letting staff make an exception for a good customer, and vary the rule by market where local law requires it.
+Spree ships one built-in rule: a return window, counted from when the order was placed and set per market (30 days by default). Whether a customer may open a return is store policy, and it's checked when the return is created — so you can hold customers to that window while letting staff make an exception for a good customer, and vary the rule by market where local law requires it.
 
 Set the return window per market, or express a more specific rule in your own application. See [Configuration](../customization/configuration.md) and [Services & Workflows](../customization/workflows.md).
 

package/dist/developer/core-concepts/search-filtering.md

@@ -180,7 +180,7 @@ const filters = await client.products.filters()
 //   filters: [
 //     { id: 'price', type: 'price_range', min: 9.99, max: 199.99, currency: 'USD' },
 //     { id: 'availability', type: 'availability', options: [{ id: 'in_stock', count: 42 }, { id: 'out_of_stock', count: 3 }] },
-//     { id: 'optt_xxx', type: 'option', name: 'size', label: 'Size', kind: 'dropdown', options: [{ id: 'optval_xxx', name: 'Small', label: 'Small', position: 1, color_code: null, image_url: null, count: 12 }] },
+//     { id: 'opt_xxx', type: 'option', name: 'size', label: 'Size', kind: 'dropdown', options: [{ id: 'optval_xxx', name: 'Small', label: 'Small', position: 1, color_code: null, image_url: null, count: 12 }] },
 //     { id: 'categories', type: 'category', options: [{ id: 'ctg_xxx', name: 'Clothing', permalink: 'clothing', count: 45 }] },
 //   ],
 //   sort_options: [{ id: 'manual' }, { id: 'price' }, { id: '-price' }],
@@ -276,10 +276,10 @@ See [Querying](../../api-reference/store-api/querying.md) for the full list of f
 
 ## Search Providers
 
-Spree uses a pluggable search provider architecture. The default provider uses SQL (ILIKE + Ransack). For production catalogs with 1,000+ products, we recommend switching to [Meilisearch](../../integrations/search/meilisearch.md) for typo tolerance, relevance ranking, and faster faceted search.
+Spree uses a pluggable search provider architecture. The default provider uses SQL (ILIKE + Ransack). For production catalogs with 1,000+ products, we recommend installing the `spree_meilisearch` gem and switching to [Meilisearch](../../integrations/search/meilisearch.md) for typo tolerance, relevance ranking, and faster faceted search.
 
 ```ruby server/config/initializers/spree.rb
-Spree.search_provider = 'Spree::SearchProvider::Meilisearch'
+Spree.search_provider = 'SpreeMeilisearch::SearchProvider'
 ```
 
 No client-side or API changes are needed — the same `q[search]`, filter params, and sort options work with any provider.