@spree/docs 0.1.182 → 0.1.184

package/dist/developer/core-concepts/order-totals.md

@@ -0,0 +1,110 @@
+---
+title: Order Totals
+description: How an order total is built up from items, tax, discounts, delivery and fees — and how to render a summary that adds up.
+---
+
+## Overview
+
+An order total is rarely just the sum of the item prices. Tax is added or already inside them, a promo code takes something off, delivery costs something, gift wrapping costs a bit more.
+
+Spree records each of those as its own kind of row, and keeps a running total for each kind on the order itself. That means the summary block in your checkout is a handful of fields — you don't add anything up yourself.
+
+```mermaid
+flowchart TB
+    Items["Item total"] --> Total["Order total"]
+    Discounts["Discounts"] --> Total
+    Delivery["Delivery"] --> Total
+    Fees["Fees"] --> Total
+    Tax["Tax"] --> Total
+
+    style Total fill:#e8f5e9,stroke:#2e7d32
+```
+
+## The totals
+
+```typescript Store SDK
+const order = await client.orders.get('or_xxx')
+
+order.display_item_total     // "$120.00"  items, before tax and discounts
+order.display_discount_total // "-$12.00"  everything taken off
+order.display_delivery_total // "$5.00"    delivery
+order.display_fee_total      // "$2.50"    surcharges
+order.display_tax_total      // "$22.60"   all tax
+order.display_total          // "$138.10"  what the customer pays
+```
+
+| Attribute | What it sums |
+|---|---|
+| `item_total` | Line item prices, before tax and discounts |
+| `discount_total` | Every [discount](discounts.md) |
+| `delivery_total` | Delivery charges |
+| `fee_total` | Every [fee](fees.md) |
+| `tax_total` | All [tax](taxes.md) |
+| `included_tax_total` | Tax already inside the displayed prices |
+| `additional_tax_total` | Tax added on top |
+| `total` | What the customer pays |
+| `amount_due` | Still to pay, after gift cards and store credit |
+
+## Two forms of every amount
+
+Every total comes twice: `total` is the raw value, `display_total` is formatted for the order's currency.
+
+```json
+{
+  "total": "138.10",
+  "display_total": "$138.10"
+}
+```
+
+**Render the `display_` one.** It knows the currency symbol, which side it goes on, and which separator that locale uses — `$138.10`, `138,10 €`, `¥138`. Formatting it yourself means reimplementing that, and getting it wrong for somebody.
+
+> **NOTE:** Money is a **string**, never a number. JavaScript can't represent every decimal exactly: `0.1 + 0.2` gives `0.30000000000000004`, which is not something you want inside a price.
+> 
+> If you must do arithmetic, use a decimal library or work in whole cents. Most of the time you don't need to — Spree already did it.
+
+## The double-counting trap
+
+> **WARNING:** If you build a subtotal yourself, include `additional_tax_total` only — never `included_tax_total`.
+> 
+> Included tax is **already inside** the item prices. Adding it again charges the customer's eyes twice, and produces a summary that doesn't match the amount taken from their card. This is the single most common bug in a European storefront.
+
+The two exist because the same order can carry both: VAT already inside the goods, and a separately-added tax on something else. `tax_total` covers both, which is why it's the safe field to display on its own line.
+
+## Totals update themselves
+
+Every change to a cart returns the whole cart, totals included:
+
+```typescript Store SDK
+const cart = await client.carts.items.create(cartId, {
+  variant_id: 'var_xxx',
+  quantity: 2,
+})
+
+cart.display_total // already correct
+```
+
+There is never a second "recalculate" request to make, and never a moment where the summary on screen disagrees with what the server thinks. Adding an item, entering an address, applying a code — each response carries the new numbers.
+
+The totals are worked out again at the moment the cart is completed, so a price that changed while the customer sat on the review page can't lead to the wrong charge.
+
+## Once an order is placed
+
+The rows stop being regenerated. Editing a placed order re-adds the rows it already has rather than starting over, so today's promotions and rates can't rewrite what a customer agreed to last week.
+
+## Where each row attaches
+
+The individual rows are there if you need them — an itemised invoice, a tax report:
+
+- **[Tax lines](taxes.md)** → a line item, a fulfillment, or a fee
+- **[Discounts](discounts.md)** → a line item or a fulfillment
+- **[Fees](fees.md)** → a line item, a fulfillment, or the order itself
+
+Each row also keeps a copy of where it came from — the rate and label on a tax line, the code and promotion on a discount. If someone deletes that promotion next month, the order still says what the customer was actually given.
+
+## Related
+
+- [Taxes](taxes.md) — how tax is worked out
+- [Discounts](discounts.md) — money off
+- [Fees](fees.md) — surcharges and duties
+- [Carts](carts.md) — checkout and completion
+- [Orders](orders.md) — the placed order

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

