@spree/docs 0.1.293 → 0.1.295

package/dist/api-reference/store.yaml

@@ -13241,6 +13241,141 @@ components:
       - amount
       - display_amount
       x-typelizer: true
+    ExchangeLineItem:
+      type: object
+      properties:
+        id:
+          type: string
+        quantity:
+          type: number
+        received_quantity:
+          type: number
+        resellable:
+          type: boolean
+        original_price:
+          type: string
+        new_variant_price:
+          type: string
+        price_difference:
+          type: string
+        original_variant_id:
+          type: string
+          nullable: true
+        new_variant_id:
+          type: string
+          nullable: true
+        line_item_id:
+          type: string
+          nullable: true
+        fulfillment_item_id:
+          type: string
+          nullable: true
+        original_variant:
+          "$ref": "#/components/schemas/Variant"
+        new_variant:
+          "$ref": "#/components/schemas/Variant"
+      required:
+      - id
+      - quantity
+      - received_quantity
+      - resellable
+      - original_price
+      - new_variant_price
+      - price_difference
+      - original_variant_id
+      - new_variant_id
+      - line_item_id
+      - fulfillment_item_id
+      x-typelizer: true
+    Exchange:
+      type: object
+      properties:
+        id:
+          type: string
+        number:
+          type: string
+        status:
+          anyOf:
+          - type: string
+            enum:
+            - requested
+            - approved
+            - received
+            - fulfilled
+            - canceled
+          - type: string
+          description: The values listed are the built-in ones; extensions may add
+            more.
+        order_id:
+          type: string
+          nullable: true
+        reason_id:
+          type: string
+          nullable: true
+        price_difference:
+          type: string
+        display_price_difference:
+          type: string
+        approved_at:
+          type: string
+          nullable: true
+        received_at:
+          type: string
+          nullable: true
+        fulfilled_at:
+          type: string
+          nullable: true
+        canceled_at:
+          type: string
+          nullable: true
+        reason:
+          "$ref": "#/components/schemas/ReturnReason"
+        exchange_line_items:
+          type: array
+          items:
+            "$ref": "#/components/schemas/ExchangeLineItem"
+      required:
+      - id
+      - number
+      - status
+      - order_id
+      - reason_id
+      - price_difference
+      - display_price_difference
+      - approved_at
+      - received_at
+      - fulfilled_at
+      - canceled_at
+      x-typelizer: true
+    Export:
+      type: object
+      properties:
+        id:
+          type: string
+        number:
+          type: string
+        format:
+          type: string
+          nullable: true
+        created_at:
+          type: string
+        updated_at:
+          type: string
+        type:
+          type: string
+          nullable: true
+        user_id:
+          type: string
+          nullable: true
+      required:
+      - id
+      - number
+      - format
+      - created_at
+      - updated_at
+      - type
+      - user_id
+      x-typelizer: true
     Fee:
       type: object
       properties:
@@ -13545,6 +13680,111 @@ components:
       - expired
       - active
       x-typelizer: true
+    ImportRow:
+      type: object
+      properties:
+        id:
+          type: string
+        row_number:
+          type: number
+        status:
+          anyOf:
+          - type: string
+            enum:
+            - pending
+            - processing
+            - completed
+            - failed
+          - type: string
+          description: The values listed are the built-in ones; extensions may add
+            more.
+        validation_errors:
+          type: string
+          nullable: true
+        created_at:
+          type: string
+        updated_at:
+          type: string
+        import_id:
+          type: string
+          nullable: true
+        item_type:
+          type: string
+          nullable: true
+        item_id:
+          type: string
+          nullable: true
+      required:
+      - id
+      - row_number
+      - status
+      - validation_errors
+      - created_at
+      - updated_at
+      - import_id
+      - item_type
+      - item_id
+      x-typelizer: true
+    Import:
+      type: object
+      properties:
+        id:
+          type: string
+        number:
+          type: string
+        rows_count:
+          type: number
+        created_at:
+          type: string
+        updated_at:
+          type: string
+        type:
+          type: string
+          nullable: true
+          description: 'Import type. Built-in: products, product_translations, customers,
+            price_list_prices. Extensions may register more.'
+        status:
+          anyOf:
+          - type: string
+            enum:
+            - pending
+            - mapping
+            - completed_mapping
+            - processing
+            - completed
+            - failed
+          - type: string
+          description: The values listed are the built-in ones; extensions may add
+            more.
+        store_id:
+          type: string
+          nullable: true
+        seller_id:
+          type: string
+          nullable: true
+        owner_type:
+          type: string
+          nullable: true
+        owner_id:
+          type: string
+          nullable: true
+        user_id:
+          type: string
+          nullable: true
+      required:
+      - id
+      - number
+      - rows_count
+      - created_at
+      - updated_at
+      - type
+      - status
+      - store_id
+      - seller_id
+      - owner_type
+      - owner_id
+      - user_id
+      x-typelizer: true
     Invitation:
       type: object
       properties:
@@ -13917,6 +14157,32 @@ components:
       - xlarge_url
       - og_image_url
       x-typelizer: true
+    NewsletterSubscriberRequestEvent:
+      type: object
+      properties:
+        id:
+          type: string
+        email:
+          type: string
+        verification_token:
+          type: string
+        unsubscribe_token:
+          type: string
+        store_id:
+          type: string
+          nullable: true
+        customer_id:
+          type: string
+          nullable: true
+        redirect_url:
+          type: string
+      required:
+      - id
+      - email
+      - unsubscribe_token
+      - store_id
+      - customer_id
+      x-typelizer: true
     NewsletterSubscriber:
       type: object
       properties:
@@ -14329,6 +14595,26 @@ components:
       - gift_card
       - market
       x-typelizer: true
+    PasswordResetRequestedEvent:
+      type: object
+      properties:
+        id:
+          type: string
+        email:
+          type: string
+        reset_token:
+          type: string
+        store_id:
+          type: string
+          nullable: true
+        redirect_url:
+          type: string
+      required:
+      - id
+      - email
+      - reset_token
+      - store_id
+      x-typelizer: true
     PaymentMethod:
       type: object
       properties:
@@ -14955,6 +15241,40 @@ components:
       - original_price
       - seller_id
       x-typelizer: true
+    ProductSubmission:
+      type: object
+      properties:
+        id:
+          type: string
+        status:
+          anyOf:
+          - type: string
+            enum:
+            - pending
+            - approved
+            - rejected
+            - withdrawn
+          - type: string
+          description: The values listed are the built-in ones; extensions may add
+            more.
+        review_note:
+          type: string
+          nullable: true
+        reviewed_at:
+          type: string
+          nullable: true
+        created_at:
+          type: string
+        product_id:
+          type: string
+      required:
+      - id
+      - status
+      - review_note
+      - reviewed_at
+      - created_at
+      - product_id
+      x-typelizer: true
     ProductType:
       type: object
       properties:
@@ -14985,6 +15305,46 @@ components:
       - description
       - code
       x-typelizer: true
+    PurchaseOrderEvent:
+      type: object
+      properties:
+        id:
+          type: string
+        number:
+          type: string
+        status:
+          type: string
+        ordered_at:
+          type: string
+          nullable: true
+        received_at:
+          type: string
+          nullable: true
+        closed_short_at:
+          type: string
+          nullable: true
+        created_at:
+          type: string
+        updated_at:
+          type: string
+        supplier_id:
+          type: string
+          nullable: true
+        destination_location_id:
+          type: string
+          nullable: true
+      required:
+      - id
+      - number
+      - status
+      - ordered_at
+      - received_at
+      - closed_short_at
+      - created_at
+      - updated_at
+      - supplier_id
+      - destination_location_id
+      x-typelizer: true
     Refund:
       type: object
       properties:
@@ -15152,6 +15512,37 @@ components:
       - refunded_at
       - canceled_at
       x-typelizer: true
+    SavedReportEvent:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        description:
+          type: string
+          nullable: true
+        query:
+          type: object
+        seeded:
+          type: boolean
+        created_at:
+          type: string
+        updated_at:
+          type: string
+        user_id:
+          type: string
+          nullable: true
+      required:
+      - id
+      - name
+      - description
+      - query
+      - seeded
+      - created_at
+      - updated_at
+      - user_id
+      x-typelizer: true
     Seller:
       type: object
       properties:
@@ -15193,11 +15584,6 @@ components:
       properties:
         id:
           type: string
-        source:
-          type: string
-          enum:
-          - purchased
-          - uploaded
         status:
           anyOf:
           - type: string
@@ -15211,26 +15597,12 @@ components:
         carrier:
           type: string
           nullable: true
-        carrier_name:
-          type: string
-          nullable: true
         service:
           type: string
           nullable: true
         tracking_number:
           type: string
           nullable: true
-        currency:
-          type: string
-          nullable: true
-        format:
-          type: string
-          nullable: true
-        external_id:
-          type: string
-          nullable: true
-        metadata:
-          type: object
         refunded_at:
           type: string
           nullable: true
@@ -15243,42 +15615,19 @@ components:
         owner_type:
           type: string
           enum:
-          - Spree::Fulfillment
-          - Spree::Return
-        cost:
-          type: string
-        display_cost:
-          type: string
-        integration_id:
-          type: string
-          nullable: true
-        file_pending:
-          type: boolean
-        download_url:
-          type: string
-          nullable: true
+          - fulfillment
+          - return
       required:
       - id
-      - source
       - status
       - carrier
-      - carrier_name
       - service
       - tracking_number
-      - currency
-      - format
-      - external_id
-      - metadata
       - refunded_at
       - created_at
       - updated_at
       - owner_id
       - owner_type
-      - cost
-      - display_cost
-      - integration_id
-      - file_pending
-      - download_url
       x-typelizer: true
     State:
       type: object
@@ -15291,6 +15640,28 @@ components:
       - abbr
       - name
       x-typelizer: true
+    StockLevel:
+      type: object
+      properties:
+        id:
+          type: string
+        count_on_hand:
+          type: number
+        backorderable:
+          type: boolean
+        stock_location_id:
+          type: string
+          nullable: true
+        variant_id:
+          type: string
+          nullable: true
+      required:
+      - id
+      - count_on_hand
+      - backorderable
+      - stock_location_id
+      - variant_id
+      x-typelizer: true
     StockLocation:
       type: object
       properties:
@@ -15338,6 +15709,76 @@ components:
       - pickup_ready_in_minutes
       - pickup_instructions
       x-typelizer: true
+    StockMovement:
+      type: object
+      properties:
+        id:
+          type: string
+        quantity:
+          type: number
+        kind:
+          type: string
+          nullable: true
+          enum:
+          - received
+          - allocated
+          - shipped
+          - released
+          - adjusted
+        reason:
+          type: string
+          nullable: true
+        created_at:
+          type: string
+        updated_at:
+          type: string
+        stock_level_id:
+          type: string
+          nullable: true
+      required:
+      - id
+      - quantity
+      - kind
+      - reason
+      - created_at
+      - updated_at
+      - stock_level_id
+      x-typelizer: true
+    StockReceiptEvent:
+      type: object
+      properties:
+        id:
+          type: string
+        number:
+          type: string
+        quantity_accepted_total:
+          type: number
+        quantity_rejected_total:
+          type: number
+        received_at:
+          type: string
+        created_at:
+          type: string
+        updated_at:
+          type: string
+        receivable_type:
+          type: string
+          enum:
+          - purchase_order
+          - stock_transfer
+        receivable_id:
+          type: string
+      required:
+      - id
+      - number
+      - quantity_accepted_total
+      - quantity_rejected_total
+      - received_at
+      - created_at
+      - updated_at
+      - receivable_type
+      - receivable_id
+      x-typelizer: true
     StockReservation:
       type: object
       properties:
@@ -15346,6 +15787,33 @@ components:
       required:
       - id
       x-typelizer: true
+    StockTransfer:
+      type: object
+      properties:
+        id:
+          type: string
+        number:
+          type: string
+        reference:
+          type: string
+          nullable: true
+        created_at:
+          type: string
+        updated_at:
+          type: string
+        source_location_id:
+          type: string
+        destination_location_id:
+          type: string
+      required:
+      - id
+      - number
+      - reference
+      - created_at
+      - updated_at
+      - source_location_id
+      - destination_location_id
+      x-typelizer: true
     StoreCreditEvent:
       type: object
       properties:
@@ -15403,6 +15871,23 @@ components:
       - display_amount_remaining
       - currency
       x-typelizer: true
+    SupplierEvent:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        created_at:
+          type: string
+        updated_at:
+          type: string
+      required:
+      - id
+      - name
+      - created_at
+      - updated_at
+      x-typelizer: true
     TaxIdentifier:
       type: object
       properties:

package/dist/api-reference/webhooks-events.md

@@ -23,9 +23,9 @@ Every webhook delivery sends a JSON envelope with the event metadata and a `data
 | `name` | string | Event name (e.g., `order.placed`) |
 | `created_at` | string | ISO 8601 timestamp |
 | `data` | object | Serialized resource (see payloads below) |
-| `metadata` | object | Additional context: always the Spree version, plus event-specific keys such as `notify_customer` (fulfillment events — order events carry it in `data`) or `deprecated_alias_of` |
+| `metadata` | object | Additional context: always the Spree version, plus event-specific keys such as `notify_customer` or `deprecated_alias_of` |
 
-Event payloads use the same [Store API V3 serializers](introduction.md) as the REST API. All `id` fields use [prefixed IDs](introduction.md) (e.g., `or_m3Rp9wXz`, `prod_86Rf07xd4z`). All monetary values are strings. All timestamps are ISO 8601.
+Event payloads use the same [Store API V3 serializers](introduction.md) as the REST API, so they never carry back-office fields such as costs, internal notes or staff names. When you need those, fetch the record from the [Admin API](admin-api/introduction.md) using the `id` in the payload. All `id` fields use [prefixed IDs](introduction.md) (e.g., `or_m3Rp9wXz`, `prod_86Rf07xd4z`). All monetary values are strings. All timestamps are ISO 8601.
 
 For details on creating webhook endpoints and verifying signatures, see [Webhooks](../developer/core-concepts/webhooks.md). For the event system and the subscriber pattern, see [Events](../developer/core-concepts/events.md).
 
@@ -73,7 +73,7 @@ Events: `order.created`, `order.updated`, `order.deleted`, `order.placed`, `orde
 | `order.resend_confirmation_email` | An admin asked to send the order confirmation again |
 | `order.resend_digital_links_email` | An admin asked to send the download links again |
 
-The `order.placed` and `order.canceled` payloads also contain a `notify_customer` boolean. It is `false` when whoever placed or canceled the order asked for the customer not to be emailed.
+The `metadata` of `order.placed` and `order.canceled` contains a `notify_customer` boolean. It is `false` when whoever placed or canceled the order asked for the customer not to be emailed.
 
 Order payloads include nested `items`, `fulfillments`, `payments`, `discounts`, `fees`, `billing_address`, `shipping_address`, `gift_card`, and `market`.
 
@@ -171,7 +171,7 @@ Carts publish their own events, separate from orders. Use them to follow carts t
 
 Events: `order_group.created`, `order_group.updated`, `order_group.deleted`, `order_group.completed`
 
-When one checkout creates several orders (for example, one per seller), they belong to an order group. `order_group.completed` fires once every order in the group is placed. The payload includes the group's `number`, `email`, `currency`, `total`, `item_total`, `fulfillment_status`, `payment_status`, `completed_at`, the addresses, and the nested `orders`.
+When one checkout creates several orders (for example, one per seller), they belong to an order group. `order_group.completed` fires once every order in the group is placed. The payload includes the group's `number`, `email`, `currency`, `total`, `item_total`, `fulfillment_status`, `payment_status`, `completed_at`, the addresses, and the nested `orders`. Its `metadata` contains `notify_customer`, as on `order.placed`.
 
 ## Line Item Events
 
@@ -542,6 +542,21 @@ Events: `user.created`, `user.updated`, `user.deleted`, `customer.anonymized`, `
 
 Customer lifecycle events use the `user` prefix. Customer payloads include nested `addresses`, `default_billing_address`, `default_shipping_address`, `newsletter_subscriber`, and `customer_groups`.
 
+`customer.password_reset_requested` carries what you need to send the reset email yourself, rather than the customer record:
+
+```json
+{
+  "email": "customer@example.com",
+  "reset_token": "eyJfcmFpbHMiOnsi...",
+  "store_id": "store_UkLWZg9DAJ",
+  "redirect_url": "https://shop.example.com/account/reset-password"
+}
+```
+
+`redirect_url` is present only when the request included one.
+
+> **WARNING:** A reset token lets whoever holds it take over the account. `customer.password_reset_requested` is therefore sent only to endpoints that name it — never to an endpoint subscribed to `*` or `customer.*` — and subscribing to it needs the permission to manage customers. The staff and seller equivalents are never sent to webhooks at all: Spree sends those emails itself.
+
 ```json
 {
   "id": "cust_k5nR8xLq",
@@ -865,7 +880,7 @@ Events: `invitation.created`, `invitation.resent`, `invitation.accepted`
 
 ## Other Events
 
-These resources publish events too. Their payloads use the same serializers as the matching API responses.
+These resources publish events too. Back-office records (purchase orders, stock receipts, suppliers and shipping labels) send a short payload with their status, related record IDs and timestamps; fetch the rest from the Admin API.
 
 | Resource | Events |
 |---|---|

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

@@ -134,7 +134,13 @@ subscribes_to 'order.placed', async: false
 
 ## Publishing your own events
 
-Anything in your own code can announce something, and subscribers and webhooks treat it like any built-in event:
+Anything in your own code can announce something, and subscribers and webhooks treat it like any built-in event. Declare the event on the model first, then publish it:
+
+```ruby server/config/initializers/spree_events.rb
+Rails.application.config.to_prepare do
+  Spree::Order.publishes_event :flagged_for_review
+end
+```
 
 ```ruby server/app/services/fraud_check.rb
 order.publish_event('order.flagged_for_review')
@@ -142,6 +148,10 @@ order.publish_event('order.flagged_for_review')
 
 Useful when your own domain has moments worth reacting to — a fraud check completing, an approval granted.
 
+Every event Spree publishes is declared this way, which is what lets the admin dashboard's webhook picker, the [webhook events endpoint](webhooks.md#event-subscriptions) and the typed events in `@spree/sdk/webhooks` list it. Publishing an event nobody declared raises an error in development and test, so a typo is caught before it ships; in production it is logged and delivered anyway.
+
+The payload is the model's Store API serializer, as for built-in events. To send something else, pass a serializer of your own: `publishes_event :flagged_for_review, serializer: 'MyApp::FraudFlagEventSerializer'`. Keep it to what a customer could see; back-office fields belong behind the Admin API. Facts about the event rather than the record, such as who triggered it, go in its metadata: `order.publish_event('order.flagged_for_review', nil, rule: 'velocity')`.
+
 ## Guidance
 
 **Listen for the specific event.** `order.placed` rather than `order.updated` with a status check.

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

@@ -141,6 +141,28 @@ The `subscriptions` array accepts exact event names and wildcard patterns:
 | `['order.*', 'payment.*', 'fulfillment.fulfilled']` | Multiple patterns |
 | `[]` or `['*']` | All events |
 
+An event that carries a credential — `customer.password_reset_requested`, which includes a reset token — is never matched by a pattern. An endpoint receives it only when it names it, and naming it needs the permission to manage customers. Password reset requests for staff and sellers are never sent to webhooks: Spree emails those itself.
+
+To see every event you can subscribe to, including those your installed extensions add, list them:
+
+
+```typescript Admin SDK
+const { data: events } = await client.webhookEvents.list()
+// [{ name: 'order.placed', group: 'order', credential: false, deprecated: false, ... }, ...]
+```
+
+```bash CLI
+spree api get /webhook_events
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/admin/webhook_events' \
+  -H 'X-Spree-API-Key: sk_xxx'
+```
+
+
+Each entry says whether the event carries a credential (and which permission subscribing to it needs), and whether it is a deprecated name along with the event that replaces it.
+
 ## Webhook Payload
 
 Each webhook delivery sends a JSON payload with the following structure. The `data` object uses the same [Store API V3 serializers](../../api-reference/introduction.md) as the REST API, so webhook payloads and API responses share the same schema:
@@ -175,7 +197,9 @@ Each webhook delivery sends a JSON payload with the following structure. The `da
 | `name` | Event name (e.g., `order.placed`) |
 | `created_at` | ISO8601 timestamp when event occurred |
 | `data` | Serialized resource data (V3 API format with [prefixed IDs](../../api-reference/introduction.md)) |
-| `metadata` | Additional context including Spree version |
+| `metadata` | Additional context: the Spree version, plus facts about the event itself, such as `notify_customer` |
+
+Payloads carry what a customer could see, never back-office fields such as costs, internal notes or staff names. When an integration needs those, it fetches the record from the Admin API with the `id` in the payload, using a key scoped to what it may read.
 
 For complete payload schemas for each event type, see [Webhook Events & Payloads](../../api-reference/webhooks-events.md).
 
@@ -203,29 +227,49 @@ The [Spree Storefront](https://github.com/spree/storefront) includes a ready-mad
 
 #### Any JavaScript/TypeScript framework
 
-Use `@spree/sdk/webhooks` for framework-agnostic verification:
+Use `@spree/sdk/webhooks` for framework-agnostic verification. `constructWebhookEvent` checks the signature and returns a typed event: once you check `event.name`, `event.data` has the type of the record that event carries.
 
 ```typescript Store SDK
-import { verifyWebhookSignature } from '@spree/sdk/webhooks'
-import type { WebhookEvent } from '@spree/sdk/webhooks'
-import type { Order } from '@spree/sdk'
+import { constructWebhookEvent, WebhookVerificationError } from '@spree/sdk/webhooks'
+import { webhookEventSchemas } from '@spree/sdk/zod'
 
 // Hono, Cloudflare Workers, or any Web Fetch API-based framework
-app.post('/webhooks/spree', async (req, res) => {
-  const body = await req.text()
-  const signature = req.headers['x-spree-webhook-signature']
-  const timestamp = req.headers['x-spree-webhook-timestamp']
+app.post('/webhooks/spree', async (c) => {
+  let event
+  try {
+    event = constructWebhookEvent(await c.req.text(), c.req.raw.headers, process.env.SPREE_WEBHOOK_SECRET!, {
+      schemas: webhookEventSchemas, // optional: validate `data` at runtime
+    })
+  } catch (error) {
+    if (error instanceof WebhookVerificationError) return c.json({ error: 'Invalid signature' }, 401)
+    throw error
+  }
 
-  if (!verifyWebhookSignature(body, signature, timestamp, process.env.SPREE_WEBHOOK_SECRET!)) {
-    return res.status(401).json({ error: 'Invalid signature' })
+  switch (event.name) {
+    case 'order.placed':
+      await fulfil(event.data) // typed as Order
+      break
+    case 'customer.password_reset_requested':
+      await sendResetEmail(event.data.email, event.data.reset_token)
+      break
   }
 
-  const event: WebhookEvent<Order> = JSON.parse(body)
-  // handle event...
-  res.json({ received: true })
+  return c.json({ received: true })
 })
 ```
 
+Pass the body exactly as received: parsing and re-serializing it changes the bytes the signature covers. `verifyWebhookSignature` is still available when you only need the check.
+
+Events your own code or an extension publishes can be typed too, by adding them to `WebhookEventMap`:
+
+```typescript
+declare module '@spree/sdk/webhooks' {
+  interface WebhookEventMap {
+    'loyalty.points_earned': { id: string; points: number }
+  }
+}
+```
+
 #### Ruby
 
 ```ruby server/app/controllers/webhooks_controller.rb
@@ -324,7 +368,7 @@ SSL certificates are verified in production, and not in development — so you c
 
 ## Available Events
 
-Webhooks can subscribe to any event in Spree's event system. See [Webhook Events & Payloads](../../api-reference/webhooks-events.md) for the complete list.
+Webhooks can subscribe to any event in Spree's event system. See [Webhook Events & Payloads](../../api-reference/webhooks-events.md) for the complete list, or [list them through the Admin API](#event-subscriptions) to include the events your extensions add.
 
 Common webhook events include:
 

package/dist/developer/customization/email-variables.md

@@ -42,7 +42,8 @@ Each object's fields, and the fields of the objects nested in it.
 
 ### `store`
 
-- `store`: `id`, `name`, `address`, `mail_from_address`, `default_currency`, `default_locale`, `url`, `support_email`, `logo_url`, `logo_width`
+- `store`: `id`, `name`, `address`, `mail_from_address`, `default_currency`, `default_locale`, `url`, `support_email`, `logo_url`, `logo_width`, `branding`
+- `store.branding`: `background_color`, `card_color`, `text_color`, `heading_color`, `accent_color` (empty unless the merchant set one), `link_color`, `button_color`, `button_text_color`, `button_border`, `font`, `font_family`, `heading_font_family`, `font_url` (a web font's stylesheet, empty for email-safe fonts)
 
 ### `order`
 

package/dist/developer/customization/emails.md

@@ -8,7 +8,7 @@ Every email Spree sends — order confirmations, shipping notices, password rese
 
 To change an email, you copy its template into your app and edit it. Nothing else changes: Spree still picks the recipient, the language and the sender, and delivers the email through your [SMTP provider](../providers/emails.md).
 
-> **NOTE:** Templates read plain data — the same fields the [Store API](../../api-reference/store-api/introduction.md) returns, plus what only an email needs — never Ruby objects. The same template can later run outside Ruby, and merchants will be able to edit templates safely from the dashboard.
+> **NOTE:** Templates read plain data — the same fields the [Store API](../../api-reference/store-api/introduction.md) returns, plus what only an email needs — never Ruby objects. The same template can run outside Ruby, and merchants can edit customer emails safely from the dashboard.
 
 ## Where templates live
 
@@ -102,6 +102,73 @@ In development and test, a variable that does not exist raises an error instead
 
 To look at every email with real data, open the mailer previews at `/rails/mailers` on your Spree server.
 
+## Templates merchants edit in the dashboard
+
+Merchants can edit the emails their customers receive in **Settings → Emails → Templates**, along with the layout and the shared blocks in `spree/shared`. An edit is saved as a draft and goes live when published; publishing renders it with the store's own data first and refuses a template that does not render. An email built from a record the store does not have yet, such as an order confirmation in a store with no orders, is checked for template syntax only. Staff, store-owner and seller emails are not editable and always render from files.
+
+A store's published template comes first, so the lookup for an editable email is:
+
+1. the store's published template in the email's language
+2. the store's published template for every language
+3. your app's file
+4. Spree's file
+
+Your file stays the default the dashboard starts from and reverts to, so overriding a template in code and letting merchants edit it work together. When a Spree upgrade or a change to your file alters a default a merchant has customized, the dashboard tells them and shows what changed.
+
+The same operations are open to integrations through the [Admin API](../../api-reference/admin-api/introduction.md), with the `email_templates` permission:
+
+**Admin SDK:**
+
+```typescript
+    const preview = await client.emailTemplates.preview('spree.order_mailer.confirm_email', {
+      body: '<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name }}!</mj-text></mj-column></mj-section>',
+    })
+
+    await client.emailTemplates.draft.update('spree.order_mailer.confirm_email', {
+      body: '<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name }}!</mj-text></mj-column></mj-section>',
+    })
+    await client.emailTemplates.publish('spree.order_mailer.confirm_email')
+    ```
+
+  **cURL:**
+
+```bash
+    curl -X PUT https://your-store.com/api/v3/admin/email_templates/spree.order_mailer.confirm_email/draft \
+      -H "X-Spree-Api-Key: sk_xxx" -H "Content-Type: application/json" \
+      -d '{"body": "<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name }}!</mj-text></mj-column></mj-section>"}'
+
+    curl -X POST https://your-store.com/api/v3/admin/email_templates/spree.order_mailer.confirm_email/publication \
+      -H "X-Spree-Api-Key: sk_xxx"
+    ```
+
+
+### Branding
+
+Merchants set the colors and font of their customer emails in **Settings → Emails**, without touching a template. Templates read them from [`store.branding`](email-variables.md#store), and Spree's layout uses them throughout. If you override the layout or a template, read colors and fonts from `store.branding` rather than writing them in, so a store's branding keeps applying.
+
+### Making your own customer email editable
+
+A customer email your app adds can be edited like Spree's own. Register it with a class that builds the data its preview renders with:
+
+```ruby server/config/initializers/spree.rb
+Rails.application.config.after_initialize do
+  Spree.editable_email_templates.register(
+    'spree/review_mailer/request_email', kind: :email, sample: 'ReviewRequestSample'
+  )
+end
+```
+
+```ruby server/app/services/review_request_sample.rb
+# Previews with the store's latest completed order, or the one the merchant picks.
+class ReviewRequestSample < Spree::Emails::Samples::Order
+  def variables
+    { order: super[:order], review_url: placeholder_url('reviews/new') }
+  end
+end
+```
+
+A sample builds from the record the merchant picked, else the store's latest one; a store with none is told there is nothing to preview with yet. Pass placeholder URLs, never real tokens, and register only emails your customers receive.
+
 ## Your own mailers
 
 A mailer that inherits `Spree::BaseMailer` and renders its own ERB views with `mail` keeps working. Spree wraps its HTML in the same layout as every other email, so it carries the store's logo, header and footer. The `spree/shared/mailer_hero` and `spree/shared/mailer_button` partials are still there for those views.

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

@@ -495,6 +495,18 @@ now returns `nil` for an ID with another model's prefix, the same as
 `find_by_prefix_id`. Call `Spree::PrefixedId.decode_prefixed_id` if you
 really need to decode any prefix.
 
+## Every event is declared
+
+Events are now declared on the model that publishes them (`publishes_event`, `publishes_events`), and `publish_event` raises in development and test for a name nobody declared. Extensions that publish their own events need one line each — see [Publishing your own events](../core-concepts/events.md#publishing-your-own-events). In production an undeclared event is logged and still delivered.
+
+Some payloads changed so that every webhook carries the Store API shape and nothing more:
+
+- **`notify_customer` moved to `metadata`** on `order.placed`, `order.completed`, `order.canceled` and `order_group.completed`. Read `event.metadata['notify_customer']` in subscribers and `metadata.notify_customer` in webhook receivers.
+- **`customer.anonymized`** carries the customer record; the store and the requester moved to `metadata` (`store_id`, `requested_by_id`).
+- **Purchase order, stock receipt, supplier and shipping label events** carry a short payload — status, related record IDs and timestamps. Costs, notes, contact details and label files are read from the Admin API.
+- **`saved_report.*`** no longer includes the author's name.
+- **Subscribing an endpoint to `customer.password_reset_requested`** needs the permission to manage customers. The staff and seller reset events are still never sent to webhooks.
+
 ## Removed in 6.0
 
 These were deprecated in 5.x and are **gone now** — there is no bridge, so calls raise `NoMethodError`. Most were one-line delegations to a replacement that already exists.

package/package.json

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