@spree/docs 0.1.230 → 0.1.232

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

@@ -83,6 +83,17 @@ spree api post /webhook_endpoints -d '{
 }'
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/webhook_endpoints' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "url": "https://example.com/webhooks/spree",
+    "subscriptions": ["order.*", "product.created"],
+    "active": true
+  }'
+```
+
 
 > **WARNING:** The `secret_key` is returned **only once**, in the create response. Save it immediately — it can't be retrieved later and is required to verify webhook signatures.
 
@@ -113,6 +124,13 @@ spree api patch /webhook_endpoints/whe_xxx \
   -d '{"subscriptions": ["order.placed", "order.canceled"]}'
 ```
 
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/webhook_endpoints/whe_xxx' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "subscriptions": ["order.placed", "order.canceled"] }'
+```
+
 
 The `subscriptions` array accepts exact event names and wildcard patterns:
 
@@ -128,7 +146,7 @@ The `subscriptions` array accepts exact event names and wildcard patterns:
 
 Each webhook delivery sends a JSON payload with the following structure. The `data` object uses the same [Store API V3 serializers](../../api-reference/introduction.md) as the REST API, so webhook payloads and API responses share the same schema:
 
-```json
+```json Payload
 {
   "id": "550e8400-e29b-41d4-a716-446655440000",
   "name": "order.placed",
@@ -188,7 +206,7 @@ The [Spree Storefront](https://github.com/spree/storefront) includes a ready-mad
 
 Use `@spree/sdk/webhooks` for framework-agnostic verification:
 
-```typescript
+```typescript Store SDK
 import { verifyWebhookSignature } from '@spree/sdk/webhooks'
 import type { WebhookEvent } from '@spree/sdk/webhooks'
 import type { Order } from '@spree/sdk'
@@ -211,7 +229,7 @@ app.post('/webhooks/spree', async (req, res) => {
 
 #### Ruby
 
-```ruby
+```ruby server/app/controllers/webhooks_controller.rb
 class WebhooksController < ApplicationController
   skip_before_action :verify_authenticity_token
 
@@ -272,6 +290,14 @@ spree api get /webhook_endpoints/whe_xxx/deliveries -q event_name_eq=order.place
 spree api post /webhook_endpoints/whe_xxx/deliveries/whd_xxx/redeliver
 ```
 
+```bash cURL
+curl 'https://api.mystore.com/api/v3/admin/webhook_endpoints/whe_xxx/deliveries?q[event_name_eq]=order.placed' \
+  -H 'X-Spree-API-Key: sk_xxx'
+
+curl -X POST 'https://api.mystore.com/api/v3/admin/webhook_endpoints/whe_xxx/deliveries/whd_xxx/redeliver' \
+  -H 'X-Spree-API-Key: sk_xxx'
+```
+
 
 ### Delivery Attributes
 
@@ -339,6 +365,17 @@ spree api post /webhook_endpoints -d '{
 spree api post /webhook_endpoints/whe_xxx/send_test
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/webhook_endpoints' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "url": "https://your-ngrok-url.ngrok.io/webhooks",
+    "subscriptions": ["order.*"],
+    "active": true
+  }'
+```
+
 
 `send_test` delivers a synthetic `webhook.test` event so you can verify the endpoint is reachable and your signature-verification code works, without having to trigger a real order.
 
@@ -386,6 +423,11 @@ const failed = deliveries[0]
 spree api get /webhook_endpoints/whe_xxx/deliveries -q success_eq=false
 ```
 
+```bash cURL
+curl 'https://api.mystore.com/api/v3/admin/webhook_endpoints/whe_xxx/deliveries?q[success_eq]=false' \
+  -H 'X-Spree-API-Key: sk_xxx'
+```
+
 
 ## Related Documentation
 

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

