@spree/docs 0.1.229 → 0.1.231

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

@@ -9,7 +9,7 @@ Spree has a highly flexible payments model which allows multiple payment methods
 
 Payment methods typically represent a payment gateway. Gateways will process card payments, online bank transfers, buy-now-pay-later, wallet payments, and other types of payments. Spree also comes with a Check option for offline processing.
 
-The `Payment` model in Spree tracks payments against [Orders](orders). Payments relate to a `source` which indicates how the payment was made, and a `PaymentMethod`, indicating the processor used for this payment.
+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.
 
@@ -153,7 +153,8 @@ Payment methods where `session_required?` returns `false` don't need a payment s
 
 For these methods, the Store API allows creating a payment directly without going through the payment session flow:
 
-```typescript
+
+```typescript Store SDK
 const options = { spreeToken: cart.token }
 
 // Create a payment for a non-session payment method
@@ -166,6 +167,19 @@ const payment = await client.carts.payments.create(cart.id, {
 }, options)
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/payments' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'X-Spree-Token: CART_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "payment_method_id": "pm_xyz789",
+    "amount": "99.99",
+    "metadata": { "purchase_order_number": "PO-12345" }
+  }'
+```
+
+
 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 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).
@@ -349,7 +363,8 @@ stateDiagram-v2
 
 **Create a Payment Session:**
 
-```typescript
+
+```typescript Store SDK
 const options = { spreeToken: cart.token }
 
 // Create a payment session for the selected payment method
@@ -364,9 +379,18 @@ console.log(session.external_id)              // e.g. 'pi_3ABC123' (Stripe Payme
 console.log(session.external_data.client_secret) // Use with Stripe.js or Adyen Drop-in
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/payment_sessions' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'X-Spree-Token: CART_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -d '{ "payment_method_id": "pm_xyz789", "amount": "99.99", "external_data": {} }'
+```
+
+
 **Response shape (`StorePaymentSession`):**
 
