@spree/docs 0.1.289 → 0.1.291

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

@@ -239,7 +239,9 @@ sequenceDiagram
 
 The frontend calls the API to create a Payment Session for a specific payment method and order. Spree calls the gateway to create a provider-side session (e.g., Stripe PaymentIntent, Adyen Session) and returns the session data including a `client_secret` for the frontend SDK.
 
-    > **INFO:** The payment session should be created (or recreated) **after** the shipping method is selected, so the amount includes shipping costs. If the order total changes (e.g., customer selects a different shipping rate or applies a coupon), create a new payment session with the updated amount.
+    > **INFO:** Create the payment session **after** the shipping method is selected, so the amount includes shipping costs. If the order total changes (a different shipping rate, a coupon), create the session again.
+
+    A cart has at most one open session per gateway. Asking Stripe for a session again (a reloaded checkout page, a second tab) cancels the cart's open session and opens a new one, because every open Stripe PaymentIntent can be paid on its own. If that session has already been paid, the request fails with a `gateway_error` and the paid session stays open. Once the order is placed, a background job cancels any session still pending — for example, one left behind when the customer switched to a different payment method — so it can no longer be paid.
 
   **Step 2: Customer pays on the frontend**
 
@@ -373,8 +375,9 @@ stateDiagram-v2
 ```
 
 > **NOTE:** There is no cancel endpoint. A session reaches `canceled` when the provider
->   says so through its webhook, and `expired` when it passes `expires_at`.
->   Neither is something a storefront drives.
+>   says so through its webhook, or after the order is placed while the session
+>   is still pending with nothing paid through it. It reaches `expired` when it
+>   passes `expires_at`. Neither is something a storefront drives.
 
 #### API
 

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 **dashboard** and the marketplace **seller panel** are included in every project — there is no flag to add them.
+The **admin dashboard** is included in every project (skip it with `--no-dashboard` and the API still serves the built-in one at `/dashboard`). The installer asks whether to add the **seller panel** — a dedicated panel where marketplace vendors manage their products, orders and settings. Answer yes only if you run a marketplace; you can add it later with `spree add seller-dashboard`.
 
 ## Prerequisites
 
@@ -30,14 +30,14 @@ The **dashboard** and the marketplace **seller panel** are included in every pro
 All prompts can be skipped with flags for non-interactive (CI/CD) usage:
 
 ```bash
-npx create-spree-app@latest my-store --no-storefront --no-sample-data --no-start
+npx create-spree-app@latest my-store --no-seller-dashboard --no-storefront --no-start
 ```
 
 | Flag | Description |
 |------|-------------|
-| `--react-dashboard` | No-op — the dashboard is always included. Kept so existing scripts keep working |
+| `--no-dashboard` | Skip the admin dashboard app — the API still serves the built-in one at `/dashboard` |
+| `--no-seller-dashboard` | Skip the marketplace seller panel |
 | `--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 |
 | `--port <number>` | Port for the Spree backend (default: `3000`) |
 | `--use-npm` | Use npm as package manager |
@@ -58,9 +58,9 @@ my-store/
 │   ├── Dockerfile            # Also builds the production image (API + dashboard)
 │   └── Gemfile
 ├── apps/
-│   ├── dashboard/            # Admin dashboard (React)
+│   ├── dashboard/            # Admin dashboard (unless --no-dashboard)
 │   │   └── .env.local        # Dev proxy target — no credentials
-│   ├── seller-dashboard/     # Seller panel, for marketplaces (React)
+│   ├── seller-dashboard/     # Seller panel, for marketplaces (unless --no-seller-dashboard)
 │   └── storefront/           # Next.js storefront (unless --no-storefront)
 │       └── .env.local        # API URL + publishable key
 ├── .env                      # SECRET_KEY_BASE, encryption keys, SPREE_PORT, SPREE_VERSION_TAG, SPREE_SAMPLE_DATA
@@ -109,11 +109,12 @@ The project includes [@spree/cli](../cli/quickstart.md) for managing your Spree
 
 | Command | Description |
 |---------|-------------|
-| `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 dev` | Run the app in the foreground — streams logs, Ctrl+C stops it. First run completes setup automatically; co-runs the Admin 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 `server/` |
-| `spree add dashboard` | Add the React Dashboard to an existing project |
+| `spree add dashboard` | Add the Admin Dashboard to an existing project, to customize it |
+| `spree add seller-dashboard` | Add the marketplace seller panel to an existing project |
 | `spree build --production` | Build the production image — the Spree API plus your dashboard, in one |
 | `spree logs` | View backend logs |
 | `spree logs worker` | View background jobs logs |
@@ -160,7 +161,7 @@ SPREE_VERSION_TAG=5.4
 
 ## Deployment
 
-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.
+The project deploys as **one image**: `server/Dockerfile` builds the Spree API together with your Admin 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/how-to/custom-payment-method.md

@@ -158,12 +158,22 @@ class MyGateway < Spree::PaymentMethod
     payment_session
   end
 
+  # Cancel a session the customer left behind, so it can no longer be paid.
+  # Spree calls this from a background job, once the order is placed, for
+  # every session still pending with nothing paid through it.
+  def cancel_payment_session(payment_session:)
+    MyProvider::Client.new(preferred_api_key).cancel_session(payment_session.external_id)
+    payment_session.cancel
+  end
+
   def payment_icon_name
     'my-gateway'
   end
 end
 ```
 
+> **WARNING:** If your provider lets each open session be paid on its own (as Stripe does with PaymentIntents), a customer with two open sessions can be charged twice — for example, with checkout open in two tabs. Have `create_payment_session` cancel the cart's open sessions for your gateway before opening a new one, and implement `cancel_payment_session`. Leave a session the provider has already accepted, and do not open another. The built-in Stripe gateway does both. If you leave out `cancel_payment_session`, sessions still pending when the order is placed stay open at your provider.
+
 ### How the Frontend Uses It
 
 The frontend creates a session, then uses the provider's SDK to collect payment:
@@ -194,7 +204,7 @@ const completed = await client.carts.paymentSessions.complete(
 const order = await client.carts.complete(cart.id, options)
 ```
 
-> **INFO:** **Important:** Always create the payment session **after** shipping is selected. If the order total changes (shipping rate change, coupon applied), create a new payment session with the updated amount. The `complete` call in step 5 only handles payment — step 6 finalizes the order.
+> **INFO:** **Important:** Always create the payment session **after** shipping is selected. If the order total changes (shipping rate change, coupon applied), update the session with the new amount (`client.carts.paymentSessions.update`) rather than creating another one. The `complete` call in step 5 only handles payment — step 6 finalizes the order.
 
 ## Step 4: Handle Webhooks (Recommended)
 

package/package.json

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