@@ -53,14 +53,14 @@ npx create-spree-app@latest my-store --no-storefront --no-sample-data --no-start
 ```text
 my-store/
 ├── docker-compose.yml        # Spree backend (prebuilt image) + Postgres + Meilisearch
-├── docker-compose.dev.yml    # Alternative: build from local backend/
+├── 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
-├── backend/                  # Full Rails app — the Spree API (from spree/spree-starter)
+├── server/                  # Full Rails app — the Spree API (from spree/spree-starter)
 │   ├── Gemfile
 │   ├── Dockerfile            # Also builds the production image (API + dashboard)
 │   ├── config/
@@ -84,18 +84,18 @@ my-store/
 
 ## Customizing the Spree API
 
-The `backend/` directory is the Spree API — a full Rails application with Spree installed (cloned from [spree-starter](https://github.com/spree/spree-starter)) serving the Store and Admin APIs your storefront and dashboard talk to, plus background jobs and transactional emails. By default, the project runs it from a prebuilt Docker image. To switch to building from your local copy:
+The `server/` directory is the Spree API — a full Rails application with Spree installed (cloned from [spree-starter](https://github.com/spree/spree-starter)) serving the Store and Admin APIs your storefront and dashboard talk to, plus background jobs and transactional emails. By default, the project runs it from a prebuilt Docker image. To switch to building from your local copy:
 
 ```bash
 npx spree eject
 ```
 
-This replaces `docker-compose.yml` with a version that builds from `backend/`, rebuilds the image, and restarts services. You can then:
+This replaces `docker-compose.yml` with a version that builds from `server/`, rebuilds the image, and restarts services. You can then:
 
-- **Add gems** to `backend/Gemfile`
-- **Override models** with decorators in `backend/app/models/`
-- **Add controllers** in `backend/app/controllers/`
-- **Configure Spree** in `backend/config/initializers/spree.rb`
+- **Add gems** to `server/Gemfile`
+- **Override models** with decorators in `server/app/models/`
+- **Add controllers** in `server/app/controllers/`
+- **Configure Spree** in `server/config/initializers/spree.rb`
 - **Add migrations** with `spree generate migration AddFooToSpreeBars foo:string` (runs inside the container)
 
 See the [Customization Guide](../customization.md) for more details.
@@ -109,7 +109,7 @@ The project includes [@spree/cli](../cli/quickstart.md) for managing your Spree
 | `spree dev` | Run the app in the foreground — streams logs, Ctrl+C stops it. First run completes setup automatically; co-runs the React Dashboard dev server when `apps/dashboard` exists |
 | `spree stop` | Stop backend services |
 | `spree update` | Pull latest Spree image and restart (runs migrations automatically) |
-| `spree eject` | Switch from prebuilt image to building from `backend/` |
+| `spree eject` | Switch from prebuilt image to building from `server/` |
 | `spree add dashboard` | Add the React Dashboard to an existing project |
 | `spree build --production` | Build the production image — the Spree API plus your dashboard, in one |
 | `spree logs` | View backend logs |
@@ -162,7 +162,7 @@ SPREE_VERSION_TAG=5.4
 
 ## Deployment
 
-The project deploys as **one image**: `backend/Dockerfile` builds the Spree API together with your React Dashboard (when `apps/dashboard` exists), served same-origin at `/dashboard` — no CORS, no cookie configuration, no second service.
+The project deploys as **one image**: `server/Dockerfile` builds the Spree API together with your React Dashboard (when `apps/dashboard` exists), served same-origin at `/dashboard` — no CORS, no cookie configuration, no second service.
 
 - **Render** — the `render.yaml` at the project root is a ready Blueprint: one Docker service built straight from your repo, migrations run on boot.
 - **Anywhere else** — `spree build --production` builds the same image locally; push it to a registry and run it on any Docker host.

package/dist/developer/dashboard/deployment.md

@@ -22,13 +22,13 @@ The official image contains the *stock* dashboard. Once you've customized yours
 spree build --production            # optionally --tag registry/repo:tag
 ```
 
-The Dockerfile normalizes its own build context: built from the project root it detects the layout (`backend/` = the Rails app, `apps/dashboard/` = your dashboard) and builds *your* dashboard into the image — no flags, no named contexts. Without the CLI, the equivalent is:
+The Dockerfile normalizes its own build context: built from the project root it detects the layout (`server/` = the Rails app, `apps/dashboard/` = your dashboard) and builds *your* dashboard into the image — no flags, no named contexts. Without the CLI, the equivalent is:
 
 ```bash
-docker build . -f backend/Dockerfile -t my-shop-spree:latest
+docker build . -f server/Dockerfile -t my-shop-spree:latest
 ```
 