-```json
+```json Response
 {
   "id": "ps_abc123",
   "status": "pending",
@@ -386,7 +410,8 @@ console.log(session.external_data.client_secret) // Use with Stripe.js or Adyen
 
 **Update a Payment Session** (e.g., after order total changes):
 
-```typescript
+
+```typescript Store SDK
 const updated = await client.carts.paymentSessions.update(
   cart.id, session.id,
   { amount: '149.99' },
@@ -394,9 +419,19 @@ const updated = await client.carts.paymentSessions.update(
 )
 ```
 
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/payment_sessions/ps_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'X-Spree-Token: CART_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -d '{ "amount": "149.99" }'
+```
+
+
 **Complete a Payment Session** (after customer confirms payment on the frontend):
 
-```typescript
+
+```typescript Store SDK
 const completed = await client.carts.paymentSessions.complete(
   cart.id, session.id,
   { session_result: '...', external_data: {} },
@@ -405,14 +440,31 @@ const completed = await client.carts.paymentSessions.complete(
 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' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'X-Spree-Token: CART_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -d '{ "session_result": "...", "external_data": {} }'
+```
+
+
 > **WARNING:** Completing a payment session does **not** complete the order. You must call `POST /carts/:id/complete` separately after the session is completed. This separation prevents race conditions between the frontend and payment webhooks.
 
 **Complete the Order** (after the payment session is completed):
 
-```typescript
+
+```typescript Store SDK
 const order = await client.carts.complete(cart.id, options)
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/complete' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'X-Spree-Token: CART_TOKEN'
+```
+
+
 ### Payment Webhooks
 
 Spree provides a generic webhook endpoint at `POST /api/v3/webhooks/payments/:payment_method_id` that payment gateway extensions can use. When a payment provider sends a webhook (e.g., Stripe `payment_intent.succeeded`), Spree:
@@ -427,7 +479,7 @@ The background job creates/updates the Payment record, marks the session as comp
 
 Gateway extensions implement `parse_webhook_event` to normalize provider-specific payloads:
 
-```ruby
+```ruby server/app/models/my_gateway.rb
 class MyGateway < Spree::Gateway
   def parse_webhook_event(raw_body, headers)
     # Verify signature — raise WebhookSignatureError if invalid
@@ -591,7 +643,8 @@ sequenceDiagram
 
 **Create a Payment Setup Session:**
 
-```typescript
+
+```typescript Store SDK
 const options = { token: jwtToken }
 
 // Create a setup session for saving a payment method
@@ -604,9 +657,18 @@ const setupSession = await client.customer.paymentSetupSessions.create({
 console.log(setupSession.external_client_secret) // e.g. 'seti_ABC123_secret_xyz'
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/store/customers/me/payment_setup_sessions' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'Authorization: Bearer $CUSTOMER_JWT' \
+  -H 'Content-Type: application/json' \
+  -d '{ "payment_method_id": "pm_xyz789", "external_data": {} }'
+```
+
+
 **Response shape (`StorePaymentSetupSession`):**
 
-```json
+```json Response
 {
   "id": "pss_abc123",
   "status": "pending",
@@ -622,13 +684,22 @@ console.log(setupSession.external_client_secret) // e.g. 'seti_ABC123_secret_xyz
 
 **Get a Payment Setup Session:**
 
-```typescript
+
+```typescript Store SDK
 const session = await client.customer.paymentSetupSessions.get('pss_abc123', options)
 ```
 
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/customers/me/payment_setup_sessions/pss_abc123' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'Authorization: Bearer $CUSTOMER_JWT'
+```
+
+
 **Complete a Payment Setup Session** (after the customer completes setup on the frontend using the gateway SDK and `external_client_secret`):
 
-```typescript
+
+```typescript Store SDK
 const completed = await client.customer.paymentSetupSessions.complete(
   'pss_abc123',
   { external_data: {} },
@@ -638,6 +709,15 @@ console.log(completed.status)             // 'completed'
 console.log(completed.payment_source_id)  // e.g. 'card_xyz789' - the saved payment method
 ```
 
+```bash cURL
+curl -X POST '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' \
+  -d '{ "external_data": {} }'
+```
+
+
 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.
 
 ## Supported Gateways
@@ -678,14 +758,6 @@ Spree publishes events throughout the payment lifecycle that you can subscribe t
 
 See [Events](events.md) for more details on subscribing to events.
 
-## Related Documentation
-
-- [Payments (Store SDK)](../sdk/store/payments.md) - SDK how-to for payment sessions, payments, and setup sessions
-- [Build a Custom Payment Method](../how-to/custom-payment-method.md) - Step-by-step guide to creating your own payment gateway integration
-- [Orders](orders.md) - Order lifecycle, payment and fulfillment status
-- [Checkout Customization](carts.md) - Customizing the checkout flow
-- [Events](events.md) - Subscribe to payment events
-
 ## Two paths to a completed order
 
 A payment can finish in two places, and both have to end at the same result.
@@ -697,3 +769,11 @@ Whichever arrives first completes the order; the other finds the work already do
 > **WARNING:** Never treat the browser returning from a redirect as proof of payment. The provider's webhook is the authoritative signal — a customer can close the tab, and a browser response can be forged.
 
 Both paths can be replaced if your integration needs different behaviour — see [Dependencies](../customization/dependencies.md).
+
+## Related Documentation
+
+- [Payments (Store SDK)](../sdk/store/payments.md) - SDK how-to for payment sessions, payments, and setup sessions
+- [Build a Custom Payment Method](../how-to/custom-payment-method.md) - Step-by-step guide to creating your own payment gateway integration
+- [Orders](orders.md) - Order lifecycle, payment and fulfillment status
+- [Checkout Customization](carts.md) - Customizing the checkout flow
+- [Events](events.md) - Subscribe to payment events

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

@@ -268,7 +268,7 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=prior_pric
 
 The response includes a `prior_price` object when expanded:
 
-```json
+```json Response
 {
   "id": "prod_xxx",
   "name": "Spree Tote",
@@ -287,15 +287,20 @@ The response includes a `prior_price` object when expanded:
 
 Price history tracking is enabled by default. To disable it (e.g., for non-EU stores):
 
-```ruby
-# config/initializers/spree.rb
-Spree.config do |config|
-  config.track_price_history = false
-  config.price_history_retention_days = 30 # default
-end
+
+```typescript Admin SDK
+await client.store.update({ preferred_track_price_history: false })
+```
+
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/store' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "preferred_track_price_history": false }'
 ```
 
-Price history retention defaults to 30 days and can be configured globally. A Rake task is provided for cleanup:
+
+Retention defaults to 30 days, set per store with the `price_history_retention_days` preference. A Rake task prunes anything older:
 
 
 ```bash Spree CLI (Docker)

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

@@ -213,6 +213,7 @@ spree api post /products -d '{
 
 For something with no options at all, send prices directly and skip the variants array — Spree forwards them to the product's single variant:
 
+
 ```typescript Admin SDK
 await adminClient.products.create({
   name: 'The Spree Handbook',
@@ -221,6 +222,18 @@ await adminClient.products.create({
 })
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/products' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "name": "The Spree Handbook",
+    "status": "active",
+    "prices": [{ "currency": "USD", "amount": "19.99" }]
+  }'
+```
+
+
 Don't pass both.
 
 Update, clone, or archive a product (deleting soft-deletes it):
@@ -346,7 +359,7 @@ await client.products.approve('prod_xxx')
 await client.products.reject('prod_xxx', { reason: 'Please add a photo showing scale.' })
 
 // The review queue
-const pending = await client.products.list({ filter: { status_eq: 'proposed' } })
+const pending = await client.products.list({ status_eq: 'proposed' })
 
 // Who decided, and when
 const product = await client.products.get('prod_xxx', { expand: ['submission'] })
@@ -448,6 +461,7 @@ There's no such thing as a product without one. A book with no size or colour st
 
 `default_variant_id` names the variant that represents the product — the price shown on a listing page, and what "add to cart" means before anyone picks anything.
 
+
 ```typescript Store SDK
 const product = await client.products.get('spree-tote')
 
@@ -456,6 +470,12 @@ product.price              // that variant's price
 product.variant_count      // 6
 ```
 
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products/spree-tote' \
+  -H 'X-Spree-API-Key: pk_xxx'
+```
+
+
 For a single-variant product that's the only variant. For a product with options it's the first one, unless you say otherwise. If the default is ever removed, another is promoted automatically — a product is never left without one.
 
 Products can also carry `buy_box_variant_id`, naming the variant a marketplace has chosen to feature when several sellers offer the same listing.
@@ -583,6 +603,7 @@ erDiagram
     }
 ```
 
+
 ```typescript Admin SDK
 const shoes = await adminClient.productTypes.create({
   name: 'Footwear',
@@ -601,6 +622,19 @@ await adminClient.products.create({
 })
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/product_types' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "name": "Footwear",
+    "option_type_ids": ["optt_size", "optt_color"],
+    "category_ids": ["ctg_footwear"],
+    "delivery_profile_id": "dp_standard"
+  }'
+```
+
+
 ### A type is a template, not a controller
 
 This is the part that determines how you should think about them.
@@ -620,10 +654,17 @@ Seeding is also **additive** — it adds what's missing and never removes what a
 
 If you *do* want an edited type to reach the products already using it, that's an explicit action:
 
+
 ```typescript Admin SDK
 const { products_count } = await adminClient.productTypes.applyToProducts('pt_xxx')
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/product_types/pt_xxx/apply_to_products' \
+  -H 'X-Spree-API-Key: sk_xxx'
+```
+
+
 It runs in the background and is additive like the rest — never a side effect of saving a type.
 
 > **INFO:** `required` on a type's custom field is **advisory** — it marks the field in the dashboard but isn't enforced on write, since Spree saves the product and its fields in two steps. Validate in your own tooling if you need it enforced.
@@ -878,6 +919,7 @@ curl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts/products?l
 
 Collections work the same way from a storefront's point of view:
 
+
 ```typescript Store SDK
 const { data: collections } = await client.collections.list()
 
@@ -886,6 +928,15 @@ const { data: products } = await client.collections.products.list('summer-2025',
 })
 ```
 
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/collections' \
+  -H 'X-Spree-API-Key: pk_xxx'
+
+curl 'https://api.mystore.com/api/v3/store/collections/summer-2025/products?limit=12' \
+  -H 'X-Spree-API-Key: pk_xxx'
+```
+
+
 A rule-based collection is defined once and maintains itself — set it to match everything tagged `sale` and under $50, and products appear and disappear as those facts change. Ordering can be manual or by a rule such as newest first.
 
 ## Publications and Sales Channels

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

@@ -28,7 +28,7 @@ flowchart LR
 
 A query names what to measure and how to slice it. This is the whole surface:
 
-```json
+```json Query
 {
   "metrics": ["total_sales", "orders"],
   "dimensions": [{ "name": "completed_at", "grain": "week" }],
@@ -76,7 +76,7 @@ different clocks, so a payment total beside a units-received count is two
 reports wearing one table — the query refuses the mix rather than inventing a
 join between grains that have no honest relationship.
 
-```ruby
+```ruby server/config/initializers/spree.rb
 Spree.reporting.metric :total_sales,
   sql: 'SUM(%{orders}.total)', base: :orders, format: :money
 ```
@@ -118,7 +118,7 @@ row and inflate every other metric in the same query.
 Core's sales metrics follow the sequence merchants and accountants already use,
 so a Spree figure means what the same word means everywhere else:
 
-```
+```text
 gross_sales − discounts − returns = net_sales
 net_sales + shipping + duties + fees + taxes = total_sales
 ```
@@ -137,7 +137,7 @@ zero and margin over an incompletely-costed catalogue reads high.
 A dimension groups and filters. Its definition owns every behaviour keyed off
 it, which is what lets an extension-registered dimension work end to end:
 
-```ruby
+```ruby server/config/initializers/spree.rb
 Spree.reporting.dimension :channel, base: :orders, column: :channel_id,
   lookup: :channel,
   subject: -> { Spree::Channel }, key_scope: 'read_channels',
@@ -179,7 +179,7 @@ fulfill", "Open returns" and "Low stock" are the state of the store right now,
 with no time range and no currency. The registry holds these as **counters**
 beside metrics and dimensions, and `GET /dashboard/counters` evaluates them:
 
-```json
+```json Response
 {
   "channel_id": null,
   "counters": [

package/dist/developer/core-concepts/returns-exchanges-claims.md

@@ -163,6 +163,7 @@ how postage records work in general.
 
 What to do about a claim is decided when you resolve it, not when the customer opens it — merchants usually decide once they've seen the photos.
 
+
 ```typescript Admin SDK
 await adminClient.orders.claims.approve('or_xxx', 'clm_xxx')
 
@@ -173,32 +174,70 @@ await adminClient.orders.claims.resolve('or_xxx', 'clm_xxx', {
 })
 ```
 
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/claims/clm_xxx/approve' \
+  -H 'X-Spree-API-Key: sk_xxx'
+
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/claims/clm_xxx/resolve' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "resolution": "refund_and_replacement",
+    "refund_method": "store_credit",
+    "replacement_line_item_ids": ["li_xxx"]
+  }'
+```
+
+
 A replacement creates a new [fulfillment](fulfillments.md) on the original order, so the customer doesn't have to place a second one.
 
 ## Exchanges
 
 An exchange works like a return, but ends by sending different items instead of refunding:
 
+
 ```typescript Admin SDK
 await adminClient.orders.exchanges.approve('or_xxx', 'exch_xxx')
 await adminClient.orders.exchanges.receive('or_xxx', 'exch_xxx')
 await adminClient.orders.exchanges.fulfill('or_xxx', 'exch_xxx')
 ```
 
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/exchanges/exch_xxx/approve' \
+  -H 'X-Spree-API-Key: sk_xxx'
+
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/exchanges/exch_xxx/receive' \
+  -H 'X-Spree-API-Key: sk_xxx'
+
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/orders/or_xxx/exchanges/exch_xxx/fulfill' \
+  -H 'X-Spree-API-Key: sk_xxx'
+```
+
+
 ## Reporting
 
 Because each one is its own record, you can query them directly:
 
+
 ```typescript Admin SDK
 // Everything awaiting action
-const pending = await adminClient.returns.list({ filter: { status_eq: 'approved' } })
+const pending = await adminClient.returns.list({ status_eq: 'approved' })
 
 // Claims opened this month
 const claims = await adminClient.claims.list({
-  filter: { created_at_gt: '2026-08-01' },
+  created_at_gt: '2026-08-01',
 })
 ```
 
+```bash cURL
+curl 'https://api.mystore.com/api/v3/admin/returns?q[status_eq]=approved' \
+  -H 'X-Spree-API-Key: sk_xxx'
+
+curl 'https://api.mystore.com/api/v3/admin/claims?q[created_at_gt]=2026-08-01' \
+  -H 'X-Spree-API-Key: sk_xxx'
+```
+
+
 ## Return policy
 
 Spree ships no built-in return window. Whether a customer may open a return is store policy, and it's checked when the return is created — so you can hold customers to a 30-day window while letting staff make an exception for a good customer, and vary the rule by market where local law requires it.

package/dist/developer/core-concepts/search-filtering.md

@@ -278,8 +278,7 @@ See [Querying](../../api-reference/store-api/querying.md) for the full list of f
 
 Spree uses a pluggable search provider architecture. The default provider uses SQL (ILIKE + Ransack). For production catalogs with 1,000+ products, we recommend switching to [Meilisearch](../../integrations/search/meilisearch.md) for typo tolerance, relevance ranking, and faster faceted search.
 
-```ruby
-# config/initializers/spree.rb
+```ruby server/config/initializers/spree.rb
 Spree.search_provider = 'Spree::SearchProvider::Meilisearch'
 ```