@spree/docs 0.1.292 → 0.1.294

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/model-preferences.md

@@ -14,12 +14,14 @@ store.save
 
 To define a model preference, you need to add them to your model class.
 
-Make sure to generate a migration to add the `preferences` column to the table. This column will store the preferences in a serialized format.
+Make sure to generate a migration to add the `preferences` column to the table. This column stores the preferences as JSON.
 
 ```bash
-spree generate migration AddPreferencesToSpreeBrands preferences:text
+spree generate migration AddPreferencesToSpreeBrands preferences:jsonb
 ```
 
+`jsonb` is for PostgreSQL, the default database. On MySQL or SQLite use `preferences:json`.
+
 Run the migration.
 
 ```bash
@@ -90,7 +92,28 @@ You can get a hash of all stored preferences by accessing the `preferences` help
 brand.preferences # => { 'featured' => false, 'display_name' => 'Wilson' }
 ```
 
-This hash will contain the value for every preference that has been defined for the model instance, whether the value is the default or one that has been previously stored.
+This hash will contain the value for every preference that has been defined for the model instance, whether the value is the default or one that has been previously stored. Its keys are strings, and it can be read with either strings or symbols (`brand.preferences[:featured]`). Values are stored as JSON, so read typed values through the `preferred_*` methods: a `:decimal` preference comes back as a `BigDecimal` there, while the raw hash holds its exact string (`"9.99"`).
+
+`preferences` never holds secrets — see [Secret preferences](#secret-preferences).
+
+## Secret preferences
+
+Declare API keys, signing secrets and other credentials with the `:password` type:
+
+```ruby server/app/models/my_app/gateway.rb
+module MyApp
+  class Gateway < Spree::Gateway
+    preference :publishable_key, :string
+    preference :secret_key, :password
+  end
+end
+```
+
+A `:password` preference works like any other — `preferred_secret_key`, `preferred_secret_key = ...`, `get_preference(:secret_key)` — but it is stored apart from the other preferences, in an encrypted `secret_preferences` column, whenever [Active Record encryption keys](../deployment/environment_variables.md#active-record-encryption) are configured. The Admin API returns it masked, showing only its last four characters.
+
+Payment methods and integrations already have that column. To declare a secret on another model, include `Spree::SecretPreferences` and add a `secret_preferences` text column to its table; Spree refuses a `:password` preference on a model that cannot encrypt it.
+
+Always declare a credential as `:password`. A secret declared as `:string`, or nested inside a `:hash` or `:array` preference, is stored in plain text.
 
 ## Models with preferences
 

package/dist/developer/deployment/environment_variables.md

@@ -18,7 +18,7 @@ You'll almost always want to set [`RAILS_HOST`](#urls-and-hosts) too — without
 
 ## Active Record encryption
 
-Spree encrypts sensitive values at rest with [Active Record encryption](https://guides.rubyonrails.org/active_record_encryption.html): webhook endpoint signing secrets, payment gateway customer IDs, and the OAuth tokens stored on user identities. It does so only when encryption keys are configured — without them, these values are stored in plain text and a production app logs a warning at boot.
+Spree encrypts sensitive values at rest with [Active Record encryption](https://guides.rubyonrails.org/active_record_encryption.html): payment gateway and integration secrets (API keys and webhook signing secrets), webhook endpoint signing secrets, payment gateway customer IDs, and the OAuth tokens stored on user identities. It does so only when encryption keys are configured — without them, these values are stored in plain text and a production app logs a warning at boot.
 
 | Variable | Description |
 | --- | --- |

package/dist/developer/how-to/custom-payment-method.md

@@ -45,10 +45,16 @@ After restarting your server, you can select "MyGateway" when creating a new pay
 
 ### Show a logo and setup guide (optional)
 
-Payment providers also appear in the admin dashboard under **Settings > Integrations**. Declare a logo and a link to your setup guide so merchants recognise the provider and know how to connect it:
+Payment methods backed by an external provider also appear in the admin dashboard under **Settings > Integrations**, next to other connected services. A method is listed there when it inherits from `Spree::Gateway`, or when its class defines `self.third_party?` to return `true`. Declare a logo and a link to your setup guide so merchants recognise the provider and know how to connect it:
 
 ```ruby app/models/my_gateway.rb
 class MyGateway < Spree::PaymentMethod
+  # Lists MyGateway under Settings > Integrations. Not needed when the class
+  # inherits from Spree::Gateway.
+  def self.third_party?
+    true
+  end
+
   def self.logo_url
     'https://my-gateway.example.com/logo.svg'
   end

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

@@ -49,6 +49,24 @@ Re-running is safe — `bundle exec rake spree:upgrade` figures out what still n
 
 Reference material — the data backfills `bundle exec rake spree:upgrade` executes. Every task is idempotent.
 
+### Store preferences as JSON
+
+
+```bash Spree CLI (Docker)
+spree rake spree:upgrade:preferences_json
+spree rake spree:upgrade:encrypt_secret_preferences
+```
+
+```bash Without Spree CLI
+bundle exec rake spree:upgrade:preferences_json
+bundle exec rake spree:upgrade:encrypt_secret_preferences
+```
+
+
+Preferences were stored as YAML; in 6.0 they are JSON. The migration converts every `preferences` column itself, and moves gateway and integration secrets (preferences declared as `:password`) into a new `secret_preferences` column. The first task is a safety net for anything the migration could not reach — a schema changed by hand, or an extension gem installed after the migration ran. The second encrypts the moved secrets; until it runs they stay readable and are encrypted the next time their payment method or integration is saved. It does nothing until [encryption keys](#enable-active-record-encryption) are configured.
+
+See [Preferences are stored as JSON](#preferences-are-stored-as-json) for what changes in your code.
+
 ### Convert incomplete orders into carts
 
 ```bash
@@ -181,7 +199,7 @@ Countries and states are no longer database records in 6.0. Addresses, delivery
 
 ## Enable Active Record encryption
 
-Spree encrypts webhook endpoint signing secrets, payment gateway customer IDs and the OAuth tokens on user identities with [Active Record encryption](https://guides.rubyonrails.org/active_record_encryption.html) — but only when encryption keys are configured. Without keys these values are stored in plain text. New 6.0 projects get keys at setup; upgraded applications need to add them.
+Spree encrypts payment gateway and integration secrets, webhook endpoint signing secrets, payment gateway customer IDs and the OAuth tokens on user identities with [Active Record encryption](https://guides.rubyonrails.org/active_record_encryption.html) — but only when encryption keys are configured. Without keys these values are stored in plain text. New 6.0 projects get keys at setup; upgraded applications need to add them.
 
 **1. Make the app read the keys.** Projects created from `spree-starter` read them from the `ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY`, `ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY` and `ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT` env vars, falling back to the `active_record_encryption` entry in Rails credentials. If your `config/application.rb` predates this, add inside the `Application` class:
 
@@ -212,7 +230,31 @@ Recreate the containers so they pick up the new `.env` (`spree update`, or `spre
 
 > **WARNING:** Never change or lose the keys once data is encrypted — the encrypted records become unreadable.
 
-**3. Encrypt existing rows.** Rows written before the keys were set are plain text. OAuth tokens on user identities stay readable and are encrypted on their next write. Webhook endpoint secrets and gateway customer IDs can't be read in plain text once encryption is on — follow [Enabling encryption on an existing installation](../deployment/environment_variables.md#enabling-encryption-on-an-existing-installation): turn on `support_unencrypted_data` and `extend_queries`, deploy with the keys, run `find_each(&:encrypt)` over `Spree::WebhookEndpoint`, `Spree::GatewayCustomer` and `Spree::UserIdentity`, then turn the two settings off again.
+**3. Encrypt existing rows.** Rows written before the keys were set are plain text. Gateway and integration secrets and the OAuth tokens on user identities stay readable and are encrypted on their next write; run `spree rake spree:upgrade:encrypt_secret_preferences` (`bundle exec rake spree:upgrade:encrypt_secret_preferences` without the Spree CLI) to encrypt every gateway and integration secret at once. Webhook endpoint secrets and gateway customer IDs can't be read in plain text once encryption is on — follow [Enabling encryption on an existing installation](../deployment/environment_variables.md#enabling-encryption-on-an-existing-installation): turn on `support_unencrypted_data` and `extend_queries`, deploy with the keys, run `find_each(&:encrypt)` over `Spree::WebhookEndpoint`, `Spree::GatewayCustomer` and `Spree::UserIdentity`, then turn the two settings off again.
+
+## Preferences are stored as JSON
+
+Model preferences moved from YAML to JSON, and secrets moved out of them. Declarations do not change, and the `preferred_*` methods return the same values as before. What can affect your code:
+
+- **The raw `preferences` hash has string keys.** It still answers to symbols (`calculator.preferences[:amount]`), but `preferences.keys` returns strings. Decimals sit in it as exact strings (`"9.99"`); read them through `preferred_*`, which returns a `BigDecimal`.
+- **Secrets are not in `preferences`.** Preferences declared `:password` live in the encrypted `secret_preferences` column. Read them with `preferred_*` or `get_preference`. A secret you assign as part of a whole hash (`update(preferences: { secret_key: ... })`) is moved there when the record is saved. To declare a secret on a model other than a payment method or an integration, see [Secret preferences](../customization/model-preferences.md#secret-preferences).
+- **Your own preference tables need a JSON column.** The migration converts every table a model storing Spree preferences reads, including your application's own; a table another library owns is left alone. A new table should use `t.jsonb :preferences` on PostgreSQL, the default database (`t.json` on MySQL or SQLite).
+- **Tiered calculators take a list of tiers.** `Spree::Calculator::TieredPercent` and `TieredFlatRate` store `tiers` as a list instead of a hash keyed by threshold, in Ruby and in the Admin API. The migration converts existing calculators.
+
+  ```json
+  // Before
+  { "tiers": { "100": 10, "250": 15 } }
+  // After
+  { "tiers": [{ "threshold": "100", "value": "10" }, { "threshold": "250", "value": "15" }] }
+  ```
+
+  `value` is a percentage for `TieredPercent` and an amount for `TieredFlatRate`.
+- **Spree no longer allows extra classes in YAML columns.** It used to add `Symbol`, `BigDecimal` and a few time classes to `config.active_record.yaml_column_permitted_classes`. If your application serializes its own columns as YAML with those classes, add them in `config/application.rb` yourself.
+- **Preference change methods follow Rails' naming.** Each preference is a Rails store accessor, so `preferred_<name>_changed?`, `preferred_<name>_change` and `preferred_<name>_was` work as before, while the after-save forms are Rails' own: `saved_change_to_preferred_<name>?` replaces `preferred_<name>_previously_changed?`, `saved_change_to_preferred_<name>` replaces `preferred_<name>_previous_change`, and `preferred_<name>_before_last_save` replaces `preferred_<name>_previously_was`.
+- **Per-preference helper methods are gone.** Use `preference_type(:name)`, `preference_default(:name)` and `preference_deprecated(:name)` instead of `preferred_<name>_type`, `preferred_<name>_default` and `preferred_<name>_deprecated`. `clear_preferences`, `restore_preferences_for`, `preferences_of_type`, the class methods `preference_getter_method`, `preference_setter_method` and `prefers_query_method`, `Spree::Preferences::ScopedStore`, `Spree::Preferences::Store` and the `Spree::Preference` model are removed.
+- **The `spree_preferences` table is dropped.** The installation id it held is not carried over: the default store generates a new one the next time it is saved. Rows an application wrote there itself are dropped with it: copy any you need before upgrading.
+- **Preferences live only on models.** `Spree::Preferences::Preferable` is included by `Spree::Base` and needs a `preferences` JSON column; including it in a plain Ruby class is no longer supported. A hash stored inside a preference comes back with string keys.
+- **A record whose preferences still hold YAML cannot be read.** The migration converts every row, so this only happens to rows written by older code after it ran. Run `spree rake spree:upgrade:preferences_json` (`bundle exec rake spree:upgrade:preferences_json` without the Spree CLI) to convert it.
 
 ## The Cart/Order split
 
@@ -453,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.292",
+  "version": "0.1.294",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",