Skip to content

armgit / spree

Public Imported from GitHub
0

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.

Developer Docs update

Damian Legawiece3207a6f1957
diff --git a/docs/developer/core-concepts/delivery-setup.mdx b/docs/developer/core-concepts/delivery-setup.mdx
index 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 labels
diff --git a/docs/developer/core-concepts/freight.mdx b/docs/developer/core-concepts/freight.mdx
new file mode 100644
index 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 dashboard
diff --git a/docs/developer/core-concepts/payments.mdx b/docs/developer/core-concepts/payments.mdx
index 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 car
The `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 @@ 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,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 methods
Payment 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 @@ 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
```
@@ -323,16 +330,18 @@ sequenceDiagram
The 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-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.
+</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::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
@@ -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 from
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.
</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 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.
@@ -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 is
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.
@@ -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.mdx
index 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.json
index 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"