@@ -148,7 +148,7 @@ Where admin edits are allowed, totals are re-added from the order's existing row
 
 ## Money on an order
 
-Tax, discounts and fees are kept as separate records, so you can ask what tax was charged without picking through a mixed list. See [Taxes, Discounts & Fees](taxes-discounts-fees.md).
+Tax, discounts and fees are kept as separate records, so you can ask what tax was charged without picking through a mixed list. See [Order totals](order-totals.md).
 
 ## Events
 

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

@@ -1,5 +1,6 @@
 ---
 title: Payments
+description: Taking money — payment methods, payment sessions, saved cards, refunds, and how a payment finishes reliably even when a customer closes the tab.
 ---
 
 ## Overview
@@ -98,7 +99,7 @@ erDiagram
     CreditCard }o--|| Customer : "belongs to"
     StoreCredit }o--|| Customer : "belongs to"
     Refund }o--|| Payment : "belongs to"
-    Refund }o--|| Reimbursement : "belongs to"
+    Refund }o--o| Return : "may come from"
 ```
 
 **Key relationships:**
@@ -681,22 +682,18 @@ See [Events](events.md) for more details on subscribing to events.
 
 - [Payments (Store SDK)](../sdk/store/payments.md) - SDK how-to for payment sessions, payments, and setup sessions
 - [Build a Custom Payment Method](../how-to/custom-payment-method.md) - Step-by-step guide to creating your own payment gateway integration
-- [Orders](orders.md) - Order management and state machine
+- [Orders](orders.md) - Order lifecycle, payment and fulfillment status
 - [Checkout Customization](carts.md) - Customizing the checkout flow
 - [Events](events.md) - Subscribe to payment events
 
-## Key Services
+## Two paths to a completed order
 
-| Service | Description |
-|---------|-------------|
-| `Spree::Carts::Complete` | Completes the order — validates, processes payments (if not already done), advances state machine. Used by both the `POST /carts/:id/complete` endpoint and the webhook handler. |
-| `Spree::Payments::HandleWebhook` | Processes a normalized webhook event — creates Payment, marks session completed, calls `Carts::Complete`. |
-| `Spree::Payments::HandleWebhookJob` | Background job that wraps `HandleWebhook` — enqueued by the webhook controller for async processing. |
+A payment can finish in two places, and both have to end at the same result.
 
-Both `Carts::Complete` and `HandleWebhook` are registered in `Spree::Dependencies` and can be replaced with custom implementations:
+The customer's browser confirms the payment and your storefront completes the cart. Or the provider's own webhook arrives first — sometimes seconds later, sometimes because the customer closed the tab mid-redirect.
 
-```ruby
-# config/initializers/spree.rb
-Spree::Dependencies.carts_complete_service = 'MyApp::CustomCartComplete'
-Spree::Dependencies.payments_handle_webhook_service = 'MyApp::CustomWebhookHandler'
-```
+Whichever arrives first completes the order; the other finds the work already done and does nothing. That is what makes a closed tab or a flaky connection recoverable rather than a lost sale with a real charge attached.
+
+> **WARNING:** Never treat the browser returning from a redirect as proof of payment. The provider's webhook is the authoritative signal — a customer can close the tab, and a browser response can be forged.
+
+Both paths can be replaced if your integration needs different behaviour — see [Dependencies](../customization/dependencies.md).

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

@@ -3,8 +3,6 @@ title: Pricing
 description: Prices, Price Lists, Price Rules, and the Pricing Context — Spree's flexible pricing engine for regional, wholesale, volume, and market-based pricing.
 ---
 
-import { Since } from '/snippets/since.mdx';
-
 ## Overview
 
 Spree's pricing system supports both simple single-currency pricing and advanced multi-currency, rule-based pricing through Price Lists. Every [Variant](products.md#variants) can have multiple prices — a base price per currency, plus additional prices from Price Lists that apply conditionally based on rules like geography, customer segment, or quantity.
@@ -94,7 +92,7 @@ spree api post /prices/bulk_upsert -d '{
 ```
 
 
