@spree/docs 0.1.240 → 0.1.242

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

@@ -11,7 +11,7 @@ Payment methods typically represent a payment gateway. Gateways will process car
 
 The `Payment` model in Spree tracks payments against [Orders](orders.md). Payments relate to a `source` which indicates how the payment was made, and a `PaymentMethod`, indicating the processor used for this payment.
 
-When a payment is created, it is given a unique, 8-character identifier. This is used when sending the payment details to the payment processor. Without this identifier, some payment gateways mistakenly reported duplicate payments.
+A payment's `number` is derived from what it belongs to — an order `R1001` numbers its payments `R1001-P1`, `R1001-P2` — so a gateway reference traces straight back to the order without a lookup.
 
 ### Payment Architecture Diagram
 
@@ -20,9 +20,8 @@ erDiagram
     Payment {
         string number
         decimal amount
-        string state
+        string status
         string response_code
-        string avs_response
         string source_type
         string source_id
     }
@@ -32,7 +31,7 @@ erDiagram
         string type
         string description
         boolean active
-        string display_on
+        boolean storefront_visible
         integer position
     }
 
@@ -58,11 +57,12 @@ erDiagram
     }
 
     CreditCard {
-        string last_digits
-        string cc_type
+        string last4
+        string brand
         integer month
         integer year
         string name
+        boolean default
     }
 
     GatewayCustomer {
@@ -124,12 +124,12 @@ A `PaymentMethod` can have the following attributes:
 | `name`       | The visible name for this payment method                                                      | `Check`                |
 | `description`| The description for this payment method                                                       | `Pay by check.`        |
 | `active`     | Whether or not this payment method is active. Set it `false` to hide it in the Store API.         | `true`                 |
-| `display_on` | Determines where the payment method can be visible. Values can be `front_end` (Store API), `back_end` (admin panel only), or `both` (both). | `both`                 |
+| `storefront_visible` | Whether customers can choose this method. Leave it off for a method only staff use. | `true`                 |
 | `position`   | The position of the payment method in lists. Lower numbers appear first.                      | `1`                    |
 
 > **INFO:** Each payment method is associated to a Store, so you can decide which Payment Method will appear on which Store. This allows you to create different experiences for your customers in different countries.
 
-### Session-based vs Legacy Payment Methods
+### Session-based vs direct payment methods
 
 Payment methods indicate whether they use the modern session-based flow via the `session_required?` method:
 
@@ -140,13 +140,13 @@ Payment methods indicate whether they use the modern session-based flow via the
 | `payment_session_class` | Returns the STI subclass of `Spree::PaymentSession` for this gateway (e.g., `Spree::PaymentSessions::Stripe`). | `nil` |
 | `payment_setup_session_class` | Returns the STI subclass of `Spree::PaymentSetupSession` for this gateway. | `nil` |
 
-Modern gateways like Stripe and Adyen set `session_required?` to `true`. The Store API serializer includes this as the `session_required` field so your frontend knows which flow to use.
+Gateways like Stripe and Adyen set `session_required?` to `true`; offline methods leave it `false`. Neither path is deprecated. The Store API serializer includes this as the `session_required` field so your frontend knows which flow to use.
 
-### Non-Session Payment Methods (Manual/Offline)
+### Direct payment methods (manual and offline)
 
 Payment methods where `session_required?` returns `false` don't need a payment session. These are typically offline or manual payment methods such as:
 
-- **Check** — built-in (`Spree::PaymentMethod::Check`)
+- **Check** — built in
 - **Cash on Delivery** — customer pays upon delivery
 - **Bank Transfer / Wire** — customer transfers money to a bank account
 - **Purchase Order** — common in B2B, customer provides a PO number
@@ -180,9 +180,16 @@ curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/payments' \
 ```
 
 
-The payment is created in `checkout` state. When the order transitions to `complete`, Spree calls `process_payments!` which runs the payment method's `authorize` (or `purchase` if auto-capture is enabled). For manual payment methods like Check, this is a no-op that succeeds immediately — the payment moves to `pending` (or `completed` with auto-capture), allowing the order to complete.
+The payment starts at `checkout`. Completing the cart processes it — for a manual method there is no provider to call, so it succeeds immediately and lands on `pending`, or `completed` when the store charges at checkout.
+
+Once the money actually arrives — the cheque clears, the transfer lands, the
+driver is paid — staff capture the payment from the dashboard, or you do it
+through the Admin API:
 
-The merchant can later capture or void the payment from the Admin Panel once the actual payment is received (e.g., check arrives, bank transfer clears, cash is collected on delivery).
+```typescript Admin SDK
+await adminClient.orders.payments.capture(orderId, paymentId)
+await adminClient.orders.payments.void(orderId, paymentId)
+```
 
 ## Payment Flow
 
@@ -247,7 +254,7 @@ After the customer completes payment, the frontend calls the Complete Payment Se
 
   **Step 4: Complete Order**
 
-The frontend calls `POST /carts/:id/complete` to finalize the order. Spree validates the order is ready (addresses, fulfillments, payment), advances through any remaining checkout states, and marks the order as complete.
+The frontend calls `POST /carts/:id/complete` to finalize the order. Spree checks the cart has everything it needs — addresses, fulfillments, payment — and turns it into an order.
 
     This separation ensures the same flow works for all payment types — inline cards, offsite redirects, and wallet payments.
 
@@ -305,11 +312,11 @@ sequenceDiagram
     Spree API-->>Frontend: Cart (with embedded payment_methods, each carrying session_required)
 
     Frontend->>Spree API: POST /payments (payment_method_id)
-    Spree API->>Spree API: Create Payment (checkout state)
+    Spree API->>Spree API: Create payment (status checkout)
     Spree API-->>Frontend: Payment created
 
     Frontend->>Spree API: POST /carts/:id/complete
-    Spree API->>Spree API: process_payments! (authorize succeeds immediately)
+    Spree API->>Spree API: Process payment (succeeds immediately)
     Spree API->>Spree API: Payment → pending/completed
     Spree API-->>Frontend: Order completed
 ```
@@ -320,16 +327,18 @@ The frontend reads the cart's embedded `payment_methods` (returned by `GET /cart
 
   **Step 2: Create payment**
 
-The frontend calls `POST /payments` with the `payment_method_id`. Spree creates a `Payment` record in `checkout` state. No external provider interaction is needed.
+The frontend calls `POST /payments` with the `payment_method_id`. Spree creates a payment with status `checkout`. No provider is contacted.
+
+    Two refusals to handle: a method needing a session returns `payment_session_required`, and one unavailable for this order returns `payment_method_unavailable` — both HTTP 422 with that `code`.
 
   **Step 3: Complete order**
 
-The frontend completes the order. Spree's `process_payments!` runs the payment method's `authorize` (or `purchase` with auto-capture). For manual methods like Check, these return an immediate success — no external service is called. The payment transitions to `pending` (without auto-capture) or `completed` (with auto-capture) and the order completes. The merchant can later capture `pending` payments from the Admin Panel once the physical payment is received.
+The frontend completes the order. Completing the cart processes the payment. For a manual method there is nothing to call, so it succeeds immediately and lands on `pending`, or `completed` when the store charges at checkout. Staff capture `pending` payments from the dashboard once the money arrives.
 
 
 ### Payment Session
 
-A `PaymentSession` (`Spree::PaymentSession`) represents a server-side session with the payment gateway. It is the entry point for every payment attempt and holds the provider-specific data needed by the frontend SDK.
+A payment session represents a server-side session with the payment gateway. It is the entry point for every payment attempt and holds the provider-specific data needed by the frontend SDK.
 
 #### Attributes
 
@@ -342,6 +351,11 @@ A `PaymentSession` (`Spree::PaymentSession`) represents a server-side session wi
 | `external_data` | Provider-specific data including `client_secret` for frontend SDK | `{"client_secret": "pi_3ABC_secret_xyz"}` |
 | `customer_external_id` | The provider's customer ID | `cus_ABC123` |
 | `expires_at` | When the session expires | `2025-01-01T12:00:00Z` |
+| `cart_id` | The cart being paid for | `cart_k5nR8xLq` |
+
+> **NOTE:** A session also carries `order_id`, but during checkout there is no order yet —
+>   it reports the cart's ID until the cart completes. Read `cart_id` while paying,
+>   and `order_id` once you have an order.
 
 #### States
 
@@ -359,6 +373,10 @@ stateDiagram-v2
     processing --> expired
 ```
 
+> **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.
+
 #### API
 
 **Create a Payment Session:**
@@ -441,7 +459,7 @@ console.log(completed.status) // 'completed'
 ```
 
 ```bash cURL
-curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/payment_sessions/ps_xxx/complete' \
+curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/payment_sessions/ps_xxx/complete' \
   -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: CART_TOKEN' \
   -H 'Content-Type: application/json' \
@@ -487,10 +505,10 @@ class MyGateway < Spree::Gateway
 
     case event.type
     when 'payment.captured'
-      session = Spree::PaymentSession.find_by(external_id: event.payment_id)
+      session = payment_sessions.find_by(external_id: event.payment_id)
       { action: :captured, payment_session: session }
     when 'payment.failed'
-      session = Spree::PaymentSession.find_by(external_id: event.payment_id)
+      session = payment_sessions.find_by(external_id: event.payment_id)
       { action: :failed, payment_session: session }
     else
       nil # unsupported event
@@ -503,48 +521,55 @@ Supported actions: `:captured`, `:authorized`, `:failed`, `:canceled`.
 
 ### Payment
 
-Once a Payment Session is completed, Spree creates a `Payment` record (`Spree::Payment`) to track the result. The Payment is linked to the session via `response_code` matching the session's `external_id`.
+Once a payment session completes, Spree creates a payment to record the result,
+linked to the session by `response_code` matching its `external_id`.
 
 #### Attributes
 
-| Attribute         | Description                                                                 | Example Value       |
-|-------------------|-----------------------------------------------------------------------------|---------------------|
-| `number`          | A unique identifier for the payment.                                        | `PAB12CD34`         |
-| `source_type`     | The type of source used for the payment.                                    | `Spree::CreditCard` |
-| `source_id`       | The ID of the source used for the payment.                                  | `1`                 |
-| `amount`          | The amount of the payment.                                                  | `99.99`             |
-| `payment_method_id`| The ID of the payment method used.                                          | `2`                 |
-| `state`           | The current state of the payment (e.g., processing, completed, failed).     | `completed`         |
-| `response_code`   | The gateway transaction ID. Links to the Payment Session's `external_id`.   | `pi_3ABC123`        |
-| `avs_response`    | The address verification system response code.                              | `D`                 |
-
-#### Payment States
-
-After a Payment Session completes, the resulting Payment transitions through these states:
-
-```mermaid
-stateDiagram-v2
-    [*] --> checkout
-    checkout --> processing : process!
-    processing --> completed : purchase! succeeds
-    processing --> pending : authorize! succeeds
-    processing --> failed : payment declined
-    pending --> completed : capture!
-    pending --> void : void!
-    completed --> void : void!
-    checkout --> void : void!
-```
-
-| State | Description |
-|-------|-------------|
-| `checkout` | Initial state. The payment has been created but not yet processed. |
-| `processing` | The payment is being processed (temporary - prevents double submission). |
-| `pending` | The payment has been authorized but not yet captured. Awaiting manual or scheduled capture. |
-| `failed` | The payment was rejected (e.g., card declined, insufficient funds). |
-| `void` | The payment has been voided and should not be counted against the order. |
-| `completed` | The payment has been captured. Only payments in this state count against the order total. |
-
-With **auto-capture** enabled (default for most gateways), the Payment goes directly from `checkout` → `processing` → `completed`. With **manual capture**, it stops at `pending` until an admin captures it.
+These are the fields the Store API returns:
+
+| Attribute | Description | Example |
+|---|---|---|
+| `number` | Derived from the owner — see above. | `R1001-P1` |
+| `status` | Where the payment stands. | `completed` |
+| `amount` / `display_amount` | The amount, raw and formatted for its currency. | `99.99` / `$99.99` |
+| `payment_method_id` | Which method took it. | `pm_xyz789` |
+| `source_type` | `credit_card`, `store_credit` or `payment_source`. | `credit_card` |
+| `source_id` | The source's ID. | `cc_abc123` |
+| `source` | The source itself, embedded. | `{ brand: "visa", last4: "4242" }` |
+| `response_code` | The gateway's transaction reference. | `pi_3ABC123` |
+
+> **NOTE:** `source_type` is a plain name — `credit_card`, not a class name — so you can
+>   switch on it directly.
+
+#### Payment statuses
+
+| Status | Meaning |
+|---|---|
+| `checkout` | Created, not yet processed. |
+| `processing` | Being processed. Brief, and it stops a double submission. |
+| `pending` | Authorized but not captured. Waiting for capture. |
+| `completed` | Captured. Only these count towards the order total. |
+| `failed` | The gateway rejected it. |
+| `void` | Voided; it no longer counts against the order. |
+| `invalid` | Superseded — written to an old checkout payment when a new one replaces it. |
+
+When the money is taken follows the store's `capture_method`, which a payment
+method can override for its own payments:
+
+| `capture_method` | What happens |
+|---|---|
+| `checkout` | Charged when the order is placed — the payment goes straight to `completed`. |
+| `on_dispatch` | Authorized at checkout, captured when the goods go out. |
+| `manual` | Authorized at checkout; staff capture it when they choose. |
+
+The last two leave the payment at `pending` until capture. See
+[Configuration](../customization/configuration.md) for where the store
+setting lives.
+
+> **NOTE:** There is no state machine behind these. A payment's status is written by the
+>   workflows that process, capture and void it, so nothing transitions on its own
+>   and there is no sequence a client has to drive.
 
 #### Order Payment Status
 
@@ -563,11 +588,27 @@ Each payment update also recalculates the order's `payment_status`, derived from
 
 > **WARNING:** Keep an eye on orders sitting at `authorized` or `partially_paid` long after placement — a sudden increase can indicate a problem with your payment gateway that is affecting customers. Check the gateway's own dashboard for recent transactions.
 
+## Refunds
+
+Refunds are an Admin API operation — there is no Store API route, so a customer
+cannot start one from your storefront:
+
+```typescript Admin SDK
+await adminClient.orders.refunds.create(orderId, {
+  payment_id: 'py_abc123',
+  amount: '25.00',
+  reason_id: 'rr_xyz789',
+})
+```
+
+A refund publishes `payment.refunded` and moves the order's `payment_status` to
+`partially_refunded` or `refunded`.
+
 ## Payment Sources
 
 Payment sources represent the actual instrument used for a payment. They are created automatically when a Payment Session completes.
 
-### Credit Cards (`Spree::CreditCard`)
+### Saved cards
 
 Stores non-sensitive credit card information. With modern gateways, the actual card data is tokenized by the provider - Spree only stores reference IDs and display information.
 
@@ -575,9 +616,10 @@ Stores non-sensitive credit card information. With modern gateways, the actual c
 |---------------------|-----------------------------------------------------------------------------------------------|------------------------|
 | `month`             | The month the credit card expires.                                                           | `6`                    |
 | `year`              | The year the credit card expires.                                                            | `2026`                 |
-| `cc_type`           | The type of credit card (e.g., visa, mastercard).                                            | `visa`                 |
-| `last_digits`       | The last four digits of the credit card number.                                              | `1234`                 |
-| `name`              | The name of the credit card holder.                                                          | `John Doe`           |
+| `brand`             | The card brand.                                                                              | `visa`                 |
+| `last4`             | The last four digits.                                                                        | `4242`                 |
+| `name`              | The cardholder's name.                                                                       | `John Doe`             |
+| `default`           | Whether this is the customer's default card.                                                 | `true`                 |
 | `gateway_payment_profile_id`  | The payment token from the gateway (e.g., Stripe `pm_xxx`, Adyen `storedPaymentMethodId`).  | `pm_1ABC123`           |
 
 > **NOTE:** Spree never stores full credit card numbers. With modern gateways, card data is collected entirely by the gateway's frontend SDK (e.g., Stripe.js, Adyen Drop-in) and never touches your server. Spree only stores the tokenized reference (`gateway_payment_profile_id`) returned by the provider.
@@ -586,7 +628,7 @@ Stores non-sensitive credit card information. With modern gateways, the actual c
 
 A generic payment source model for non-card payment methods such as digital wallets, bank transfers, and buy-now-pay-later services. Gateway integrations create subtypes for each payment method type (e.g., Klarna, Afterpay, iDEAL, Apple Pay, Google Pay, PayPal).
 
-### Gateway Customers (`Spree::GatewayCustomer`)
+### Gateway customers
 
 Maps a Spree customer to their provider-specific customer profile. This enables features like saved payment methods, recurring billing, and customer-level fraud detection.
 
@@ -594,13 +636,16 @@ Maps a Spree customer to their provider-specific customer profile. This enables
 |-----------|-------------|---------------|
 | `profile_id` | The provider's customer ID (encrypted at rest) | `cus_ABC123` |
 | `payment_method_id` | The gateway this customer belongs to | `1` |
-| `user_id` | The Spree user | `42` |
+| `customer_id` | The Spree customer | `42` |
+
+A customer has at most one record per payment method, and `profile_id` is encrypted with Active Record Encryption where it is configured.
 
-Each customer has at most one `GatewayCustomer` record per payment method. The `profile_id` is encrypted using Active Record Encryption when available.
+> **NOTE:** This one is internal — the API does not expose it. It is listed here because
+>   gateway integrations rely on it; nothing a storefront does will read it.
 
 ## Payment Setup Sessions
 
-Payment Setup Sessions (`Spree::PaymentSetupSession`) allow customers to save payment methods for future use **without making an immediate payment**. This maps to concepts like Stripe's SetupIntent - a secure way to collect and tokenize payment details for later charges.
+Payment setup sessions let customers save payment methods for future use **without making an immediate payment**. This maps to concepts like Stripe's SetupIntent - a secure way to collect and tokenize payment details for later charges.
 
 ### Use Cases
 
@@ -714,7 +759,7 @@ console.log(completed.payment_source_id)  // e.g. 'card_xyz789' - the saved paym
 ```
 
 ```bash cURL
-curl -X POST 'https://api.mystore.com/api/v3/store/customers/me/payment_setup_sessions/pss_abc123/complete' \
+curl -X PATCH 'https://api.mystore.com/api/v3/store/customers/me/payment_setup_sessions/pss_abc123/complete' \
   -H 'X-Spree-API-Key: pk_xxx' \
   -H 'Authorization: Bearer $CUSTOMER_JWT' \
   -H 'Content-Type: application/json' \
@@ -722,7 +767,7 @@ curl -X POST 'https://api.mystore.com/api/v3/store/customers/me/payment_setup_se
 ```
 
 
-Spree will verify the result with the provider and create a saved payment source (e.g., `Spree::CreditCard`) that can be used for future payments.
+Spree verifies the result with the provider and saves a payment source — usually a card — for future payments.
 
 ## Supported Gateways
 
@@ -741,7 +786,11 @@ Spree publishes events throughout the payment lifecycle that you can subscribe t
 ### Payment Events
 | Event | Description |
 |-------|-------------|
-| `payment.paid` | Payment was completed |
+| `payment.completed` | Payment reached `completed` |
+| `payment.paid` | Payment was paid |
+| `payment.captured` | An authorized payment was captured |
+| `payment.voided` | Payment was voided |
+| `payment.refunded` | Payment was refunded |
 | `order.paid` | Order is fully paid |
 
 ### Payment Session Events
@@ -756,9 +805,11 @@ Spree publishes events throughout the payment lifecycle that you can subscribe t
 ### Payment Setup Session Events
 | Event | Description |
 |-------|-------------|
+| `payment_setup_session.processing` | Setup is being processed |
 | `payment_setup_session.completed` | Setup completed, payment source saved |
 | `payment_setup_session.failed` | Setup failed |
 | `payment_setup_session.canceled` | Setup was canceled |
+| `payment_setup_session.expired` | Setup expired |
 
 See [Events](events.md) for more details on subscribing to events.
 

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

@@ -308,7 +308,21 @@ The scheduler is the host app's. Two jobs fan out per seller and the interval lo
 | `Spree::SellerPayouts::SweepDueJob` | daily | settles every seller who is due |
 | `Spree::SellerTransfers::ExecutePendingDueJob` | hourly | retries earnings a provider refused — usually a passing thing |
 
-`spree/spree-starter` ships both entries in `server/config/recurring.yml`. A seller on the `manual` interval is skipped by the sweep and settled by hand instead:
+> **WARNING:** **You have to schedule these yourself** — a new project does not ship them, so
+>   a marketplace that skips this step never pays a seller. Add both to your
+>   scheduler; with Solid Queue that is `server/config/recurring.yml`:
+> 
+> ```yaml server/config/recurring.yml
+production:
+  sweep_due_seller_payouts:
+    class: Spree::SellerPayouts::SweepDueJob
+    schedule: every day at 3am
+  execute_pending_seller_transfers:
+    class: Spree::SellerTransfers::ExecutePendingDueJob
+    schedule: every hour
+```
+
+A seller on the `manual` interval is skipped by the sweep and settled by hand instead:
 
 
 ```typescript Admin SDK
@@ -319,7 +333,7 @@ const { data: balances } = await adminClient.sellers.balances('sel_xxx')
 await adminClient.sellers.settle('sel_xxx')
 
 // The built-in provider: record that the bank transfer went out
-await adminClient.sellerPayouts.complete('spo_xxx', { reference: 'TRN-2026-0912-0042' })
+await adminClient.sellerPayouts.complete('vpo_xxx', { reference: 'TRN-2026-0912-0042' })
 ```
 
 ```bash cURL
@@ -329,14 +343,43 @@ curl 'https://api.mystore.com/api/v3/admin/sellers/sel_xxx/balances' \
 curl -X POST 'https://api.mystore.com/api/v3/admin/sellers/sel_xxx/payouts' \
   -H 'X-Spree-API-Key: sk_xxx'
 
-curl -X PATCH 'https://api.mystore.com/api/v3/admin/seller_payouts/spo_xxx/complete' \
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/seller_payouts/vpo_xxx/complete' \
   -H 'X-Spree-API-Key: sk_xxx' \
   -H 'Content-Type: application/json' \
   -d '{ "reference": "TRN-2026-0912-0042" }'
 ```
 
 
-`GET /admin/seller_transfers` and `GET /admin/seller_payouts` list the ledger across every seller; the seller panel reads its own through `GET /seller/balances`, `/seller/transfers` and `/seller/payouts`, all read-only — the ledger is written by fulfilment and the sweep, never by the seller.
+Settling answers `201` with the payouts it created, one per currency. When one
+currency settles and another is refused it still answers `201`, listing what
+failed under `meta.failures` — so check that rather than assuming success. With
+nothing to settle it answers `422`.
+
+### Reading the ledger
+
+Across every seller, from the marketplace side:
+
+```typescript Admin SDK
+const { data: transfers } = await adminClient.sellerTransfers.list({ seller_id_eq: 'sel_xxx' })
+const { data: payouts } = await adminClient.sellerPayouts.list({ status_eq: 'completed' })
+
+const payout = await adminClient.sellerPayouts.get('vpo_xxx')
+```
+
+And from the seller's own panel, where every request is already scoped to the
+seller signed in — which is why none of these takes a seller ID:
+
+```typescript Seller SDK
+// What I'm owed, one row per currency
+const { data: balances } = await sellerClient.balances.list()
+
+// What I earned, and which payout settled it
+const { data: transfers } = await sellerClient.transfers.list({ payout_id_eq: 'vpo_xxx' })
+const { data: payouts } = await sellerClient.payouts.list()
+```
+
+All of it is read-only: the ledger is written by fulfilment and the sweep, never
+by a seller.
 
 ### Payout providers
 
@@ -347,7 +390,9 @@ A provider is a stateless class registered in `Spree.payout_providers` and chose
 | `Spree::PayoutProvider::System` (default) | No — keeps the books | The operator marks each payout paid, with the bank reference |
 | Stripe Connect (`spree_stripe`) | Yes — transfers each earning to the seller's connected account as goods ship, tied to the charge that funds it | A Stripe webhook, when the money lands |
 
-The contract is small: `transfer!` credits one earning, `pay!` sends one settlement, `reverse!` takes back part of an earning after a refund, and every call carries an idempotency key derived from the ledger row so a retry finds the movement it already made. Providers that need the seller to hold an account with them answer `requires_payout_account?` and implement `onboarding_url` — which is what the **payout account** [onboarding requirement](#onboarding-requirements) drives. To pay sellers through rails of your own, see [Seller payouts](../providers/payouts.md).
+The contract is small: `transfer!` credits one earning, `pay!` sends one settlement, `reverse!` takes back part of an earning after a refund, and every call carries an idempotency key derived from the ledger row so a retry finds the movement it already made. Providers that need the seller to hold an account with them answer `requires_payout_account?` and implement `onboarding_url` — which is what the **payout account** [onboarding requirement](#onboarding-requirements) drives. A seller gets a fresh link from `POST /seller/onboarding/payout_account`, and `GET /admin/payout_providers` lists what is registered, for a picker.
+
+A connected provider confirms settlements through `POST /api/v3/webhooks/payouts/:payment_method_id` — separate from the payment webhook, because providers scope seller-account events to their own subscription and signing secret. To pay sellers through rails of your own, see [Seller payouts](../providers/payouts.md).
 
 See [Stripe Connect for marketplaces](../../integrations/payments/stripe-connect.md) for the shipped provider.
 

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: