Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Developer Docs update
Damian Legawiece3207a6f1957
diff --git a/docs/developer/core-concepts/delivery-setup.mdx b/docs/developer/core-concepts/delivery-setup.mdxindex 09f59b7e38..d2800b98be 100644--- a/docs/developer/core-concepts/delivery-setup.mdx+++ b/docs/developer/core-concepts/delivery-setup.mdx@@ -163,7 +163,8 @@ otherwise every parcel is quoted light.Package types are that vocabulary: the box parcels ship in, and for wholesale,the cartons products are packed into and the pallets or containers an order-leaves on.+leaves on. How those cartons and pallets roll up into a quote is+[freight](/developer/core-concepts/freight).<CodeGroup>@@ -262,6 +263,7 @@ box of their own with all three dimensions and a weight recorded. See## Related+- [Freight](/developer/core-concepts/freight) — cartons, pallets and wholesale shipping- [Fulfillments](/developer/core-concepts/fulfillments) — what happens to the parcel afterwards- [Calculators](/developer/core-concepts/calculators) — how a price is worked out- [EasyPost](/integrations/shipping/easypost) — live carrier rates and labelsdiff --git a/docs/developer/core-concepts/freight.mdx b/docs/developer/core-concepts/freight.mdxnew file mode 100644index 0000000000..62fef2810d--- /dev/null+++ b/docs/developer/core-concepts/freight.mdx@@ -0,0 +1,293 @@+---+title: Freight+description: How wholesale orders ship — the carton and pallet chain a product declares, the logistics rollup a forwarder quotes against, and rates that carry no price yet.+---++## Overview++A wholesale order does not leave the warehouse as parcels. It leaves as+cartons, a pallet, or a container, and for international freight the price is+quoted by a forwarder after someone looks at the order — not by an API at+checkout.++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? |+| **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? |++One catalog serves both audiences. The same product ships parcel to a shopper+and carton to a trade buyer, because freight methods sit on the ordinary+shipping profile and are gated by who is buying rather than by what is bought.+See [delivery setup](/developer/core-concepts/delivery-setup) for profiles,+zones and methods, and [package types](/developer/core-concepts/delivery-setup#packaging)+for the packaging vocabulary this builds on.++## How products pack++Freight numbers are not derivable from retail shipping data. A case of 48+bottles is one carton, not 48 parcels — so a product says how its units pack,+and the rest follows the chain **unit → carton → pallet → cubic meters and+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:++| Field | What it says |+|---|---|+| `carton_package_type_id` | Which carton this is packed into. Must be a package type of kind `carton` |+| `units_per_carton` | How many units one carton holds |+| `carton_weight` | What a packed carton weighs, gross. Optional |+| `cartons_per_pallet` | How those cartons stack |+| `purchase_unit` | `unit` or `carton` — what a buyer is quoted in |++<CodeGroup>++```typescript Admin SDK+// The carton, once, shared by every product packed in it.+const carton = await adminClient.packageTypes.create({+ name: 'Master carton',+ kind: 'carton',+ length: 40, width: 30, height: 25, dimensions_unit: 'cm',+ weight: 0.4, max_weight: 20, weight_unit: 'kg',+})++// How this product fills it.+await adminClient.products.variants.update('prod_xxx', 'variant_xxx', {+ carton_package_type_id: carton.id,+ units_per_carton: 48,+ carton_weight: 19.2,+ cartons_per_pallet: 40,+ purchase_unit: 'carton',+})+```++```bash cURL+curl -X POST 'https://api.mystore.com/api/v3/admin/package_types' \+ -H 'X-Spree-API-Key: sk_xxx' \+ -H 'Content-Type: application/json' \+ -d '{+ "name": "Master carton", "kind": "carton",+ "length": 40, "width": 30, "height": 25, "dimensions_unit": "cm",+ "weight": 0.4, "max_weight": 20, "weight_unit": "kg"+ }'++curl -X PATCH 'https://api.mystore.com/api/v3/admin/products/prod_xxx/variants/variant_xxx' \+ -H 'X-Spree-API-Key: sk_xxx' \+ -H 'Content-Type: application/json' \+ -d '{+ "carton_package_type_id": "pkgtype_xxx",+ "units_per_carton": 48,+ "carton_weight": 19.2,+ "cartons_per_pallet": 40,+ "purchase_unit": "carton"+ }'+```++</CodeGroup>++Stored quantities are always units, at every level. `purchase_unit` only+changes the vocabulary a storefront presents — a buyer shown "2 cartons" is+buying 96 units.++Two data errors are refused while the merchant is still editing rather than+discovered through a customer complaint: an `order_multiple` that straddles+carton boundaries can never ship whole, and quoting in cartons without saying+how many units one holds leaves a storefront no way to render the offer.++Reading a product back adds `units_per_pallet`, derived from the two divisors+so a merchant sees the far end of the chain without doing the arithmetic. It+is null unless both halves are recorded.++<Note>+A product may only be packed into a package type of kind `carton`, and a+carton with products packed into it cannot later become a pallet. Repack the+products first.+</Note>++## The freight summary++The **freight summary** is the load as a forwarder reads it: how many units,+the cartons they fill, the pallets those stack onto, the cubic meters they+occupy and what the whole thing weighs.++```json+{+ "total_units": 480,+ "total_cartons": 10,+ "total_pallets": 1,+ "total_volume": "0.3",+ "total_weight": "192.0",+ "complete": true+}+```++`total_volume` is cubic meters and `total_weight` is kilograms, both as+decimal strings. `total_pallets` is null unless every carton-bearing line says+how it stacks — one silent product would understate the load, so no figure is+better than a wrong one.++**`complete` is the field to read before quoting from any of it.** False means+part of the catalog carries no carton data, so those products were measured+loose from their unit dimensions instead. The numbers are still the best+available and real enough to quote against, but they are a floor rather than a+total, and a surface using them should say so.++A cart of unmeasured goods has no freight summary at all rather than one full+of zeros, which would read as a shipment that takes up no space.++### Where it appears++| Response | Shape |+|---|---|+| Store cart | Totals only |+| Store delivery rate | Totals only, on freight rates |+| Admin cart and order | Totals plus a `lines` breakdown |+| Admin delivery rate | Totals plus `lines` |++The per-product breakdown is back-office only. A buyer is told what their+shipment costs and how big it is; which SKU accounts for which part of it is+the warehouse's business. Each admin line carries `variant_id`, `sku`, `name`,+`units`, `cartons`, `pallets`, `units_per_carton`, `cartons_per_pallet`,+`weight_per_carton`, `volume`, `weight` and its own `complete` flag.++<CodeGroup>++```typescript SDK+const cart = await client.carts.get('cart_xxx')++if (cart.freight_summary) {+ const { total_cartons, total_pallets, total_volume, complete } = cart.freight_summary+ // `complete: false` — show these as a minimum, not a total.+}+```++```bash cURL+curl 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \+ -H 'X-Spree-API-Key: pk_xxx' \+ -H 'X-Spree-Token: guest_token'+```++</CodeGroup>++<Note>+A placed order's summary is never re-derived from the live catalog. The freight+provider freezes a copy onto the rate it quoted, and the order reads that — so+a carton size corrected next month does not rewrite what this container held.+Two freight consignments on one order are merged into the one load the+forwarder sees, and a canceled one is left out.+</Note>++## Freight rates++A freight method is an ordinary [delivery method](/developer/core-concepts/delivery-setup#delivery-methods-and-zones)+priced by the **Freight** rate provider. That provider quotes nothing and says+so: it returns a rate with no price, carrying the freight summary the merchant+will send to the forwarder in place of an amount.++Such a rate comes back with `unpriced: true`, and every money field on it reads+**"Quoted after review"** rather than a figure. That matters: a zero cost+rendering as "Free" over a container of goods is a promise the merchant cannot+keep. Unpriced rates are also sorted after every priced one and are never+preselected, so a buyer with a real parcel option still sees it first.++<CodeGroup>++```typescript SDK+const rates = fulfillment.delivery_rates++rates.forEach((rate) => {+ if (rate.unpriced) {+ rate.display_total // "Quoted after review"+ rate.freight_summary // what the forwarder will quote against+ } else {+ rate.display_total // "$24.00"+ }+})+```++```bash cURL+curl 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \+ -H 'X-Spree-API-Key: pk_xxx' \+ -H 'X-Spree-Token: guest_token'+```++</CodeGroup>++Checkout completes on an unpriced rate. The shipping price arrives afterwards,+once the forwarder has quoted it.++<Note>+How a wholesale buyer **pays** — deposits, net terms, credit limits — is a+separate subject and is not part of freight in 6.0. Partial payments are+generally available and predate this work. See+[payments](/developer/core-concepts/payments).+</Note>++## Shipment tiers++Which freight method a load qualifies for is configuration, not code. Each+tier — "Cartons", "Pallet", "20ft container" — is an ordinary delivery method+bounded by a rule.++**Volume rule.** Bounds the method by packed volume in cubic meters: a pallet+method takes 1–15 CBM, a 20ft container 15–33, and the estimator offers+whichever one the order actually fills.++Its minimum is deliberately forgiving. A partly measured catalog understates+the load, so the figure is a floor rather than a measurement — it may raise a+shipment into a tier but never exclude it from one. A maximum still applies,+since passing one on too small a number errs toward offering the method.++**Company rule.** Splits freight from parcel by who is buying. On, the method+is offered only to orders placed for a [company](/developer/core-concepts/companies),+so a carton tier disappears from retail carts. Off, only to orders that are+not, which keeps parcel methods away from wholesale buyers. A method with no+company rule is offered to both, so the rule is only ever added to state a+split.++<CodeGroup>++```typescript Admin SDK+await adminClient.deliveryMethods.create({+ name: 'Pallet freight',+ rate_provider: 'Spree::DeliveryRateProvider::Freight',+ rules: [+ { type: 'volume_rule', preferences: { minimum_volume: 1, maximum_volume: 15 } },+ { type: 'company_rule', preferences: { company_orders_only: true } },+ ],+})+```++```bash cURL+curl -X POST 'https://api.mystore.com/api/v3/admin/delivery_methods' \+ -H 'X-Spree-API-Key: sk_xxx' \+ -H 'Content-Type: application/json' \+ -d '{+ "name": "Pallet freight",+ "rate_provider": "Spree::DeliveryRateProvider::Freight",+ "rules": [+ { "type": "volume_rule", "preferences": { "minimum_volume": 1, "maximum_volume": 15 } },+ { "type": "company_rule", "preferences": { "company_orders_only": true } }+ ]+ }'+```++</CodeGroup>++A freight method never consults a calculator — there is no price to work out —+so admin surfaces hide its pricing form. `GET /api/v3/admin/delivery_methods/rate_providers`+lists the providers installed on the store, which is what a picker should read+rather than a hardcoded list.++## Related++- [Delivery setup](/developer/core-concepts/delivery-setup) — profiles, zones, methods and package types+- [Fulfillments](/developer/core-concepts/fulfillments) — what happens to the consignment afterwards+- [Companies](/developer/core-concepts/companies) — who a wholesale order is placed for+- [Build a B2B store](/developer/how-to/build-a-b2b-store) — the wholesale setup end to end+- [Package types](/user/settings/package-types) — configuring packaging in the dashboarddiff --git a/docs/developer/core-concepts/payments.mdx b/docs/developer/core-concepts/payments.mdxindex 363b849b8a..cff378e96d 100644--- a/docs/developer/core-concepts/payments.mdx+++ b/docs/developer/core-concepts/payments.mdx@@ -11,7 +11,7 @@ Payment methods typically represent a payment gateway. Gateways will process carThe `Payment` model in Spree tracks payments against [Orders](/developer/core-concepts/orders). 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 @@ erDiagramPayment {string numberdecimal amount- string state+ string statusstring response_code- string avs_responsestring source_typestring source_id}@@ -32,7 +31,7 @@ erDiagramstring typestring descriptionboolean active- string display_on+ boolean storefront_visibleinteger position}@@ -58,11 +57,12 @@ erDiagram}CreditCard {- string last_digits- string cc_type+ string last4+ string brandinteger monthinteger yearstring name+ boolean default}GatewayCustomer {@@ -124,14 +124,14 @@ 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.</Info>-### Session-based vs Legacy Payment Methods+### Session-based vs direct payment methodsPayment methods indicate whether they use the modern session-based flow via the `session_required?` method:@@ -142,13 +142,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@@ -184,9 +184,16 @@ curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/payments' \</CodeGroup>-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@@ -250,7 +257,7 @@ sequenceDiagram**This step does NOT complete the order** — it only handles payment processing. For wallet payments (Apple Pay, Google Pay), the gateway also patches the order's billing address with data from the wallet at this stage.</Step><Step title="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.</Step>@@ -309,11 +316,11 @@ sequenceDiagramSpree 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 createdFrontend->>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/completedSpree API-->>Frontend: Order completed```@@ -323,16 +330,18 @@ sequenceDiagramThe frontend reads the cart's embedded `payment_methods` (returned by `GET /carts/:id`) and checks the `session_required` flag on each method. Methods with `session_required: false` use this direct flow.</Step><Step title="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><Step title="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.</Step></Steps>### 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@@ -345,6 +354,13 @@ 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.+</Note>#### States@@ -362,6 +378,12 @@ stateDiagram-v2processing --> 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.+</Note>+#### API**Create a Payment Session:**@@ -449,7 +471,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' \@@ -500,10 +522,10 @@ class MyGateway < Spree::Gatewaycase event.typewhen '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 }elsenil # unsupported event@@ -516,48 +538,59 @@ 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` |+These are the fields the Store API returns:-#### Payment States+| 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` |-After a Payment Session completes, the resulting Payment transitions through these states:+<Note>+ `source_type` is a plain name — `credit_card`, not a class name — so you can+ switch on it directly.+</Note>-```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!-```+#### Payment statuses-| 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. |+| 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:-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.+| `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](/developer/customization/configuration) 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.+</Note>#### Order Payment Status@@ -578,11 +611,27 @@ Each payment update also recalculates the order's `payment_status`, derived fromKeep 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.</Warning>+## 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 SourcesPayment sources represent the actual instrument used for a payment. They are created automatically when a Payment Session completes.-### Credit Cards (`Spree::CreditCard`)+### Saved cardsStores 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.@@ -590,9 +639,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>@@ -603,7 +653,7 @@ Spree never stores full credit card numbers. With modern gateways, card data isA 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 customersMaps a Spree customer to their provider-specific customer profile. This enables features like saved payment methods, recurring billing, and customer-level fraud detection.@@ -611,13 +661,18 @@ 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` |-Each customer has at most one `GatewayCustomer` record per payment method. The `profile_id` is encrypted using Active Record Encryption when available.+A customer has at most one record per payment method, and `profile_id` is encrypted with Active Record Encryption where it is configured.++<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.+</Note>## 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@@ -738,7 +793,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' \@@ -747,7 +802,7 @@ curl -X POST 'https://api.mystore.com/api/v3/store/customers/me/payment_setup_se</CodeGroup>-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@@ -772,7 +827,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@@ -787,9 +846,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](/developer/core-concepts/events) for more details on subscribing to events.diff --git a/docs/developer/core-concepts/sellers.mdx b/docs/developer/core-concepts/sellers.mdxindex 579fd09fcf..e6dfc673b1 100644--- a/docs/developer/core-concepts/sellers.mdx+++ b/docs/developer/core-concepts/sellers.mdx@@ -324,7 +324,23 @@ 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+```+</Warning>++A seller on the `manual` interval is skipped by the sweep and settled by hand instead:<CodeGroup>@@ -336,7 +352,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@@ -346,7 +362,7 @@ 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" }'@@ -354,7 +370,36 @@ curl -X PATCH 'https://api.mystore.com/api/v3/admin/seller_payouts/spo_xxx/compl</CodeGroup>-`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@@ -365,7 +410,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](/developer/providers/payouts).+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](/developer/providers/payouts).See [Stripe Connect for marketplaces](/integrations/payments/stripe-connect) for the shipped provider.diff --git a/docs/docs.json b/docs/docs.jsonindex 4ca6d08633..9f2e093559 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -659,6 +659,7 @@"pages": ["developer/core-concepts/fulfillments","developer/core-concepts/delivery-setup",+ "developer/core-concepts/freight","developer/core-concepts/returns-exchanges-claims","developer/core-concepts/addresses","developer/core-concepts/calculators"