-## Price Lists  
+## Price Lists
 
 Price Lists allow you to create different pricing strategies based on various conditions. This enables advanced pricing scenarios like:
 
@@ -165,27 +163,27 @@ spree api patch /price_lists/pl_xxx/activate
 ```
 
 
-## Price Rules 
+## Price Rules
 
 Price Rules define conditions that must be met for a Price List to apply. Spree includes five built-in rule types:
 
 | Rule | Description | Use Case |
 |------|-------------|----------|
 | **Market Rule** | Matches based on the current [Market](markets.md) | Regional pricing across markets |
-| **Zone Rule** | Matches based on the customer's geographic zone | Country or state-level pricing |
+| **Channel Rule** | Matches based on the [Channel](channels.md) the customer is buying through | App-only or in-store pricing |
 | **User Rule** | Matches specific customer accounts | VIP customers, wholesale accounts |
 | **Customer Group Rule** | Matches members of customer groups | Loyalty tiers, membership pricing |
 | **Volume Rule** | Matches based on quantity purchased | Bulk discounts, tiered pricing |
 
-### Market Rule 
+### Market Rule
 
-The recommended approach for regional pricing when using Markets. Applies the Price List when the customer is in one of the specified markets.
+Regional pricing. Applies the Price List when the customer is in one of the specified markets.
 
 **Example:** Price a product at $29.99 in North America and €24.99 in Europe, rather than relying on exchange rate conversion.
 
-### Zone Rule
+### Channel Rule
 
-Applies based on the customer's geographic zone. Useful for regional or country-specific pricing when not using Markets.
+Applies when the customer is buying through a particular sales channel — a discount that exists only in the mobile app, or a price that only applies at a retail till.
 
 ### User Rule
 
@@ -207,7 +205,7 @@ Applies based on quantity purchased. Supports `min_quantity` and `max_quantity`
 
 > **INFO:** Custom Price Rules can be created for specialized pricing logic. See the [Customization Quickstart](../customization/quickstart.md) for details.
 
-## Pricing Context 
+## Pricing Context
 
 When resolving prices, Spree considers the full context of the request:
 
@@ -215,8 +213,8 @@ When resolving prices, Spree considers the full context of the request:
 |---------|--------|-------------|
 | Currency | Market or request header | The currency to price in |
 | Market | Customer's country | The [Market](markets.md) for market-based rules |
-| Zone | Customer's address | The geographic zone for zone-based rules |
-| Customer | JWT authentication | The logged-in customer for user-based rules |
+| Channel | The API credential in use | The [Channel](channels.md) for channel-based rules |
+| Customer | Authentication | The signed-in customer for user-based rules |
 | Quantity | Cart line item | The quantity for volume-based rules |
 | Date | Current time | For time-based Price List scheduling |
 
@@ -236,7 +234,7 @@ Price Lists are managed in the Admin Panel under **Products → Price Lists**, o
 
 Each Price List contains prices for specific variants and currencies. Products can be added to a Price List, and individual variant prices set within it.
 
-## Price History (EU Omnibus Directive) 
+## Price History (EU Omnibus Directive)
 
 Spree automatically records price changes for EU Omnibus Directive compliance. When a product goes on sale, EU regulations require displaying the lowest price in the preceding 30 days alongside the discounted price.
 

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

@@ -3,28 +3,29 @@ title: Products
 description: How Spree models products, variants, option types, images, prices, and categories — the building blocks of every catalog and storefront.
 ---
 
-import { Since } from '/snippets/since.mdx';
-
 ## Overview
 
-A product represents something you sell. Each product has one or more **variants** — the actual purchasable items with their own SKU, price, and inventory. For example, a "T-Shirt" product might have variants for each size and color combination.
+A product is the listing a customer browses. A **variant** is the thing they actually buy.
+
+That split runs through everything on this page. The product holds what's shared — name, description, images, which categories it's filed under. Each variant holds what differs — its SKU, its price, its stock. A T-shirt is one product; small navy is a variant.
 
-Products are organized into **categories** — a flexible hierarchy for grouping products. Categories can be filtered, sorted, and searched via the Store API.
+**Every product has at least one variant**, even when there's nothing to choose. A book with no size or colour still has a single variant carrying its SKU, price and stock; you just never render a picker.
 
-> **INFO:** Product names, descriptions, slugs, and SEO fields are [translatable](translations.md#resource-translations).
+> **INFO:** Product names, descriptions, slugs and SEO fields are [translatable](translations.md#resource-translations).
 
 ```mermaid
 erDiagram
     Product ||--o{ Variant : "has many"
-    Product }o--o{ OptionType : "has many"
-    Product ||--o{ Classification : "has many"
-    Variant ||--o{ Price : "has many"
-    Variant ||--o{ StockItem : "has many"
-    Variant ||--o{ Image : "has many"
-    Variant }o--o{ OptionValue : "has many"
+    Product }o--o{ OptionType : "varies by"
+    Product }o--o{ Category : "filed under"
+    Product }o--o{ Collection : "grouped into"
+    Product ||--o{ Media : "images and video"
+    Product }o--|| DeliveryProfile : "ships by"
+    Variant ||--o{ Price : "one per currency"
+    Variant ||--o{ StockLevel : "stocked per location"
+    Variant }o--o{ OptionValue : "identified by"
     OptionType ||--o{ OptionValue : "has many"
-    Taxon ||--o{ Classification : "has many"
-    Taxonomy ||--o{ Taxon : "has many"
+    Category ||--o{ Category : "nests under"
 
     Product {
         string name
@@ -36,7 +37,7 @@ erDiagram
 
     Variant {
         string sku
-        boolean is_master
+        string barcode
         decimal weight
     }
 
@@ -60,21 +61,26 @@ erDiagram
 ## Product Attributes
 
 | Attribute | Description | Translatable |
-|-----------|-------------|:---:|
+|---|---|:---:|
 | `name` | Product name | Yes |
-| `description` | Full product description | Yes |
-| `slug` | URL-friendly identifier (e.g., `spree-tote`) | Yes |
-| `status` | `draft`, `active`, or `archived`. A marketplace adds `proposed` and `rejected` — see Seller submissions below | No |
-| `available_on` | Date the product becomes available for sale | No |
-| `discontinue_on` | Date the product is no longer available | No |
-| `meta_title` | Custom SEO title | Yes |
-| `meta_description` | SEO description | Yes |
-| `meta_keywords` | SEO keywords | Yes |
-| `purchasable` | Whether the product can be added to cart | No |
-| `in_stock` | Whether any variant has stock available | No |
-| `price` | Default variant's price in the current currency | No |
-| `thumbnail_url` | URL to the product's first image — always returned, no expand needed | No |
-| `tags` | Array of tag strings for filtering | No |
+| `description` / `description_html` | Description as plain text and as formatted HTML | Yes |
+| `slug` | URL identifier, e.g. `spree-tote` | Yes |
+| `status` | `draft`, `active` or `archived`. A marketplace adds `proposed` and `rejected` — see [Seller submissions](#seller-submissions) | No |
+| `available_on` | When it goes on sale | No |
+| `discontinue_on` | When it comes off | No |
+| `meta_title` / `meta_description` / `meta_keywords` | SEO fields | Yes |
+| `purchasable` | Whether it can be added to a cart | No |
+| `in_stock` | Whether any variant has stock | No |
+| `backorderable` | Whether it can be ordered while out of stock | No |
+| `preorder` / `preorder_ships_at` | Whether it's sold ahead of availability, and when it ships | No |
+| `available` | Whether it's on sale right now, by date and status | No |
+| `price` / `original_price` | The [default variant's](#the-default-variant) price, and its compare-at price | No |
+| `default_variant_id` | Which variant represents the product | No |
+| `variant_count` | How many variants it has | No |
+| `thumbnail_url` | First image — always returned, no expand needed | No |
+| `tags` | Tags, for filtering | No |
+
+The Admin API adds the operational fields on top: `product_type_id`, `delivery_profile_id`, `tax_category_id`, `seller_id`, `metadata`, `created_at` / `updated_at` / `deleted_at`.
 
 ## Listing Products
 
@@ -161,18 +167,20 @@ Pass `expand` to include related resources in a single response — see [expand
 
 The examples above use the **Store API** (publishable key, read-only, customer-facing). To **create and manage** products, use the [Admin API](../../api-reference/admin-api/introduction.md) — via the [Admin SDK](../sdk/admin/quickstart.md) or the [Spree CLI](../cli/admin-api.md).
 
-A product's purchasable attributes (SKU, prices, stock) live on its **variants**, which you can create inline:
+A product's purchasable attributes (SKU, prices, stock) live on its **variants**, which you can create inline.
+
+For a product with options, send the variants:
 
 
 ```typescript Admin SDK
 import { createAdminClient } from '@spree/admin-sdk'
 
-const client = createAdminClient({
+const adminClient = createAdminClient({
   baseUrl: 'https://store.example.com',
   secretKey: 'sk_xxx',
 })
 
-const product = await client.products.create({
+const product = await adminClient.products.create({
   name: 'Premium T-Shirt',
   description: 'Soft, organic cotton.',
   status: 'active',
@@ -184,7 +192,7 @@ const product = await client.products.create({
         { name: 'color', value: 'navy' },
       ],
       prices: [{ currency: 'USD', amount: '29.99' }],
-      stock_items: [{ stock_location_id: 'sloc_xxx', count_on_hand: 50 }],
+      stock_levels: [{ stock_location_id: 'sloc_xxx', count_on_hand: 50 }],
     },
   ],
 })
@@ -203,6 +211,18 @@ spree api post /products -d '{
 ```
 
 
+For something with no options at all, send prices directly and skip the variants array — Spree forwards them to the product's single variant:
+
+```typescript Admin SDK
+await adminClient.products.create({
+  name: 'The Spree Handbook',
+  status: 'active',
+  prices: [{ currency: 'USD', amount: '19.99' }],
+})
+```
+
+Don't pass both.
+
 Update, clone, or archive a product (deleting soft-deletes it):
 
 
@@ -221,7 +241,7 @@ spree api delete /products/prod_xxx
 
 > **TIP:** Operating on many products at once? The Admin API has bulk actions — `bulkStatusUpdate`, `bulkAddToCategories`, `bulkAddTags`, `bulkDestroy`, and more. See the [Admin API endpoint index](../../api-reference/admin-api/endpoints.md).
 
-## Seller submissions 
+## Seller submissions
 
 On a marketplace, a seller lists a product but does not publish one. They submit it, and the marketplace decides. This adds two statuses to the three above — both hidden from the storefront, since only `active` is visible.
 
@@ -398,29 +418,54 @@ curl 'https://api.mystore.com/api/v3/store/products/filters?category_id=ctg_xxx'
 
 ## Variants
 
-Variants are the purchasable units of a product. Each variant has its own SKU, price, inventory, and images, and is defined by a unique combination of option values.
+**A product is not the thing you buy — a variant is.** The product is the listing; the variant is the actual item with a SKU, a price and stock.
+
+That distinction is worth holding onto, because everything purchasable lives on the variant:
 
 | Attribute | Description |
-|-----------|-------------|
-| `sku` | Unique stock keeping unit |
-| `barcode` | Barcode (UPC, EAN, etc.) |
+|---|---|
+| `sku` | Stock keeping unit |
+| `barcode` | Barcode — UPC, EAN and so on |
 | `price` | Price in the current currency |
-| `original_price` | Compare-at price for showing discounts |
-| `weight`, `height`, `width`, `depth` | Dimensions for shipping calculations |
-| `in_stock` | Whether stock is available |
-| `backorderable` | Whether the variant can be ordered when out of stock |
-| `option_values` | The option values that define this variant (e.g., Size: Small, Color: Red) |
+| `original_price` | Compare-at price, for showing a reduction |
+| `weight`, `height`, `width`, `depth` | Used for delivery rates and labels |
+| `in_stock` / `purchasable` | Whether it can be bought right now |
+| `backorderable` | Whether it can be ordered while out of stock |
+| `preorder` / `preorder_ships_at` | Whether it's sold ahead of availability |
+| `option_values` | What distinguishes it — Size: Small, Colour: Red |
+| `options_text` | Those values as one readable string |
+| `track_inventory` | Whether stock is counted at all |
+
+Variants also carry the customs attributes — `hs_code`, `country_of_origin`, `customs_description` — used when a parcel crosses a border. See [Fees](fees.md#customs-classification).
+
+### Every product has at least one variant
+
+There's no such thing as a product without one. A book with no size or colour still has a single variant holding its SKU, price and stock — you simply never show a picker for it.
+
+> **NOTE:** Earlier versions of Spree had a special "master variant" alongside the real ones, which meant every query had to remember to exclude it. **That concept is gone.** A product's variants are all real, all purchasable, and all the same kind of thing.
 
-### Master Variant
+### The default variant
 
-Every product has a **master variant** that holds default pricing and inventory. If a product has no option types (e.g., a book with no size/color), the master variant is the only purchasable variant.
+`default_variant_id` names the variant that represents the product — the price shown on a listing page, and what "add to cart" means before anyone picks anything.
 
-### Regular Variants
+```typescript Store SDK
+const product = await client.products.get('spree-tote')
+
+product.default_variant_id // "var_xxx"
+product.price              // that variant's price
+product.variant_count      // 6
+```
+
+For a single-variant product that's the only variant. For a product with options it's the first one, unless you say otherwise. If the default is ever removed, another is promoted automatically — a product is never left without one.
 
-When a product has option types, each unique combination of option values creates a variant. For example, a T-shirt with sizes (S, M, L) and colors (Red, Green) has 6 variants:
+Products can also carry `buy_box_variant_id`, naming the variant a marketplace has chosen to feature when several sellers offer the same listing.
 
-| SKU | Size | Color |
-|-----|------|-------|
+### Options make variants
+
+A product with option types has one variant per combination. A T-shirt in three sizes and two colours is six variants:
+
+| SKU | Size | Colour |
+|---|---|---|
 | `TEE-S-R` | Small | Red |
 | `TEE-S-G` | Small | Green |
 | `TEE-M-R` | Medium | Red |
@@ -428,20 +473,18 @@ When a product has option types, each unique combination of option values create
 | `TEE-L-R` | Large | Red |
 | `TEE-L-G` | Large | Green |
 
-The product's `default_variant_id` points to the first non-master variant (or the master variant if none exist).
-
-Add a variant to an existing product via the Admin API (SKU, prices, and stock all live on the variant):
+Adding one to an existing product:
 
 
 ```typescript Admin SDK
-const variant = await client.products.variants.create('prod_xxx', {
+await adminClient.products.variants.create('prod_xxx', {
   sku: 'TEE-L-R',
   options: [
     { name: 'size', value: 'Large' },
     { name: 'color', value: 'Red' },
   ],
   prices: [{ currency: 'USD', amount: '24.99' }],
-  stock_items: [{ stock_location_id: 'sloc_xxx', count_on_hand: 30 }],
+  stock_levels: [{ stock_location_id: 'sloc_xxx', count_on_hand: 30 }],
 })
 ```
 
@@ -454,6 +497,8 @@ spree api post /products/prod_xxx/variants -d '{
 ```
 
 
+Options are named by value rather than by ID, so you don't have to look up an option value before creating a variant that uses it.
+
 ## Option Types and Option Values
 
 Option types define the axes of variation for a product (e.g., Size, Color, Material). Option values are the specific choices within each type (e.g., Small, Medium, Large).
@@ -518,9 +563,76 @@ spree api post /option_types -d '{
 ```
 
 
+## Product Types
+
+Merchants who sell more than one kind of thing end up repeating themselves. Every pair of shoes needs Size and Colour, belongs under Footwear, and wants a Material field. Every book needs an ISBN and an author.
+
+A **product type** captures that once. Creating a product from a type gives it the right option types, the right categories, the right delivery profile, and a form asking for the fields that kind of product actually needs.
+
+```mermaid
+erDiagram
+    ProductType ||--o{ Product : "creates"
+    ProductType }o--o{ OptionType : "seeds"
+    ProductType }o--o{ Category : "seeds"
+    ProductType }o--o{ CustomFieldDefinition : "asks for"
+    ProductType }o--o| DeliveryProfile : "ships by"
+
+    ProductType {
+        string name
+        integer products_count
+    }
+```
+
+```typescript Admin SDK
+const shoes = await adminClient.productTypes.create({
+  name: 'Footwear',
+  option_type_ids: ['optt_size', 'optt_color'],
+  category_ids: ['ctg_footwear'],
+  delivery_profile_id: 'dp_standard',
+  custom_field_definitions: [
+    { id: 'cfdef_material', required: true, sort_order: 0 },
+  ],
+})
+
+await adminClient.products.create({
+  name: 'Trail Runner',
+  product_type_id: shoes.id,
+  status: 'draft',
+})
+```
+
+### A type is a template, not a controller
+
+This is the part that determines how you should think about them.
+
+> **WARNING:** **Editing a product type never rewrites existing products.** Add an option type to Footwear next month and the shoes you created last month are untouched.
+
+That's deliberate. A merchant who adds a field to a type is describing what *new* products should look like — not asking Spree to silently restructure a live catalogue, invalidate URLs, or change what customers can pick.
+
+So the pieces behave in two distinct ways:
+
+| Part of the type | Behaviour |
+|---|---|
+| Option types, categories, delivery profile | **Stamped at creation.** Copied onto the product, then independent |
+| Custom field definitions | **Live by reference.** The form always reflects the type as it is now |
+
+Seeding is also **additive** — it adds what's missing and never removes what a product already has. Reassigning a product's type is therefore safe: it seeds the new type's option types and categories alongside whatever was already there.
+
+If you *do* want an edited type to reach the products already using it, that's an explicit action:
+
+```typescript Admin SDK
+const { products_count } = await adminClient.productTypes.applyToProducts('pt_xxx')
+```
+
+It runs in the background and is additive like the rest — never a side effect of saving a type.
+
+> **INFO:** `required` on a type's custom field is **advisory** — it marks the field in the dashboard but isn't enforced on write, since Spree saves the product and its fields in two steps. Validate in your own tooling if you need it enforced.
+
+A type in use can't be deleted; its products would lose the structure they were built from.
+
 ## Media
 
-Media can be attached to the product (via the master variant) or to individual variants. When displaying a product, show the images for the selected variant, falling back to the product-level images.
+Media can be attached to a product or to individual variants. When displaying a product, show the images for the selected variant, falling back to the product's own.
 
 ### Thumbnails
 
@@ -561,7 +673,7 @@ const product = await client.products.get('spree-tote', {
   expand: ['media', 'variants'],
 })
 
-// Product-level images (from master variant)
+// The product's own images
 product.media // [{ original_url: "https://cdn.../tote-front.jpg", position: 1 }, ...]
 
 // Each variant has its own thumbnail and media_count
@@ -606,14 +718,19 @@ See the [Pricing](pricing.md) guide for details on Price Lists, Price Rules, and
 
 ## Categories
 
-Categories provide a flexible way to organize products into hierarchical trees. Internally, Spree uses Taxonomies (category trees) and Taxons (nodes within those trees), but the Store API exposes them simply as **Categories**.
+There are two ways to group products, and they answer different questions.
+
+**Categories** are a hierarchy — the navigation tree a shopper browses. Clothing contains T-Shirts, which contains Long Sleeve. A product can sit in several categories, and each one has a permalink built from its path.
+
+**Collections** are flat groupings — "Summer 2025", "Best Sellers", "Under $50". A collection can be curated by hand, or defined by rules so products join and leave it on their own as their price, tags or stock change.
 
-For example:
-- **Categories** → Clothing → T-Shirts, Dresses
-- **Brands** → Nike, Adidas, Puma
-- **Collections** → Summer 2025, Best Sellers
+| | Categories | Collections |
+|---|---|---|
+| Shape | Nested tree | Flat list |
+| Membership | You assign it | Assigned, or matched by rules |
+| Typical use | Site navigation | Merchandising and campaigns |
 
-Products can belong to multiple categories.
+A brand is usually best modelled as one or the other rather than as a separate concept — a category if you want it in the navigation tree, a collection if it's a landing page.
 
 
 ```typescript Store SDK
@@ -650,7 +767,19 @@ curl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts/products?l
 
 > **INFO:** Category `name` and `description` fields are translatable.
 
-## Publications and Sales Channels 
+Collections work the same way from a storefront's point of view:
+
+```typescript Store SDK
+const { data: collections } = await client.collections.list()
+
+const { data: products } = await client.collections.products.list('summer-2025', {
+  limit: 12,
+})
+```
+
+A rule-based collection is defined once and maintains itself — set it to match everything tagged `sale` and under $50, and products appear and disappear as those facts change. Ordering can be manual or by a rule such as newest first.
+
+## Publications and Sales Channels
 
 A product is visible on a [Channel](channels.md) only when a `ProductPublication` record joins the two. Publications carry an optional time window so a product can be scheduled to go live and come down without code or manual toggles.