@spree/docs 0.1.265 → 0.1.267

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".
 
@@ -205,7 +207,7 @@ The available rule and action types — including any custom ones you register
 Coupon codes track promotion usage and can be single-use or multi-use.
 
 - **Single code** — set the `code` attribute on the promotion; `usage_limit` controls how many times it can be redeemed.
-- **Multi-code** — bulk-generated codes each track their own state (`unused` / `used`).
+- **Multi-code** — bulk-generated codes each track their own state (`unused` / `used`). A code is used up only when an order is placed with it. Applying it to a cart just holds it there, and a shopper who presents a code held by an abandoned cart takes it over, so an unfinished checkout never burns a code.
 
 Customers apply codes on the cart via the Store API:
 

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.265",
+  "version": "0.1.267",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",