-Inside the dashboard stage the build runs with `VITE_BASE_PATH=/dashboard/` (asset URLs resolve under the mount) and `VITE_SPREE_API_URL` unset (API calls stay origin-relative); the Node toolchain lives only in that throw-away stage. Projects **without** `apps/dashboard/` get the stock dashboard baked instead — and if your `backend/Dockerfile` predates this layout support, the command warns instead of silently shipping the stock dashboard over your customized one (update it from the spree-starter template).
+Inside the dashboard stage the build runs with `VITE_BASE_PATH=/dashboard/` (asset URLs resolve under the mount) and `VITE_SPREE_API_URL` unset (API calls stay origin-relative); the Node toolchain lives only in that throw-away stage. Projects **without** `apps/dashboard/` get the stock dashboard baked instead — and if your `server/Dockerfile` predates this layout support, the command warns instead of silently shipping the stock dashboard over your customized one (update it from the spree-starter template).
 
 ## Static host / CDN — the alternative
 
@@ -53,7 +53,7 @@ The Blueprint that `create-spree-app` places at the project root deploys the bac
 
 ```yaml
 runtime: docker
-dockerfilePath: ./backend/Dockerfile
+dockerfilePath: ./server/Dockerfile
 dockerContext: .
 ```
 

package/dist/developer/dashboard/recipes/attribute-end-to-end.md

@@ -28,7 +28,7 @@ Lead time is a column because its whole point is the query: *"show me everything
 
 ## 1. Backend
 
