@spree/docs 0.1.250 → 0.1.252

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

@@ -250,7 +250,7 @@ For providers like Stripe, create a payment session and confirm it with their ow
     const order = await client.carts.complete(cartId)
     ```
 
-    You get back an [Order](orders.md).
+    You get back an [Order](orders.md) — or, in a marketplace where the cart held several sellers' goods, an [order group](sellers.md#one-checkout-several-sellers) holding one order per seller. Tell them apart with `isOrderGroup` from `@spree/sdk`.
 
 
 Discount codes, gift cards and store credit can be applied any time before completion:

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

@@ -246,6 +246,15 @@ Two details worth knowing:
 > A back office must handle it too: an order raised from the admin divides the same way, so completing one may answer with a group instead of an order.
 
 
+```typescript Store SDK
+import { isOrderGroup } from '@spree/sdk'
+
+const result = await client.carts.complete(cartId, { spreeToken: cart.token })
+
+// One order per seller when the cart held several sellers' goods.
+const orders = isOrderGroup(result) ? result.orders : [result]
+```
+
 ```typescript Admin SDK
 import { isOrderGroup } from '@spree/admin-sdk'
 

package/dist/developer/sdk/store/cart-checkout.md

@@ -122,9 +122,26 @@ await client.carts.update(cartId, {
 ### Complete Checkout
 
 ```typescript
-await client.carts.complete(cartId, { spreeToken: cart.token });
+import { isOrderGroup } from '@spree/sdk';
+
+const result = await client.carts.complete(cartId, { spreeToken: cart.token });
+```
+
+Completing a cart usually returns one order. In a [marketplace](../../core-concepts/sellers.md#one-checkout-several-sellers), a cart holding several sellers' goods divides into one order per seller, and the response is the **order group** that ties them together: one purchase, one payment, combined totals, and the per-seller orders in `orders`. Use `isOrderGroup` to tell the two apart:
+
+```typescript
+if (isOrderGroup(result)) {
+  // One purchase, shown to the customer under the group's number and total.
+  console.log(result.number, result.display_total);
+  // How it will arrive: one order per seller, each with its own items and delivery.
+  result.orders.forEach((order) => console.log(order.number, order.items));
+} else {
+  console.log(result.number, result.display_total);
+}
 ```
 
+A storefront that never sells through more than one seller always gets an order back, but checking costs nothing and keeps the confirmation page working if sellers are added later.
+
 ### Fulfillments
 
 Fulfillments are included in the cart response — there is no separate list endpoint.

package/dist/developer/upgrades/5.6-to-6.0.md

@@ -313,13 +313,15 @@ Replace it by swapping the handler:
 
 ```ruby
 # config/initializers/spree.rb
-Rails.application.config.after_initialize do
-  Spree.hooks.unregister('returns.create.validate', 'Spree::Returns::EligibilityValidator')
-  Spree.hooks.register('returns.create.validate', 'MyStore::ReturnPolicy')
-end
+Spree.hooks.unregister('returns.create.validate', 'Spree::Returns::EligibilityValidator')
+Spree.hooks.register('returns.create.validate', 'MyStore::ReturnPolicy')
+
+# The same validator guards exchanges — swap it there too if your policy should cover them:
+Spree.hooks.unregister('exchanges.create.validate', 'Spree::Returns::EligibilityValidator')
+Spree.hooks.register('exchanges.create.validate', 'MyStore::ReturnPolicy')
 ```
 
-Wrap the swap in `after_initialize`: core registers the default validator after your initializers load, so an `unregister` at the top level of an initializer would run too early and do nothing.
+Core registers the default validator before your initializers load, so the swap works at the top level of an initializer.
 
 A handler receives the workflow (so it can read `order`, `items`, `created_by`, `order.market`) and calls `workflow.reject!(message)` to veto. Every one of the fifteen transitions has a leading `validate` hook, so the same seam gates approving, receiving and refunding.
 
@@ -391,6 +393,20 @@ one. An order whose every parcel was recalled now reads
 `fulfillment_status: unfulfilled` rather than `canceled`; only a canceled
 order reads `canceled`.
 
+## Payment source IDs use the `psrc_` prefix
+
+`Spree::PaymentSource` shared the `ps_` prefix with `Spree::PaymentSession`,
+so the same string could name either record. Payment sources now use
+`psrc_`. The encoded part of the ID doesn't change, only the prefix. The only
+place a payment source's ID shows up is the `source_id` of a payment backed by
+a non-card payment source (wallets, bank redirects and similar). If you stored
+one of those values, swap `ps_` for `psrc_`. Payment session IDs stay `ps_`.
+
+Class-level `decode_prefixed_id` (for example `Spree::Product.decode_prefixed_id`)
+now returns `nil` for an ID with another model's prefix, the same as
+`find_by_prefix_id`. Call `Spree::PrefixedId.decode_prefixed_id` if you
+really need to decode any prefix.
+
 ## Removed in 6.0
 
 These were deprecated in 5.x and are **gone now** — there is no bridge, so calls raise `NoMethodError`. Most were one-line delegations to a replacement that already exists.

package/package.json

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