@spree/docs 0.1.252 → 0.1.254

package/dist/api-reference/admin-api/endpoints.md

@@ -711,7 +711,7 @@ Endpoints marked — are exempt from scope checks (authentication and session en
 | Method | Path | Required scope | Summary |
 |---|---|---|---|
 | `GET` | `/translations` | `read_products` | Translation coverage for a resource type |
-| `POST` | `/translations/batch` | *write_<resource> for every resource type in the batch (for API-key authentication)* | Batch upsert translations |
+| `POST` | `/translations/batch` | *write_&lt;resource&gt; for every resource type in the batch (for API-key authentication)* | Batch upsert translations |
 
 ## Webhook endpoints
 

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

@@ -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/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/deployment/emails.md

@@ -30,7 +30,7 @@ Spree Backend → Webhook POST → Storefront → render email → send via Rese
 
 1. **Create a webhook endpoint** in Spree Admin → Settings → Developer → Webhooks:
    - **URL:** `https://your-storefront.com/api/webhooks/spree`
-   - **Events:** `order.completed`, `order.canceled`, `order.shipped`, `customer.password_reset_requested`, `newsletter_subscriber.subscription_requested`
+   - **Events:** `order.placed`, `order.canceled`, `order.fulfilled`, `customer.password_reset_requested`
 
 2. **Configure the storefront** with the webhook secret and email provider:
 
@@ -49,13 +49,12 @@ Spree Backend → Webhook POST → Storefront → render email → send via Rese
 
 | Event | Email |
 |-------|-------|
-| `order.completed` | Order confirmation with items, totals, addresses |
+| `order.placed` | Order confirmation with items, totals, addresses |
 | `order.canceled` | Cancellation notice |
-| `order.shipped` | Shipping notification with tracking link |
+| `order.fulfilled` | Shipping notification with tracking link |
 | `customer.password_reset_requested` | Password reset link |
-| `newsletter_subscriber.subscription_requested` | Newsletter double opt-in confirmation link |
 
-> **NOTE:** The storefront listens for `order.completed` and `order.shipped`, the names these events had before Spree 6.0. Spree 6.0 still sends them alongside the new names, `order.placed` and `order.fulfilled`, but stops in Spree 6.1. Before upgrading to 6.1, switch the storefront handlers and your webhook endpoint subscriptions to the new names.
+> **NOTE:** Spree 6.0 also sends the pre-6.0 names `order.completed` and `order.shipped` as deprecated aliases until 6.1. Subscribe the endpoint to the new names only — subscribing to both makes Spree deliver both events.
 
 #### Custom Frameworks
 

package/dist/developer/storefront/nextjs/emails.md

@@ -16,14 +16,14 @@ Email templates are React components in `src/lib/emails/`:
 
 | File | Event | Description |
 |------|-------|-------------|
-| `order-confirmation.tsx` | `order.completed` | Items, totals, addresses, delivery method |
+| `order-confirmation.tsx` | `order.placed` | Items, totals, addresses, delivery method |
 | `order-canceled.tsx` | `order.canceled` | Cancellation notice with items |
-| `shipment-shipped.tsx` | `order.shipped` | Tracking number and link |
+| `shipment-shipped.tsx` | `order.fulfilled` | Tracking number and link |
 | `password-reset.tsx` | `customer.password_reset_requested` | Reset button and fallback link |
 
 Customize a template by editing its file directly — they use `@react-email/components` for email-safe layout primitives.
 
-> **NOTE:** The storefront listens for `order.completed` and `order.shipped`, the names these events had before Spree 6.0. Spree 6.0 still sends them alongside the new names, `order.placed` and `order.fulfilled`, but stops in Spree 6.1. Before upgrading to 6.1, switch the storefront handlers and your webhook endpoint subscriptions to the new names.
+> **NOTE:** Spree 6.0 also sends the pre-6.0 names `order.completed` and `order.shipped` as deprecated aliases until 6.1. Subscribe the endpoint to the new names only — subscribing to both makes Spree deliver both events.
 
 ## Previewing
 
@@ -57,9 +57,9 @@ import { createWebhookHandler } from '@/lib/spree/webhooks'
 const handler = createWebhookHandler({
   secret: process.env.SPREE_WEBHOOK_SECRET!,
   handlers: {
-    'order.completed': handleOrderCompleted,
+    'order.placed': handleOrderPlaced,
     'order.canceled': handleOrderCanceled,
-    'order.shipped': handleOrderShipped,
+    'order.fulfilled': handleOrderFulfilled,
     'customer.password_reset_requested': handlePasswordReset,
   },
 })
@@ -74,7 +74,7 @@ To add a new email type:
 
 ## Setup
 
-1. **Create a webhook endpoint** in Spree Admin → Settings → Developer → Webhooks. Subscribe to `order.completed`, `order.canceled`, `order.shipped`, and `customer.password_reset_requested`, and copy the secret key into `SPREE_WEBHOOK_SECRET`.
+1. **Create a webhook endpoint** in Spree Admin → Settings → Developer → Webhooks. Subscribe to `order.placed`, `order.canceled`, `order.fulfilled`, and `customer.password_reset_requested`, and copy the secret key into `SPREE_WEBHOOK_SECRET`.
 
 2. **Receive webhooks locally.** Expose the storefront with a public URL so Spree can reach it — the simplest option is a [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/):
 

package/package.json

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