@spree/docs 0.1.278 → 0.1.280

package/dist/api-reference/store-api/localization.md

@@ -128,6 +128,16 @@ Each value is resolved in the following order:
 
 > **NOTE:** The locale and currency must be supported by the current store. If an unsupported value is provided, the API falls back to the store's default.
 
+### Caching
+
+Cacheable guest responses (products, categories, collections, markets, locales, currencies, policies, sellers) are sent with `Cache-Control: public` and:
+
+```
+Vary: Accept, X-Spree-Api-Key, Authorization, X-Spree-Country, X-Spree-Currency, X-Spree-Locale, X-Spree-Channel
+```
+
+A CDN or shared cache therefore stores one copy per country, currency, locale and channel, so a visitor in one market never receives another market's prices. The `country`, `currency` and `locale` query parameters are part of the URL, so they are cached separately without needing `Vary`. Responses to signed-in customers are `Cache-Control: private, no-store`.
+
 ## Translated Content
 
 When a locale is set, all translatable fields are returned in the requested language. This includes product names, descriptions, category names, and other content managed through [translations](../../developer/core-concepts/translations.md).

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

@@ -220,7 +220,7 @@ When resolving prices, Spree considers the full context of the request:
 
 The Store API automatically builds this context from the [request headers](../../api-reference/store-api/localization.md) (`X-Spree-Currency`, `X-Spree-Country`) and authentication state. You don't need to construct it manually — just make API requests and the correct price is resolved.
 
-> **INFO:** Price resolution runs per request — there is no in-process caching of resolved prices. The Store API instead relies on HTTP/CDN caching, with `Vary` headers keyed on the `X-Spree-Currency` and `X-Spree-Locale` request headers so each currency/locale combination is cached separately at the edge.
+> **INFO:** Price resolution runs per request — there is no in-process caching of resolved prices. The Store API instead relies on HTTP/CDN caching, with `Vary` headers keyed on every request header that changes the price — `X-Spree-Country` (market), `X-Spree-Currency`, `X-Spree-Locale`, `X-Spree-Channel`, the publishable key and `Authorization` — so each combination is cached separately at the edge. See [HTTP caching](../deployment/caching.md#http-caching-of-store-api-responses).
 
 ## Time-Based Pricing
 

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/caching.md

@@ -23,6 +23,23 @@ config.cache_store = :redis_cache_store, { url: ENV["REDIS_URL"] }
 
 Works identically with Redis or Valkey (the Linux Foundation fork most hosting platforms now provision).
 
+## HTTP caching of Store API responses
+
+Read-only Store API endpoints (products, categories, collections, markets, locales, currencies, policies, sellers) are HTTP-cacheable for guests, so a CDN or reverse proxy in front of Spree can serve them from the edge:
+
+- **Guests** get `Cache-Control: public, max-age=300` (list endpoints add `stale-while-revalidate=30`) plus an `ETag`, and conditional requests return `304 Not Modified`.
+- **Signed-in customers** (a customer JWT in `Authorization`) get `Cache-Control: private, no-store` — nothing is cached.
+
+Guest responses carry this `Vary` header:
+
+```
+Vary: Accept, X-Spree-Api-Key, Authorization, X-Spree-Country, X-Spree-Currency, X-Spree-Locale, X-Spree-Channel
+```
+
+Each of these headers changes the response body: the publishable key selects the store, `X-Spree-Country` selects the market (currency, prices, tax display, availability), and `X-Spree-Channel` controls price visibility and which products are listed. `Authorization` keeps a cached guest response from being served to a signed-in customer.
+
+> **WARNING:** If your CDN ignores `Vary` or builds its own cache key (for example Cloudflare Cache Rules with a custom cache key), include every header listed above in that key, or it serves one market's or store's prices to another.
+
 ## Testing Locally
 
 To enable caching in the development environment:

package/dist/developer/deployment/cdn.md

@@ -6,6 +6,8 @@ description: >-
 
 To improve performance of your Spree application, we recommend using a CDN (Content Delivery Network) to cache images and static files.
 
+> **NOTE:** If you also cache Store API responses at the CDN, the cache key must include every header in the response's `Vary` header — see [HTTP caching of Store API responses](caching.md#http-caching-of-store-api-responses).
+
 We recommend using [Cloudflare](https://www.cloudflare.com/) as your CDN provider. It's free and simple to set up.
 
 After setting up your Cloudflare account and adding your domain name to Cloudflare, you will need to set your cache settings.

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/how-to/custom-delivery-rate-provider.md

@@ -93,13 +93,19 @@ module SpreeAcmeCarrier
     # One API call serves every delivery method sharing this provider within
     # a request — carriers return all services in one response, so quoting
     # five methods should not mean five round-trips.
+    #
+    # Key the cache on everything the request sends, not on the location and
+    # order: an order split into several packages from one stock location
+    # would otherwise get the first package's rates for every package.
+    # Digesting the payload itself keeps the key complete as the request grows.
     def quotes_for(package)
-      key = [:acme_quotes, store.id, package.stock_location.id, package.order.id]
-      Spree::Current.provider_cache[key] ||= integration.client.rates(
-        from: package.stock_location,
-        to: package.order.ship_address,
-        parcel: { weight: package.weight }
-      )
+      request = {
+        from: package.stock_location.slice(:address1, :city, :zipcode, :country_id),
+        to: package.owner.ship_address.slice(:address1, :city, :zipcode, :country_id),
+        parcel: { weight: package.weight.to_f }
+      }
+      key = [:acme_quotes, store.id, Digest::SHA256.hexdigest(request.to_json)]
+      Spree::Current.provider_cache[key] ||= integration.client.rates(**request)
     end
   end
 end

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.278",
+  "version": "0.1.280",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",