@spree/docs 0.1.267 → 0.1.269

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/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/core-concepts/store-credits-gift-cards.md

@@ -399,6 +399,8 @@ Store Credits and Gift Cards work differently at checkout:
 - **Store Credits** - Require a customer account; applied from the customer's balance
 - **Gift Cards** - Can be used by anyone (guests included); applied directly to the order via code
 
+Both are applied before the customer chooses how to pay, and neither appears among the cart's payment methods. An order uses one or the other, never both. A gift card covers as much of the total as its balance allows and keeps up as the total changes. See the [cart & checkout SDK guide](../sdk/store/cart-checkout.md) for the calls.
+
 ### Checkout Flow
 
 ```mermaid

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

@@ -77,6 +77,8 @@ const cart = await client.carts.giftCards.apply(cartId, 'GC-ABCD-1234', options)
 await client.carts.giftCards.remove(cartId, 'gc_abc123', options);
 ```
 
+A gift card pays as much of the total as its balance allows, and its share keeps up when delivery, discounts or tax change the total. A cart can use a gift card or store credit, not both.
+
 ### Fees and Duties
 
 A cart may carry charges that are neither a product price nor tax: gift wrapping, a handling charge, a cash-on-delivery surcharge, or an import duty on a cross-border order. Each is a [fee](../../core-concepts/fees.md) on the cart, and the storefront should show every one of them before the customer pays.
@@ -174,6 +176,8 @@ await client.carts.storeCredits.apply(cartId, 25.00, options);
 await client.carts.storeCredits.remove(cartId, options);
 ```
 
+Store credit is a balance, not one of the cart's `payment_methods`: apply it here, then collect whatever `amount_due` is left with a payment method. It can't be combined with a gift card on the same cart.
+
 ### Totals
 
 The cart and order responses break the amount the customer pays into these totals. Each has a raw string value and a `display_` twin formatted in the cart's currency.

package/package.json

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