@spree/docs 0.1.266 → 0.1.268

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

@@ -41,7 +41,8 @@ On top of that, meaningful business moments get their own events:
 
 | Event | Meaning |
 |---|---|
-| `order.placed` | A customer completed checkout |
+| `order.placed` | An order was placed — one per order, so a checkout that split across several sellers publishes one per seller |
+| `order_group.completed` | A checkout that split finished — one event for the whole purchase |
 | `order.paid` | Payment is settled in full |
 | `order.canceled` | The order was cancelled |
 | `order.fulfilled` / `order.delivered` | Everything has shipped / arrived |

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

@@ -137,7 +137,9 @@ Writes a discount on each fulfillment covering its delivery cost. The row is kep
 
 ### Free items (`CreateLineItems`)
 
-Adds specified products to the cart when the promotion is eligible, checking stock first. Items are not removed automatically if eligibility is lost — customers remove them manually.
+Adds specified products to the cart when the promotion is eligible, checking stock first, and discounts them to zero. A customer who already has the gift in their cart gets theirs free rather than a duplicate; any further copies they bought stay paid for. The gift is taken back when the promotion stops applying.
+
+No second action is needed to make the gift free — pairing this with an order discount set to the gift's price discounts it twice.
 
 **Use case:** "Free gift with purchase", "Spend $100 get a free sample".
 

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

@@ -271,6 +271,14 @@ curl -X PATCH https://your-store.com/api/v3/admin/orders/or_UkLWZg9DAJ/complete
 ```
 
 
+### One confirmation, and it describes the purchase
+
+The customer made one purchase, so they get one confirmation email — sent from the group, not from any of its orders. Each child order is placed silently.
+
+If you replace the confirmation email, replace it at the group level too: the email a customer receives for a split checkout is `Spree::OrderGroupMailer`, reacting to the `order_group.completed` event, and a re-send from any child order in the admin sends the purchase's email rather than that child's. A checkout that doesn't split is unaffected and still sends the ordinary order confirmation.
+
+> **NOTE:** **Orders and deliveries are different counts.** Three seller orders do not mean three parcels. When several sellers' goods ship from one warehouse, the checkout quotes one delivery charge, and the split divides that charge between the orders rather than charging for it again — so one box arrives. Ask the group for `fulfillment_groups` to get the parcels that really ship; each one knows its delivery method, its cost, the goods it carries and who is sending it. Counting child orders instead promises the customer deliveries that will never arrive.
+
 ## Commission
 
 Commission is what the marketplace charges for the sale — configured as **rates**, and recorded per sale as immutable **commission lines**.

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

@@ -375,6 +375,14 @@ A handler receives the workflow (so it can read `order`, `items`, `created_by`,
 - **Customers are emailed their download links** when the order is placed, from the new `Spree::DigitalAssetMailer` in the optional `spree_emails` gem. Hosts that already send their own download email should either suppress it (`send_consumer_transactional_emails`) or drop their own. The dashboard's order page can re-send it.
 - **Digital assets are managed through the Admin API and dashboard**, and signed-in customers can list everything they have bought at `GET /api/v3/store/customers/me/digital_links`.
 
+## Free-gift promotions price their own gift
+
+The `Create line items` promotion action now discounts the items it adds down to zero. It used to add them at their full price and leave the discounting to you.
+
+> **WARNING:** **Delete the second action if you paired one with it.** The old guidance was to add a whole-order discount set to the gift's price to pay for the gift. That discount still applies, so a promotion configured the old way now discounts twice — the gift is free *and* the order discount comes off. Open each promotion using `Create line items`, and remove the accompanying `Create whole-order adjustment` that exists only to cancel out the gift.
+
+Two further changes come with it. A customer who already has the gift variant in their cart now gets theirs free rather than a second copy being added, and the promotion applies where it previously did nothing at all. And a gift is only taken back out of the cart for promotions actually applied to that order, so a customer who bought the gift variant themselves without qualifying keeps it.
+
 ## Dependency injection changes
 
 6.0 introduces `*_workflow` keys for the flows that graduated to the workflow tier. The old `*_service` keys **stay settable and readable one release so applications don't crash at boot — but a legacy write is stashed, not applied**: a class written against the old service contract is not interchangeable with the workflow the new call sites consume. Reads return your stashed class (legacy code calling its own override keeps working), falling back to the workflow. Removed in 6.1.

package/package.json

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