@spree/docs 0.1.194 → 0.1.195

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

@@ -20,10 +20,8 @@ flowchart LR
 erDiagram
     Catalog ||--o{ CatalogProduct : "assortment"
     Catalog ||--o{ CatalogAssignment : "audiences"
-    Catalog }o--o| PriceList : "optional pricing"
-    CatalogAssignment }o--|| Channel : "one of"
+    Catalog ||--o| PriceList : "owns (optional)"
     CatalogAssignment }o--|| CustomerGroup : "one of"
-    CatalogAssignment }o--|| Market : "one of"
     CatalogAssignment }o--|| Company : "one of"
 
     Catalog {
@@ -60,6 +58,8 @@ const catalog = await adminClient.catalogs.create({
 
 The price list is optional. A catalog with an assortment and no price list restricts the range at normal prices; a catalog with a price list and no assortment adjusts prices without hiding anything.
 
+A price list is either **standalone** (matched by its own rules) or **owned by exactly one catalog** — attaching a list a catalog already claims moves it. Detaching (`price_list_id: null`) is an explicit act with a real consequence: a released list starts matching by its own rules again, and a rule-less one matches everyone.
+
 ### Filling the assortment
 
 ```typescript Admin SDK
@@ -71,7 +71,7 @@ const { data: products } = await adminClient.catalogs.products.list(catalog.id)
 await adminClient.catalogs.products.delete(catalog.id, 'prod_xxx')
 ```
 
-Products are positioned, so a catalog also controls the order they're presented in.
+Membership is all a catalog holds — it decides *what* a buyer sees, never the order they see it in. Presentation order stays with categories and collections.
 
 When a catalog should restrict to exactly what its price list covers, there's a shortcut that copies those products in rather than making someone add them by hand:
 
@@ -81,15 +81,15 @@ const { added_count } = await adminClient.catalogs.importProducts(catalog.id)
 
 ## Choosing the audience
 
-A catalog is assigned to one of four things:
+A catalog is assigned to a buyer audience:
 
 | Assign to | Meaning |
 |---|---|
-| **[Channel](channels.md)** | Everyone buying through this channel — an app, a retail till |
 | **[Customer group](customers.md)** | A segment — wholesale accounts, staff, a loyalty tier |
-| **[Market](markets.md)** | Everyone in a region |
 | **[Company](companies.md)** | One B2B organization |
 
+A [Channel](channels.md) is not assigned — it names its catalog directly via `default_catalog_id`, which applies to everyone buying through it when nothing narrower does.
+
 ```typescript Admin SDK
 await adminClient.catalogs.assign(catalog.id, {
   assignable_type: 'customer_group',
@@ -128,9 +128,9 @@ Prices are checked in order, and the first match wins:
 
 Nearest-first is what lets a subsidiary hold a better-negotiated rate than the group's, without disturbing anyone else.
 
-> **WARNING:** A price list attached to a catalog applies **because the catalog applies** — its own rules are not consulted, and it's excluded from ordinary rule matching.
+> **WARNING:** A price list owned by a catalog applies **because the catalog applies** — its own rules are not consulted, and it's excluded from ordinary rule matching.
 > 
-> That exclusion is load-bearing: a price list with no rules would otherwise match everyone, and one company's negotiated pricing would leak to the entire storefront.
+> That exclusion is load-bearing: a price list with no rules would otherwise match everyone, and one company's negotiated pricing would leak to the entire storefront. It also means a deactivated catalog's list goes **dormant** — turning the catalog off never releases its pricing to the whole store. Only explicitly detaching the list puts it back into rule matching.
 
 ## Related
 

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

@@ -142,7 +142,7 @@ const priceList = await client.priceLists.create({
   name: 'EU wholesale',
   match_policy: 'all',
   rules: [
-    { type: 'customer_group_rule', preferences: { customer_group_ids: ['cg_xxx'] } },
+    { type: 'market_rule', preferences: { market_ids: ['mkt_xxx'] } },
   ],
   prices: [
     { variant_id: 'variant_xxx', currency: 'EUR', amount: '19.99' },
@@ -165,16 +165,18 @@ spree api patch /price_lists/pl_xxx/activate
 
 ## Price Rules
 
-Price Rules define conditions that must be met for a Price List to apply. Spree includes five built-in rule types:
+Price Rules define conditions that must be met for a Price List to apply. Rules describe the *context* of a purchase — where, through what, how much:
 
 | Rule | Description | Use Case |
 |------|-------------|----------|
 | **Market Rule** | Matches based on the current [Market](markets.md) | Regional pricing across markets |
 | **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 |
 
+*Who* gets a price list is not a rule — it's a [Catalog](catalogs.md): attach the list to a catalog assigned to the customer groups or companies it's for.
+
+> **NOTE:** The **User Rule** and **Customer Group Rule** kinds still work and are not going away, but they're no longer offered when adding a rule — targeting an audience through a catalog is the one way to do it now. Nothing needs migrating; rules you already have keep matching exactly as before.
+
 ### Market Rule
 
 Regional pricing. Applies the Price List when the customer is in one of the specified markets.
@@ -183,15 +185,7 @@ Regional pricing. Applies the Price List when the customer is in one of the spec
 
 ### Channel Rule
 
-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
-
-Limits the Price List to specific customer accounts. Useful for VIP customers, employee pricing, or wholesale accounts.
-
-### Customer Group Rule
-
-Applies to members of specific customer groups. Useful for wholesale tiers, loyalty programs, or membership-based pricing.
+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. For new setups, prefer giving the channel a default [Catalog](catalogs.md) that owns the price list — that is where channel-wide commercial terms live going forward.
 
 ### Volume Rule
 
@@ -214,7 +208,7 @@ 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 |
 | Channel | The API credential in use | The [Channel](channels.md) for channel-based rules |
-| Customer | Authentication | The signed-in customer for user-based rules |
+| Customer | Authentication | The signed-in customer, for resolving their [Catalogs](catalogs.md) |
 | Quantity | Cart line item | The quantity for volume-based rules |
 | Date | Current time | For time-based Price List scheduling |
 

package/package.json

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