@spree/docs 0.1.279 → 0.1.281

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

@@ -224,6 +224,8 @@ To add your own step or requirement, see
 
 Each [fulfillment](fulfillments.md) offers delivery rates. Pick one per fulfillment.
 
+    A cart has no fulfillments until it has a shipping address or a pickup location, unless none of its items ships to an address (a digital-only cart has them straight away). Saving a different address replaces the fulfillments, under new ids, with the cheapest shipping rate selected, so show the customer the new options before taking payment.
+
     ```typescript Store SDK
     const cart = await client.carts.get(cartId)
     await client.carts.fulfillments.update(cartId, cart.fulfillments[0].id, {

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

@@ -0,0 +1,114 @@
+---
+title: Email Template Variables
+sidebarTitle: Template Variables
+description: Every variable the Liquid templates of customer emails receive, email by email.
+---
+
+These are the emails your customers receive. Every one of their templates receives `store` and `locale`, plus the variables listed for it below. Use these names exactly: a variable not listed here does not exist, and in development and test it raises an error. See [Email Templates](emails.md) for how to override a template.
+
+## Emails
+
+| Template | Variables |
+| --- | --- |
+| `spree/order_mailer/confirm_email` | `order`, `resend` |
+| `spree/order_mailer/cancel_email` | `order`, `resend` |
+| `spree/order_mailer/payment_link_email` | `order`, `payment_url` |
+| `spree/order_group_mailer/confirm_email` | `order_group`, `resend` |
+| `spree/fulfillment_mailer/fulfilled_email` | `fulfillment`, `order`, `resend` |
+| `spree/return_mailer/refunded_email` | `return`, `order`, `resend` |
+| `spree/digital_asset_mailer/files_ready_email` | `order`, `downloads`, `resend` |
+| `spree/customer_mailer/password_reset_email` | `customer`, `reset_url` |
+| `spree/customer_mailer/data_export_email` | `download_url`, `expires_at` |
+| `spree/newsletter_mailer/email_confirmation` | `confirmation_url` |
+| `spree/company_mailer/invitation_email` | `company`, `accept_url` |
+
+## Values
+
+| Variable | What it holds |
+| --- | --- |
+| `resend` | True when staff re-sent the email. |
+| `locale` | The language the email renders in, e.g. `en`. |
+| `payment_url` | Where the customer pays for the order. |
+| `reset_url` | The password reset link, carrying its token. |
+| `accept_url` | The link that accepts the invitation, carrying its token. |
+| `confirmation_url` | The link that confirms the subscription, carrying its token. |
+| `download_url` | The signed link to the customer's data export. |
+| `expires_at` | When the data export link stops working. |
+| `downloads` | Each file bought: `filename`, `url` (carrying its token) and `expires_at`. |
+
+## Objects
+
+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`
+
+### `order`
+
+- `order`: `id`, `market_id`, `withdrawal_period_ends_at`, `within_withdrawal_period`, `cart_id`, `channel_id`, `company_id`, `company_name`, `po_document_filename`, `po_document_byte_size`, `number`, `email`, `customer_note`, `po_number`, `currency`, `locale`, `total_quantity`, `coupon_code`, `fulfillment_status`, `payment_status`, `completed_at`, `item_total`, `display_item_total`, `adjustment_total`, `display_adjustment_total`, `discount_total`, `display_discount_total`, `tax_total`, `display_tax_total`, `included_tax_total`, `display_included_tax_total`, `additional_tax_total`, `display_additional_tax_total`, `total`, `display_total`, `gift_card_total`, `display_gift_card_total`, `amount_due`, `display_amount_due`, `delivery_total`, `display_delivery_total`, `fee_total`, `display_fee_total`, `store_credit_total`, `display_store_credit_total`, `covered_by_store_credit`, `customer_name`, `display_total_minus_store_credits`
+- `order.discounts`: `id`, `promotion_id`, `name`, `description`, `code`, `amount`, `display_amount`
+- `order.fees`: `id`, `label`, `kind`, `line_item_id`, `fulfillment_id`, `amount`, `display_amount`
+- `order.items`: `id`, `variant_id`, `seller_id`, `preorder`, `preorder_ships_at`, `quantity`, `currency`, `name`, `slug`, `options_text`, `price`, `display_price`, `total`, `display_total`, `adjustment_total`, `display_adjustment_total`, `additional_tax_total`, `display_additional_tax_total`, `included_tax_total`, `display_included_tax_total`, `discount_total`, `display_discount_total`, `pre_tax_amount`, `display_pre_tax_amount`, `discounted_amount`, `display_discounted_amount`, `display_compare_at_amount`, `compare_at_amount`, `url`, `image_url`, `sku`, `display_amount`
+- `order.items.option_values`: `id`, `option_type_id`, `name`, `label`, `position`, `color_code`, `option_type_name`, `option_type_label`, `image_url`
+- `order.fulfillments`: `id`, `number`, `tracking`, `tracking_url`, `pickup_point_data`, `selected_delivery_rate_id`, `unpriced`, `cost`, `display_cost`, `total`, `display_total`, `discount_total`, `display_discount_total`, `additional_tax_total`, `display_additional_tax_total`, `included_tax_total`, `display_included_tax_total`, `tax_total`, `display_tax_total`, `status`, `fulfillment_type`, `fulfilled_at`, `delivered_at`, `items`
+- `order.fulfillments.deliveries`: `id`, `tracking_number`, `carrier`, `carrier_name`, `service`, `status`, `tracking_url`, `estimated_delivery_at`, `delivered_at`
+- `order.fulfillments.delivery_method`: `id`, `name`, `code`, `estimated_transit_business_days_min`, `estimated_transit_business_days_max`, `digital`, `pickup`, `pickup_point`
+- `order.fulfillments.stock_location`: `id`, `name`, `address1`, `city`, `zipcode`, `country_code`, `country_name`, `state_code`, `state_text`, `pickup_ready_in_minutes`, `pickup_instructions`
+- `order.fulfillments.delivery_rates`: `id`, `delivery_method_id`, `name`, `selected`, `cost`, `total`, `additional_tax_total`, `included_tax_total`, `tax_total`, `carrier`, `service_level`, `estimated_delivery_date`, `unpriced`, `display_cost`, `display_total`, `display_additional_tax_total`, `display_included_tax_total`, `display_tax_total`
+- `order.payments`: `id`, `payment_method_id`, `response_code`, `number`, `status`, `amount`, `display_amount`, `source_type`, `source_id`, `source`
+- `order.payments.payment_method`: `id`, `name`, `description`, `type`, `session_required`, `source_required`
+- `order.billing_address`: `id`, `label`, `first_name`, `last_name`, `full_name`, `address1`, `address2`, `postal_code`, `city`, `phone`, `company`, `country_name`, `country_code`, `state_text`, `state_code`, `quick_checkout`, `is_default_billing`, `is_default_shipping`, `state_abbr`, `country_iso`, `state_name`
+- `order.shipping_address`: `id`, `label`, `first_name`, `last_name`, `full_name`, `address1`, `address2`, `postal_code`, `city`, `phone`, `company`, `country_name`, `country_code`, `state_text`, `state_code`, `quick_checkout`, `is_default_billing`, `is_default_shipping`, `state_abbr`, `country_iso`, `state_name`
+- `order.gift_card`: `id`, `code`, `status`, `currency`, `amount`, `amount_used`, `amount_authorized`, `amount_remaining`, `display_amount`, `display_amount_used`, `display_amount_remaining`, `expires_at`, `redeemed_at`, `expired`, `active`
+- `order.market`: `id`, `name`, `currency`, `default_locale`, `tax_inclusive`, `default`, `country_codes`, `country_isos`, `supported_locales`
+- `order.promotion_discounts`: `label`, `display_amount`, `amount`
+- `order.manual_discounts`: `label`, `display_amount`, `amount`
+- `order.fee_lines`: `label`, `display_amount`, `amount`
+- `order.delivery_lines`: `label`, `display_amount`, `amount`
+
+### `order_group`
+
+- `order_group`: `id`, `number`, `email`, `currency`, `total`, `display_total`, `item_total`, `display_item_total`, `fulfillment_status`, `payment_status`, `completed_at`, `customer_name`, `display_total_minus_store_credits`, `po_number`, `order_count`, `display_delivery_total`, `delivery_total`, `additional_tax_total`, `display_additional_tax_total`, `gift_card_total`, `display_gift_card_total`
+- `order_group.billing_address`: `id`, `label`, `first_name`, `last_name`, `full_name`, `address1`, `address2`, `postal_code`, `city`, `phone`, `company`, `country_name`, `country_code`, `state_text`, `state_code`, `quick_checkout`, `is_default_billing`, `is_default_shipping`, `state_abbr`, `country_iso`, `state_name`
+- `order_group.shipping_address`: `id`, `label`, `first_name`, `last_name`, `full_name`, `address1`, `address2`, `postal_code`, `city`, `phone`, `company`, `country_name`, `country_code`, `state_text`, `state_code`, `quick_checkout`, `is_default_billing`, `is_default_shipping`, `state_abbr`, `country_iso`, `state_name`
+- `order_group.items`: `id`, `variant_id`, `seller_id`, `preorder`, `preorder_ships_at`, `quantity`, `currency`, `name`, `slug`, `options_text`, `price`, `display_price`, `total`, `display_total`, `adjustment_total`, `display_adjustment_total`, `additional_tax_total`, `display_additional_tax_total`, `included_tax_total`, `display_included_tax_total`, `discount_total`, `display_discount_total`, `pre_tax_amount`, `display_pre_tax_amount`, `discounted_amount`, `display_discounted_amount`, `display_compare_at_amount`, `compare_at_amount`, `url`, `image_url`, `sku`, `display_amount`
+- `order_group.items.option_values`: `id`, `option_type_id`, `name`, `label`, `position`, `color_code`, `option_type_name`, `option_type_label`, `image_url`
+- `order_group.promotion_discounts`: `label`, `display_amount`, `amount`
+- `order_group.manual_discounts`: `label`, `display_amount`, `amount`
+- `order_group.fee_lines`: `label`, `display_amount`, `amount`
+- `order_group.fulfillment_groups`: `name`, `display_cost`, `seller_names`
+- `order_group.fulfillment_groups.items`: `id`, `url`, `image_url`, `name`, `quantity`, `sku`, `options_text`, `display_price`, `display_amount`
+- `order_group.unfulfilled_items`: `id`, `variant_id`, `seller_id`, `preorder`, `preorder_ships_at`, `quantity`, `currency`, `name`, `slug`, `options_text`, `price`, `display_price`, `total`, `display_total`, `adjustment_total`, `display_adjustment_total`, `additional_tax_total`, `display_additional_tax_total`, `included_tax_total`, `display_included_tax_total`, `discount_total`, `display_discount_total`, `pre_tax_amount`, `display_pre_tax_amount`, `discounted_amount`, `display_discounted_amount`, `display_compare_at_amount`, `compare_at_amount`, `url`, `image_url`, `sku`, `display_amount`
+- `order_group.unfulfilled_items.option_values`: `id`, `option_type_id`, `name`, `label`, `position`, `color_code`, `option_type_name`, `option_type_label`, `image_url`
+- `order_group.delivery_lines`: `label`, `display_amount`, `amount`
+
+### `fulfillment`
+
+- `fulfillment`: `id`, `number`, `tracking`, `tracking_url`, `pickup_point_data`, `selected_delivery_rate_id`, `unpriced`, `cost`, `display_cost`, `total`, `display_total`, `discount_total`, `display_discount_total`, `additional_tax_total`, `display_additional_tax_total`, `included_tax_total`, `display_included_tax_total`, `tax_total`, `display_tax_total`, `status`, `fulfillment_type`, `fulfilled_at`, `delivered_at`, `items`, `delivery_method_name`
+- `fulfillment.deliveries`: `id`, `tracking_number`, `carrier`, `carrier_name`, `service`, `status`, `tracking_url`, `estimated_delivery_at`, `delivered_at`
+- `fulfillment.delivery_method`: `id`, `name`, `code`, `estimated_transit_business_days_min`, `estimated_transit_business_days_max`, `digital`, `pickup`, `pickup_point`
+- `fulfillment.stock_location`: `id`, `name`, `address1`, `city`, `zipcode`, `country_code`, `country_name`, `state_code`, `state_text`, `pickup_ready_in_minutes`, `pickup_instructions`
+- `fulfillment.delivery_rates`: `id`, `delivery_method_id`, `name`, `selected`, `cost`, `total`, `additional_tax_total`, `included_tax_total`, `tax_total`, `carrier`, `service_level`, `estimated_delivery_date`, `unpriced`, `display_cost`, `display_total`, `display_additional_tax_total`, `display_included_tax_total`, `display_tax_total`
+- `fulfillment.delivery_rates.freight_summary`: `total_units`, `total_cartons`, `total_pallets`, `total_volume`, `total_weight`, `complete`
+- `fulfillment.delivery_rates.delivery_method`: `id`, `name`, `code`, `estimated_transit_business_days_min`, `estimated_transit_business_days_max`, `digital`, `pickup`, `pickup_point`
+- `fulfillment.manifest_items`: `id`, `url`, `image_url`, `name`, `quantity`, `sku`, `options_text`, `display_price`, `display_amount`
+
+### `return`
+
+- `return`: `id`, `number`, `status`, `order_id`, `reason_id`, `refund_total`, `display_refund_total`, `approved_at`, `received_at`, `refunded_at`, `canceled_at`, `display_refunded_total`
+- `return.returned_items`: `id`, `variant_id`, `seller_id`, `preorder`, `preorder_ships_at`, `quantity`, `currency`, `name`, `slug`, `options_text`, `price`, `display_price`, `total`, `display_total`, `adjustment_total`, `display_adjustment_total`, `additional_tax_total`, `display_additional_tax_total`, `included_tax_total`, `display_included_tax_total`, `discount_total`, `display_discount_total`, `pre_tax_amount`, `display_pre_tax_amount`, `discounted_amount`, `display_discounted_amount`, `display_compare_at_amount`, `compare_at_amount`, `url`, `image_url`, `sku`, `display_amount`
+- `return.returned_items.option_values`: `id`, `option_type_id`, `name`, `label`, `position`, `color_code`, `option_type_name`, `option_type_label`, `image_url`
+
+### `customer`
+
+- `customer`: `id`, `email`, `first_name`, `last_name`, `phone`, `accepts_email_marketing`, `email_marketing_consent_updated_at`, `full_name`, `available_store_credit_total`, `display_available_store_credit_total`
+- `customer.addresses`: `id`, `label`, `first_name`, `last_name`, `full_name`, `address1`, `address2`, `postal_code`, `city`, `phone`, `company`, `country_name`, `country_code`, `state_text`, `state_code`, `quick_checkout`, `is_default_billing`, `is_default_shipping`, `state_abbr`, `country_iso`, `state_name`
+- `customer.default_billing_address`: `id`, `label`, `first_name`, `last_name`, `full_name`, `address1`, `address2`, `postal_code`, `city`, `phone`, `company`, `country_name`, `country_code`, `state_text`, `state_code`, `quick_checkout`, `is_default_billing`, `is_default_shipping`, `state_abbr`, `country_iso`, `state_name`
+- `customer.default_shipping_address`: `id`, `label`, `first_name`, `last_name`, `full_name`, `address1`, `address2`, `postal_code`, `city`, `phone`, `company`, `country_name`, `country_code`, `state_text`, `state_code`, `quick_checkout`, `is_default_billing`, `is_default_shipping`, `state_abbr`, `country_iso`, `state_name`
+- `customer.newsletter_subscriber`: `id`, `email`, `created_at`, `updated_at`, `verified`, `verified_at`, `customer_id`
+- `customer.customer_groups`: `id`, `name`
+
+### `company`
+
+- `company`: `id`, `name`, `kind`, `po_number_required`, `parent_id`, `ancestors`

package/dist/developer/customization/emails.md

@@ -0,0 +1,132 @@
+---
+title: Email Templates
+sidebarTitle: Emails
+description: Change what Spree's transactional emails say and look like, with Liquid templates written in MJML.
+---
+
+Every email Spree sends — order confirmations, shipping notices, password resets, staff invitations — renders from a **Liquid** template written in **MJML**. Liquid fills in the data; MJML turns a dozen layout tags into the nested tables, inline styles and Outlook workarounds that email clients need, and makes the email stack on phones.
+
+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.
+
+## Where templates live
+
+A template sits at its email's path with a `.liquid` extension. To override one, create the file at the same path in your app:
+
+| Email | Template |
+| --- | --- |
+| Order confirmation | `server/app/views/spree/order_mailer/confirm_email.liquid` |
+| Shipping notification | `server/app/views/spree/fulfillment_mailer/fulfilled_email.liquid` |
+| Customer password reset | `server/app/views/spree/customer_mailer/password_reset_email.liquid` |
+| The layout around every email | `server/app/views/layouts/spree/base_mailer.liquid` |
+
+The path is also the template's name, for example `spree/order_mailer/confirm_email`. [Email Template Variables](email-variables.md) lists every customer email's template and the data it receives.
+
+Start from Spree's own template rather than a blank file: customer emails are in [`spree/emails/app/views`](https://github.com/spree/spree/tree/main/spree/emails/app/views/spree) and staff emails and the layout in [`spree/core/app/views`](https://github.com/spree/spree/tree/main/spree/core/app/views) on GitHub.
+
+Your file wins as soon as it exists, and edits to it show on the next email without a restart. There is nothing to register. The one exception: Rails only reads `server/app/views` if the folder existed when the app started, so restart once after creating that folder. API-only apps often start without it.
+
+## Anatomy of a template
+
+```liquid server/app/views/spree/order_mailer/confirm_email.liquid
+---
+subject: "{{ store.name }} {{ 'order_mailer.confirm_email.subject' | t }} #{{ order.number }}"
+---
+<mj-section>
+  <mj-column css-class="hero">
+    <mj-text mj-class="heading">Thanks for your order!</mj-text>
+    <mj-text mj-class="greeting">Hi {{ order.customer_name }},</mj-text>
+    <mj-button href="{{ store.url }}/account/orders/{{ order.number }}">View your order</mj-button>
+  </mj-column>
+</mj-section>
+{% assign heading = 'order_mailer.confirm_email.order_summary' | t: number: order.number %}
+{% render 'spree/shared/order_summary', heading: heading, purchase: order, items: order.items, totals: true %}
+```
+
+- **The subject** is the `subject` line at the top, and it is Liquid too.
+- **The body** is a list of MJML sections. The layout wraps it with the store's logo and footer.
+- **Copy** either comes from Spree's translations through the `t` filter, which keeps one template working in every language, or is written straight into the template for a single-language store.
+
+The layout defines named styles you can use through `mj-class`: `heading`, `greeting`, `lead`, `note`, `section-heading` and `body`. For the MJML tags themselves, see the [MJML documentation](https://documentation.mjml.io).
+
+## Partials
+
+Pull a shared piece in with `{% render %}`. The name maps to a file with a leading underscore, as Rails partials do: `'spree/shared/line_item'` is `app/views/spree/shared/_line_item.liquid`. A partial only sees the values you pass it.
+
+| Partial | Arguments | What it renders |
+| --- | --- | --- |
+| `spree/shared/order_summary` | `heading`, `purchase`, `items`, `totals` | A headed list of purchased items, with the order's totals when `totals` is true |
+| `spree/shared/line_item` | `item` | One purchased item: thumbnail, name, options, quantity and amount |
+| `spree/shared/purchase_totals` | `purchase` | Subtotal, discounts, delivery, tax, gift card, fees and total |
+| `spree/shared/fulfillment_group` | `group`, `position`, `count` | One parcel of a multi-seller purchase |
+| `spree/shared/summary_row` | `label`, `value`, `sub`, `total`, `translate` | One label and amount row inside an `<mj-table css-class="summary">` |
+
+Override a partial the same way as a template, by creating the file at its path in your app. Every email that uses it changes.
+
+## Filters
+
+Besides [Liquid's standard filters](https://shopify.github.io/liquid/filters/abs/), templates have these. The names follow common Liquid conventions where they mean the same thing.
+
+| Filter | Example | Result |
+| --- | --- | --- |
+| `money` | `{{ '10.5' \| money }}` | `$10.50`, in the email's currency |
+| `money_with_currency` | `{{ '10.5' \| money_with_currency }}` | `$10.50 USD` |
+| `date` | `{{ order.completed_at \| date: 'long' }}` | A date in the store's time zone. Takes a named format (`short`, `long`, `default`) or a `strftime` pattern such as `'%Y-%m-%d'` |
+| `t` | `{{ 'order_mailer.confirm_email.dear_customer' \| t: name: order.customer_name }}` | A Spree translation, with its placeholders filled in |
+| `raw` | `{{ product.description_html \| raw }}` | Prints the value without escaping. See below |
+
+Most amounts already arrive formatted, as `display_total`, `display_amount` and the like, so `money` is only needed for a raw amount.
+
+## Escaping
+
+Everything a template prints is HTML-escaped. A customer who types `<a href="https://evil.test">Click to verify</a>` as their name sees that text in the email, not a live link — and so does the store owner reading the new-order notification.
+
+`raw` turns escaping off for one value. Only use it for HTML that was cleaned when it was saved, such as a product's rich-text description. Never use it on a name, an address or a note.
+
+## The plain-text version
+
+Spree builds each email's plain-text version from its HTML, writing links as `label (url)`, so the two can never drift apart. To write the text by hand instead, add a `.text.liquid` file next to the template:
+
+```liquid server/app/views/spree/order_mailer/confirm_email.text.liquid
+Thanks for your order {{ order.number }}, {{ order.customer_name }}.
+
+Total: {{ order.display_total }}
+```
+
+Nothing is escaped in the text version.
+
+## Mistakes surface in development
+
+In development and test, a variable that does not exist raises an error instead of printing nothing, so `{{ order.nubmer }}` fails your spec rather than sending a blank. In production it prints nothing. A template that loops endlessly fails that one email instead of stalling your background jobs.
+
+To look at every email with real data, open the mailer previews at `/rails/mailers` on your Spree server.
+
+## 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.
+
+To give a new email the same data contract as Spree's own, render it from a Liquid template instead:
+
+```ruby server/app/mailers/spree/welcome_mailer.rb
+module Spree
+  class WelcomeMailer < BaseMailer
+    def welcome_email(customer, store)
+      @current_store = store
+
+      with_store_locale(store) do
+        mail_template({ customer: email_data(customer, Spree.api.customer_serializer) }, to: customer.email)
+      end
+    end
+  end
+end
+```
+
+The template goes at `server/app/views/spree/welcome_mailer/welcome_email.liquid`. `email_data` serializes a record the way templates read it; pass a URL that carries a token as its own variable rather than serializing it.
+
+## Related
+
+- [Email Template Variables](email-variables.md) — every customer email and the data it receives
+- [Upgrading from 5.6 to 6.0](../upgrades/5.6-to-6.0.md#emails-render-from-liquid-templates) — moving ERB email overrides to Liquid
+- [Sending out Emails](../deployment/emails.md) — which emails Spree sends, and handing customer emails to your storefront
+- [Emails provider setup](../providers/emails.md) — SMTP configuration

package/dist/developer/deployment/emails.md

@@ -13,7 +13,7 @@ Spree handles two categories of emails:
 
 ## Customer-Facing Emails
 
-By default, **Spree sends all customer transactional emails itself**. This works for every client of the API: mobile apps, custom frontends, POS integrations — no storefront required. Delivery uses the same [SMTP configuration](#configuration) as system emails.
+By default, **Spree sends all customer transactional emails itself**. This works for every client of the API: mobile apps, custom frontends, POS integrations — no storefront required. Delivery uses the same [SMTP configuration](#configuration) as system emails, and every email renders from a Liquid template you can override — see [Email Templates](../customization/emails.md).
 
 Customer emails can be turned off in the admin under **Settings → Emails** — do this when your storefront takes over sending them (below), otherwise customers receive both.
 

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

@@ -690,6 +690,29 @@ Nothing in 5.6 could reach it: there was no API endpoint and no admin screen, so
 
 If you subclassed `Spree::Report` in your own application, that class no longer has a superclass and will raise on boot. Move the question to one of the two replacements above.
 
+## Emails render from Liquid templates
+
+Every transactional email now renders from a Liquid template written in MJML instead of an ERB view. Templates read serializer data rather than models, keep their Rails view paths, carry their subject line, and get a plain-text version generated from the HTML. See [Email Templates](../customization/emails.md) for how they work.
+
+**If your app overrides no emails, there is nothing to do.** The emails look the same.
+
+**If your app overrides Spree's emails with ERB**, those files are no longer used and Spree sends its default design instead, without a warning. Look for them under `app/views/spree/*_mailer/` and `app/views/spree/shared/`, and port each to the `.liquid` file at the same path:
+
+| ERB view (removed) | Liquid template |
+| --- | --- |
+| `spree/shared/_base_mailer_header`, `_base_mailer_footer`, `_base_mailer_stylesheets`, `_mailer_logo`, `_purchased_items_styles` | `layouts/spree/base_mailer.liquid` |
+| `spree/shared/_order_summary_section`, `_purchased_items_table`, `purchased_items_table/*` | `spree/shared/_order_summary.liquid`, `_line_item.liquid`, `_purchase_totals.liquid`, `_summary_row.liquid` |
+| `spree/shared/_fulfillment_group_section`, `_purchase_totals` | `spree/shared/_fulfillment_group.liquid`, `_purchase_totals.liquid` |
+| `spree/<mailer>/<email>.html.erb` and `.text.erb`, for every mailer | `spree/<mailer>/<email>.liquid`, plus an optional `<email>.text.liquid` |
+
+Other changes that come with it:
+
+- **Subjects moved into the templates.** Each template's front matter holds its subject. `Spree::BaseMailer#order_email_subject` is removed.
+- **The mailer view helpers are removed.** `Spree::MailHelper` (`name_for`), `Spree::BaseHelper` (`spree_storefront_resource_url`), `Spree::FulfillmentHelper` and `Spree::DigitalAssetHelper` are gone. Templates get the same values as serializer fields, such as `order.customer_name` and `item.url`.
+- **Every email has a plain-text part**, generated from the HTML. Seven emails that had none now have one.
+- **Alba moved into `spree_core`**, with its configuration, so core's staff emails render in installations without `spree_api`.
+- **Your own mailers keep working.** A mailer that inherits `Spree::BaseMailer` and calls `mail` with its own ERB views is wrapped in the new email layout, and the `spree/shared/mailer_hero` and `mailer_button` partials remain for its views. See [Your own mailers](../customization/emails.md#your-own-mailers).
+
 ## Deprecated in 6.0, removed in 6.1
 
 Every rename keeps the legacy name working for one release with a deprecation warning. The notable ones:

package/package.json

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