@spree/docs 0.1.251 → 0.1.253

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:
@@ -280,6 +280,10 @@ Completing a cart moves real money, so Spree is careful about it:
 
 **Totals are worked out at the last moment.** The amount charged is calculated when the cart is completed, not taken from an earlier request — so a price or promotion that changed while the customer was reviewing can't lead to the wrong charge.
 
+**The order keeps what the cart collected.** The customer, addresses, items, notes, purchase order number, tax identifier and the cart's `metadata` are all copied onto the order. When a checkout is split into one order per seller, every one of those orders receives the same copy. After that the cart and the order are independent — changing one never changes the other.
+
+> **WARNING:** A customer can write a cart's `metadata` through the Store API, so once it is copied onto the order, treat those keys as customer input. Do not keep anything there that your own code later trusts, such as a fraud or approval flag.
+
 If a cart can't be completed you get told why — a payment failure, or unmet [requirements](#checkout-requirements) — and the cart is left alone so the customer can fix it and try again.
 
 ## Abandoned carts

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

@@ -5,7 +5,7 @@ description: How Spree models orders — a permanent record created by completin
 
 ## Overview
 
-An order is a placed purchase. It's created by completing a [Cart](carts.md) and holds its own copy of everything the customer agreed to — items, prices, taxes, discounts and delivery.
+An order is a placed purchase. It's created by completing a [Cart](carts.md) and holds its own copy of everything the customer agreed to — items, prices, taxes, discounts and delivery. Anything your storefront stored in the cart's `metadata` is copied onto the order too, including onto every order of a checkout split between sellers.
 
 ```mermaid
 erDiagram

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/customization/checkout.md

@@ -41,6 +41,11 @@ Spree::Checkout::Registry.add_requirement(
 While `satisfied:` returns false the cart reports the requirement and refuses to
 complete. Its `code` is derived as `<field>_required` — `vat_number_required` here.
 
+The storefront satisfies it by writing the value into the cart's `metadata`. When the
+cart is completed, its `metadata` is copied onto the order — onto every order if the
+checkout is split between sellers — so the VAT number is still there after placement as
+`order.metadata['vat_number']`.
+
 Pass `applicable:` to scope it. It is checked before `satisfied:`, so a requirement
 that doesn't apply never appears at all:
 

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.
 

package/package.json

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