-Four small pieces — each one unlocks a specific frontend capability. In a host app these live in `backend/` (or `api/`); in a distributed plugin, in the Rails engine half.
+Four small pieces — each one unlocks a specific frontend capability. In a host app these live in `server/` (or `api/`); in a distributed plugin, in the Rails engine half.
 
 **The column** (with an index — you're adding it *because* it will be queried):
 

package/dist/developer/deployment/docker.md

@@ -13,7 +13,7 @@ If you haven't ejected yet, do that first:
 spree eject
 ```
 
-This generates the app source — including its production `Dockerfile` — in `backend/`. Make your customizations, then build:
+This generates the app source — including its production `Dockerfile` — in `server/`. Make your customizations, then build:
 
 ```bash
 spree build --production                                  # → <project>-spree:latest
@@ -23,7 +23,7 @@ spree build --production --tag registry.example.com/my-store:v42
 Or with plain Docker, from the project root:
 
 ```bash
-docker build . -f backend/Dockerfile -t my-store
+docker build . -f server/Dockerfile -t my-store
 ```
 
 Both produce the same image — and it's exactly what Render and Railway build from your repository. Migrations run automatically on boot.

package/dist/developer/how-to/custom-promotion.md

@@ -21,7 +21,7 @@ Rules determine whether a promotion is eligible for a given order. Each rule imp
 
 Create a new class inheriting from `Spree::PromotionRule`:
 
-```ruby app/models/spree/promotion/rules/minimum_quantity.rb
+```ruby server/app/models/spree/promotion/rules/minimum_quantity.rb
 module Spree
   class Promotion
     module Rules
@@ -67,7 +67,7 @@ The `options` hash passed to `eligible?` can include `:user`, `:email`, and othe
 
 Rules use Spree's preference system for configuration. Each preference creates getter/setter methods automatically:
 
-```ruby
+```ruby server/app/models/spree/promotion/rules/minimum_quantity.rb
 preference :amount, :decimal, default: 100.00
 preference :operator, :string, default: 'gte'
 preference :category_ids, :array, default: []
@@ -82,7 +82,7 @@ Available types: `:string`, `:integer`, `:decimal`, `:boolean`, `:array`.
 
 ### Step 2: Register the Rule
 
-```ruby config/initializers/spree.rb
+```ruby server/config/initializers/spree.rb
 Rails.application.config.after_initialize do
   Spree.promotions.rules << Spree::Promotion::Rules::MinimumQuantity
 end
@@ -90,11 +90,31 @@ end
 
 Registered rules are discoverable at `/api/v3/admin/promotion_rules/types` together with their preference schema, and the dashboard's promotion editor is built on that endpoint — your rule appears there with a generated preferences form, no UI work needed.
 
+The API names your rule by its **shorthand** — the class name demodulized and underscored, so `Spree::Promotion::Rules::MinimumQuantity` is `minimum_quantity`. That is what `/types` returns, what a promotion payload sends, and what the locale key below is named after. The Ruby class name is never accepted on the wire:
+
+
+```typescript Admin SDK
+await adminClient.promotions.rules.create('promo_xxx', {
+  type: 'minimum_quantity',
+  preferences: { amount: 3 },
+})
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/promotions/promo_xxx/promotion_rules' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "type": "minimum_quantity", "preferences": { "amount": 3 } }'
+```
+
+
+Override `self.api_type` on the class when you need the wire value to stay put across a rename.
+
 ### Step 3: Add Translations
 
 The rule's display name and description in the dashboard come from your locale file:
 
-```yaml config/locales/en.yml
+```yaml server/config/locales/en.yml
 en:
   spree:
     promotion_rule_types:
@@ -107,7 +127,7 @@ en:
 
 When your rule targets specific line items (not the whole order), implement `actionable?` so that item-level actions only discount matching items:
 
-```ruby app/models/spree/promotion/rules/brand.rb
+```ruby server/app/models/spree/promotion/rules/brand.rb
 module Spree
   class Promotion
     module Rules
@@ -153,7 +173,7 @@ Three declarations make a discount action:
 | `compute_amount(adjustable)` | The discount for one adjustable — a line item, fulfillment, or the order, matching your scope. Return a **negative** amount, or zero for "no discount". |
 | `perform(options = {})` | Called when the promotion is activated. For discount actions, delegate to `apply_via_adjuster(options)`. |
 
-```ruby app/models/spree/promotion/actions/tiered_discount.rb
+```ruby server/app/models/spree/promotion/actions/tiered_discount.rb
 module Spree
   class Promotion
     module Actions
@@ -195,7 +215,7 @@ With `discount_scope :order`, the winning amount is shared out proportionally ac
 
 For actions that don't create discounts (awarding points, sending notifications), implement `perform` alone:
 
-```ruby app/models/spree/promotion/actions/add_loyalty_points.rb
+```ruby server/app/models/spree/promotion/actions/add_loyalty_points.rb
 module Spree
   class Promotion
     module Actions
@@ -219,13 +239,13 @@ end
 
 ### Register and Translate
 
-```ruby config/initializers/spree.rb
+```ruby server/config/initializers/spree.rb
 Rails.application.config.after_initialize do
   Spree.promotions.actions << Spree::Promotion::Actions::TieredDiscount
 end
 ```
 
-```yaml config/locales/en.yml
+```yaml server/config/locales/en.yml
 en:
   spree:
     promotion_action_types:
@@ -240,7 +260,7 @@ Like rules, registered actions surface automatically in the dashboard's promotio
 
 Not every charge or reduction is a promotion. A gift wrap fee, a payment surcharge, or loyalty pricing has no rules, no coupon codes, and no competition — it just needs to be on the order whenever it applies. That's an **adjuster**: a class invoked on every recalculation that owns a family of [Fee](../core-concepts/fees.md) or [Discount](../core-concepts/discounts.md) rows.
 
-```ruby app/models/my_app/adjusters/gift_wrap.rb
+```ruby server/app/models/my_app/adjusters/gift_wrap.rb
 module MyApp
   module Adjusters
     class GiftWrap < Spree::Adjusters::Base
@@ -258,7 +278,7 @@ module MyApp
 end
 ```
 
-```ruby config/initializers/spree.rb
+```ruby server/config/initializers/spree.rb
 Rails.application.config.after_initialize do
   Spree.adjusters << MyApp::Adjusters::GiftWrap
 end
@@ -272,7 +292,7 @@ Custom discounts work the same way, writing `order.discounts` rows with your own
 
 ## Testing
 
-```ruby spec/models/spree/promotion/rules/minimum_quantity_spec.rb
+```ruby server/spec/models/spree/promotion/rules/minimum_quantity_spec.rb
 require 'spec_helper'
 
 RSpec.describe Spree::Promotion::Rules::MinimumQuantity do
@@ -300,7 +320,7 @@ RSpec.describe Spree::Promotion::Rules::MinimumQuantity do
 end
 ```
 
-```ruby spec/models/spree/promotion/actions/tiered_discount_spec.rb
+```ruby server/spec/models/spree/promotion/actions/tiered_discount_spec.rb
 require 'spec_helper'
 
 RSpec.describe Spree::Promotion::Actions::TieredDiscount do

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

@@ -44,7 +44,7 @@ spree eject
 
 ### Adding gems
 
-1. Add the following code to your `backend/Gemfile`:
+1. Add the following code to your `server/Gemfile`:
 
     ```ruby
     source "https://license:#{ENV['KEYGEN_LICENSE_KEY']}@rubygems.pkg.keygen.sh/#{ENV['KEYGEN_ACCOUNT_ID']}" do
@@ -66,10 +66,10 @@ spree eject
 >       In that case the Gemfile reads `KEYGEN_LICENSE_KEY` / `KEYGEN_ACCOUNT_ID` directly from
 >       your shell environment.
 
-    Wrap **every** `bundle install` in your `backend/Dockerfile` with the secret mounts. There
+    Wrap **every** `bundle install` in your `server/Dockerfile` with the secret mounts. There
     are usually two — one in the build stage and one in the dev stage:
 
-    ```dockerfile backend/Dockerfile
+    ```dockerfile server/Dockerfile
     COPY .ruby-version Gemfile Gemfile.lock ./
     RUN bundle install # [!code --]
     RUN --mount=type=secret,id=keygen_license_key,env=KEYGEN_LICENSE_KEY,required=false \ # [!code ++]
@@ -185,7 +185,7 @@ development by default, but `.lvh.me` (and your production domain) are not — r
 `app.lvh.me` are rejected with a "Blocked hosts" error until you allow them. Add your root
 domain to `config/environments/development.rb`:
 
-```ruby backend/config/environments/development.rb
+```ruby server/config/environments/development.rb
 if (root_domain = ENV['SPREE_ROOT_DOMAIN']).present?
   config.hosts << ".#{root_domain}"
 end
@@ -200,7 +200,7 @@ to your customer user model automatically. You then need to **remove the `:valid
 manually. `:validatable` validates the user's email uniqueness globally; the concern re-validates
 it in the scope of the tenant instead, so the same email can exist across different tenants.
 
-```ruby backend/app/models/spree/user.rb
+```ruby server/app/models/spree/user.rb
 class Spree::User < Spree.base_class
   include Spree::UserAddress
   include Spree::UserMethods
@@ -222,7 +222,7 @@ The generator also changes your admin user model's base class from `Spree.base_c
 `Spree::Base`. If your `admin_user.rb` exists, this is applied automatically; otherwise make the
 change yourself:
 
-```ruby backend/app/models/spree/admin_user.rb
+```ruby server/app/models/spree/admin_user.rb
 class Spree::AdminUser < Spree.base_class # [!code --]
 class Spree::AdminUser < Spree::Base # [!code ++]
   include Spree::AdminUserMethods

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

@@ -61,7 +61,7 @@ npm run test:e2e
 
 ### A `create-spree-app` project's backend
 
-A project scaffolded with [`create-spree-app`](../../create-spree-app/quickstart.md) has its customizable Spree in `backend/` (built from `backend/Dockerfile`) and this storefront in `apps/storefront/`. Build that backend into a local image and point the suite at it — this is what tests the storefront against the **exact Spree you deploy**, extensions and all:
+A project scaffolded with [`create-spree-app`](../../create-spree-app/quickstart.md) has its customizable Spree in `server/` (built from `server/Dockerfile`) and this storefront in `apps/storefront/`. Build that backend into a local image and point the suite at it — this is what tests the storefront against the **exact Spree you deploy**, extensions and all:
 
 ```bash
 # From the project root — build the customized backend image
@@ -74,7 +74,7 @@ npm run test:e2e
 npm run e2e:down
 ```
 
-> **NOTE:** New `create-spree-app` projects wire this into the generated storefront CI workflow automatically — the workflow builds `backend/Dockerfile` and runs the storefront E2E against that image rather than stock Spree.
+> **NOTE:** New `create-spree-app` projects wire this into the generated storefront CI workflow automatically — the workflow builds `server/Dockerfile` and runs the storefront E2E against that image rather than stock Spree.
 
 ### Interactive / manual
 

package/package.json

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