@spree/docs 0.1.181 → 0.1.183

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,8 +3,6 @@ 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.
@@ -16,15 +14,16 @@ Products are organized into **categories** — a flexible hierarchy for grouping
 ```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 +35,7 @@ erDiagram
 
     Variant {
         string sku
-        boolean is_master
+        string barcode
         decimal weight
     }
 
@@ -64,7 +63,7 @@ erDiagram
 | `name` | Product name | Yes |
 | `description` | Full product description | Yes |
 | `slug` | URL-friendly identifier (e.g., `spree-tote`) | Yes |
-| `status` | `draft`, `active`, or `archived` | No |
+| `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 |
@@ -221,6 +220,144 @@ 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
+
+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.
+
+> **INFO:** This applies to products that belong to a seller. A marketplace's own catalog is unaffected: an operator publishing their own product sets `status` directly and answers to nobody.
+
+### The lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> draft
+    draft --> proposed : seller submits
+    proposed --> active : operator approves
+    proposed --> rejected : operator sends back
+    rejected --> proposed : seller revises and resubmits
+    proposed --> draft : seller withdraws
+    proposed --> archived : seller withdraws
+    active --> draft : seller takes it down
+    active --> archived : seller withdraws it
+```
+
+Withdrawing a submission before anyone has ruled on it closes the open row as `withdrawn`, so a `pending` row always means the marketplace still owes an answer. A product that was already rejected keeps that decision at the head of its trail instead.
+
+| Status | Meaning | Storefront |
+|---|---|:---:|
+| `draft` | The seller is still working on it | Hidden |
+| `proposed` | Submitted, waiting on the marketplace | Hidden |
+| `rejected` | Sent back with a reason, awaiting changes | Hidden |
+| `active` | Approved and on sale | **Visible** |
+| `archived` | Withdrawn | Hidden |
+
+A seller can always take their own listing down — that is not a review decision. Putting one up is.
+
+### The submission record
+
+Each submission and each decision on it is a `Spree::ProductSubmission` row. The product's `status` stays the operational truth; these rows are how it got there.
+
+```mermaid
+erDiagram
+    Product ||--o{ ProductSubmission : "has many"
+    AdminUser ||--o{ ProductSubmission : "submitted"
+    AdminUser ||--o{ ProductSubmission : "reviewed"
+
+    ProductSubmission {
+        string status
+        bigint product_id
+        bigint submitted_by_id
+        bigint reviewed_by_id
+        datetime reviewed_at
+        text review_note
+        json metadata
+    }
+```
+
+| Column | Description |
+|---|---|
+| `status` | `pending`, `approved`, `rejected`, or `withdrawn` |
+| `submitted_by_id` | The seller's staff member who asked |
+| `reviewed_by_id` | The marketplace's staff member who decided |
+| `reviewed_at` | When the decision was made |
+| `review_note` | Why it was sent back — this is what the seller reads |
+
+Rows accumulate rather than overwrite, so a seller sent back three times leaves three rows. The latest row for a product is the live one; the ones before it are the trail.
+
+> **WARNING:** Never store a rejection reason on the product itself. A seller can write their own product's `metadata`, so a note kept there is erased the next time they save.
+
+An approval with no `reviewed_by_id` and `metadata.auto_approved` set means the store approves listings automatically — never a decision whose author was lost. Turn that on with the `auto_approve_seller_products` store preference.
+
+### Submitting, as a seller
+
+Status is not writable on the seller branch. A seller moves a product with an explicit action:
+
+
+```typescript Seller SDK
+import { createSellerClient } from '@spree/seller-sdk'
+
+const client = createSellerClient({
+  baseUrl: 'https://marketplace.example.com',
+  sellerId: 'sel_xxx',
+})
+
+await client.products.submit('prod_xxx')   // draft or rejected → proposed
+await client.products.draft('prod_xxx')    // take it back down
+await client.products.archive('prod_xxx')  // withdraw it
+
+// Why it was sent back
+const product = await client.products.get('prod_xxx', 'submission')
+product.submission?.review_note
+```
+
+```bash CLI
+spree api patch /seller/products/prod_xxx/submit
+spree api patch /seller/products/prod_xxx/draft
+spree api patch /seller/products/prod_xxx/archive
+```
+
+
+### Deciding, as the marketplace
+
+
+```typescript Admin SDK
+await client.products.approve('prod_xxx')
+await client.products.reject('prod_xxx', { reason: 'Please add a photo showing scale.' })
+
+// The review queue
+const pending = await client.products.list({ filter: { status_eq: 'proposed' } })
+
+// Who decided, and when
+const product = await client.products.get('prod_xxx', { expand: ['submission'] })
+product.submission?.reviewed_by_name
+```
+
+```bash CLI
+spree api patch /products/prod_xxx/approve
+spree api patch /products/prod_xxx/reject -d '{"reason": "Please add a photo showing scale."}'
+```
+
+
+> **NOTE:** The seller sees the note and when the decision was made, but never who made it.
+
+### Leaving review is a decision
+
+A product in `proposed` or `rejected` cannot have its status changed by an ordinary update — that would put it on sale with nobody's name against it. The refusal lives in the product update workflow, so every caller inherits it, and bulk status updates skip those products and report how many they left behind.
+
+### Events
+
+Each transition publishes an event you can subscribe to:
+
+| Event | Published when |
+|---|---|
+| `product.proposed` | A seller submits for review |
+| `product.approved` | The marketplace accepts it |
+| `product.rejected` | The marketplace sends it back |
+| `product.drafted` | A seller takes a listing down |
+| `product.archived` | A seller withdraws it |
+
+The submission row itself also publishes `product_submission.created` and `product_submission.updated`, carrying the status, the note and the product. See [Events](events.md).
+
 ## Product Filters
 
 Get available filter options for building a faceted search UI. Returns price ranges, option values, and categories with counts:
@@ -468,14 +605,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
@@ -512,7 +654,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.
 

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

@@ -5,7 +5,9 @@ description: Build percentage and fixed-amount discounts, free shipping, BOGO of
 
 ## Overview
 
-Promotions give money off an order — a percentage off, free shipping, or free items added to the cart. A promotion is a campaign definition: **rules** decide when it applies, **actions** decide what it does. When a promotion applies, its actions write [Discount](taxes-discounts-fees.md#discounts) rows on the order.
+A promotion is a campaign: a percentage off, free shipping, or free items in the cart. **Rules** decide when it applies, **actions** decide what it does.
+
+A promotion is a *rule that exists on its own*, set up in advance and lasting across many orders. What lands on any one order is a [Discount](discounts.md) — the record of money actually coming off. The promotion is the campaign; the discount is what a particular customer got.
 
 ```mermaid
 erDiagram
@@ -52,14 +54,13 @@ Promotions can be activated in two ways:
 - **Automatic promotions** — applied on their own when the rules are met (e.g. free shipping on orders over $50)
 - **Coupon code promotions** — applied when a customer enters a valid code during checkout
 
-### How discounts are recorded
+### When promotions compete
 
-Each applied promotion becomes one or more Discount rows on the order — on a specific line item or on a fulfillment, never a loose adjustment. Each row keeps a copy of the coupon code and the configured value ("10% off"), so the order still tells the whole story even if the promotion is deleted later.
+Several promotions can qualify for the same item at once. Spree applies **only the one that saves the customer the most**, and records just that one.
 
-Two things follow from this design:
+Losing candidates aren't stored or tracked — they're simply reconsidered on every cart change. So a promotion that loses today can win tomorrow, when the basket changes, without any bookkeeping to keep straight.
 
-- **Only winners are stored.** When several promotions compete for the same item, Spree picks the one that saves the customer the most and writes only that one. Losing candidates are recomputed on every cart change, so a promotion that loses today can win tomorrow without any bookkeeping.
-- **A discount on the whole order is shared out across the items.** If a customer later returns one item, Spree knows exactly how much of the discount belonged to it.
+What an applied promotion leaves behind on the order is a [Discount](discounts.md) — a permanent record that survives the promotion being edited or deleted.
 
 ## Promotion Attributes
 
@@ -112,7 +113,7 @@ You can also [build your own rules](../how-to/custom-promotion.md) for business-
 
 Actions define what happens when a promotion applies.
 
-### CreateAdjustment
+### Order discount (`CreateAdjustment`)
 
 A discount on the whole order. The amount is distributed proportionally across the line items — there is no single order-level row, so per-item reporting and partial returns always know their share.
 
@@ -120,7 +121,7 @@ A discount on the whole order. The amount is distributed proportionally across t
 
 **Use case:** "10% off your order", "$20 off orders over $100".
 
-### CreateItemAdjustments
+### Item discount (`CreateItemAdjustments`)
 
 A discount on individual line items. Only items that match the promotion's rules receive it — if a Category rule says "Electronics", only electronics are discounted.
 
@@ -128,13 +129,13 @@ A discount on individual line items. Only items that match the promotion's rules
 
 **Use case:** "15% off shoes", "Buy 2+ shirts get 10% off each".
 
-### FreeShipping
+### Free shipping (`FreeShipping`)
 
 Writes a discount on each fulfillment covering its delivery cost. The row is kept even when the cost is zero — its presence is what marks the order as having free shipping.
 
 **Use case:** "Free shipping on orders over $75", "Free shipping with code FREESHIP".
 
-### CreateLineItems
+### Free items (`CreateLineItems`)
 
 Adds specified products to the cart when the promotion is eligible, checking stock first. Items are not removed automatically if eligibility is lost — customers remove them manually.
 
@@ -245,7 +246,7 @@ Automatic promotions need no customer action at all — they are evaluated on ev
 
 ## Related Documentation
 
-- [Taxes, Discounts & Fees](taxes-discounts-fees.md) — the Discount rows promotions write, and manual discounts
+- [Discounts](discounts.md) — the rows promotions write, and manual discounts
 - [Build Custom Promotion Rules & Actions](../how-to/custom-promotion.md) — step-by-step guide to custom rules, actions and adjusters
 - [Calculators](calculators.md) — promotion calculators
 - [Carts](carts.md) — the cart lifecycle promotions act on

package/dist/developer/core-concepts/search-filtering.md

@@ -3,13 +3,11 @@ title: Search & Filtering
 description: "Use Ransack-style query parameters to search, filter, sort, and paginate products, taxons, and other resources through the Spree Store API."
 ---
 
-import { Since } from '/snippets/since.mdx';
-
 ## Overview
 
 Spree provides powerful search, filtering, and sorting capabilities for products and other resources. The Store API supports:
 
-- Full-text search across product names, SKUs, and searchable product metafields
+- Full-text search across product names, SKUs, and searchable custom fields
 - Attribute-based filtering (price range, availability, stock status)
 - Category and taxon filtering
 - Faceted search with filter counts
@@ -276,7 +274,7 @@ curl 'https://api.mystore.com/api/v3/store/products?page=1&limit=24' \
 
 See [Querying](../../api-reference/store-api/querying.md) for the full list of filtering, sorting, and pagination options.
 
-## Search Providers 
+## Search Providers
 
 Spree uses a pluggable search provider architecture. The default provider uses SQL (ILIKE + Ransack). For production catalogs with 1,000+ products, we recommend switching to [Meilisearch](../../integrations/search/meilisearch.md) for typo tolerance, relevance ranking, and faster faceted search.
 

package/dist/developer/core-concepts/store-credits-gift-cards.md

@@ -3,9 +3,6 @@ title: Store Credits & Gift Cards
 description: How Spree models store credits and gift cards — stored value balances, redeemable codes, and checkout usage for refunds, loyalty, and gifting.
 ---
 
-import { Since } from '/snippets/since.mdx';
-
-
 ## Overview
 
 Spree provides two stored value mechanisms that customers can use at checkout: