Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Delete a catalog's price list rather than releasing it, and fix the editor
Damian Legawiec64bb1558aa76
diff --git a/docs/developer/core-concepts/catalogs.mdx b/docs/developer/core-concepts/catalogs.mdxindex 2849d2afa7..4baf308c77 100644--- a/docs/developer/core-concepts/catalogs.mdx+++ b/docs/developer/core-concepts/catalogs.mdx@@ -62,7 +62,9 @@ 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.+A price list is either **standalone** (matched by its own rules) or **owned by exactly one catalog**. A catalog creates the list it prices through, so the two are configured together on the catalog page — an owned list never appears in the price-lists index, since it has no rules or audience of its own.++Removing a catalog's pricing (`price_list: null`), or deleting the catalog itself, **deletes the owned list** rather than releasing it. A released list would match by its own rules, and an owned list has none — so it would begin pricing every shopper in the store. It is a soft delete, so the prices stay recoverable.### Filling the assortment@@ -136,7 +138,7 @@ Nearest-first is what lets a subsidiary hold a better-negotiated rate than the g<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. 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.+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. Nothing puts an owned list back into rule matching: removing the pricing deletes the list instead, for the same reason.</Warning>## Relateddiff --git a/docs/plans/6.0-catalog-agreement-rework.md b/docs/plans/6.0-catalog-agreement-rework.mdindex 1260983159..664d3c921a 100644--- a/docs/plans/6.0-catalog-agreement-rework.md+++ b/docs/plans/6.0-catalog-agreement-rework.md@@ -31,11 +31,23 @@ catalog page this rework establishes.leak: the shipped derived exclusion set (`Catalog.bound_price_list_ids`)reads **active** catalogs only, so deactivating a catalog dropped its —typically rule-less — list back into generic matching, pricing the whole- store. With the FK, a deactivated catalog's list goes dormant; detaching- a list is an explicit act behind a dashboard warning ("this list will- start matching by its own rules"). Sharing one list across catalogs is- lost — one catalog serving many audiences through assignments is the- replacement.+ store. With the FK, a deactivated catalog's list goes dormant. Sharing one+ list across catalogs is lost — one catalog serving many audiences through+ assignments is the replacement.+- **An owned list is never released — removing a catalog's pricing deletes+ it** (revised 2026-08-30 in review, superseding the detach-with-a-warning+ design above). Releasing was to be an explicit act behind a dashboard+ warning, but the released state is the dangerous one: an owned list+ carries no rules, so back in generic matching it prices *every* shopper —+ the same leak this plan exists to close, reached deliberately instead of+ by accident. No warning makes that a reasonable thing to offer, so+ `price_list: null` and destroying the catalog both destroy the list+ (`has_one ... dependent: :destroy`; the model is paranoid, so the prices+ stay recoverable). Consequences: an owned list never appears in the+ price-lists index (it has no rules or audience of its own and is edited on+ its catalog), and switching from fixed prices to a percentage clears the+ hand-entered amounts, since an explicit row would otherwise keep winning+ over the adjustment the card claims is in effect.- **Audience price rules are grandfathered, not deprecated** (revised2026-08-30 after review — supersedes the same-day "deprecated + datatask" decision). `PriceRules::CustomerGroupRule` anddiff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.tsindex 466fac3824..92e508a8dd 100644--- a/packages/admin-sdk/src/params.ts+++ b/packages/admin-sdk/src/params.ts@@ -2562,6 +2562,8 @@ export interface CompanyMembershipCreateParams {export interface CatalogParams {name?: string+ /** Internal note on what the agreement is — never shown to shoppers. */+ description?: string | nullactive?: booleanposition?: number/**diff --git a/packages/admin-sdk/src/types/generated/Catalog.ts b/packages/admin-sdk/src/types/generated/Catalog.tsindex 7561a4427f..c17299205b 100644--- a/packages/admin-sdk/src/types/generated/Catalog.ts+++ b/packages/admin-sdk/src/types/generated/Catalog.ts@@ -1,4 +1,4 @@-// Typelizer digest 0d9c3211b399c7bf1c501f3296c63ee2+// Typelizer digest 6d7bb9370fb528e2f636b56464c167f6//// DO NOT MODIFY: This file was automatically generated by Typelizer.import type {PriceList, CatalogAssignment} from '@/types'@@ -6,6 +6,7 @@ import type {PriceList, CatalogAssignment} from '@/types'interface Catalog {id: string;name: string;+ description: string | null;active: boolean;position: number | null;metadata: Record<string, unknown> | null;diff --git a/packages/dashboard/src/components/spree/catalog-pricing-fields.tsx b/packages/dashboard/src/components/spree/catalog-pricing-fields.tsxindex f365bd9d1a..6404ea8099 100644--- a/packages/dashboard/src/components/spree/catalog-pricing-fields.tsx+++ b/packages/dashboard/src/components/spree/catalog-pricing-fields.tsx@@ -1,3 +1,4 @@+import type { PriceList } from '@spree/admin-sdk'import {Button,Field,@@ -12,10 +13,17 @@ import {SelectValue,Switch,} from '@spree/dashboard-ui'+import { TableIcon } from 'lucide-react'+import { useState } from 'react'import { Controller, type UseFormReturn } from 'react-hook-form'import { useTranslation } from 'react-i18next'-import { CATALOG_PRICING_MODES, type CatalogFormValues } from '../../schemas/catalog'+import {+ CATALOG_PRICING_MODES,+ type CatalogFormValues,+ type CatalogPricingMode,+} from '../../schemas/catalog'import { ADJUSTMENT_DIRECTIONS } from '../../schemas/price-list'+import { BulkPriceEditorDialog } from './bulk-price-editor/bulk-price-editor-dialog'/*** How the agreement prices, edited on the catalog itself: the catalog and the@@ -29,20 +37,28 @@ import { ADJUSTMENT_DIRECTIONS } from '../../schemas/price-list'export function CatalogPricingFields({form,canEdit,- hasOwnedList = false,- onImport,- importing = false,+ priceList,+ savedMode,}: {form: UseFormReturn<CatalogFormValues>canEdit: boolean- /** Drives the detach warning and the import shortcut, both edit-only. */- hasOwnedList?: boolean- onImport?: () => void- importing?: boolean+ /**+ * The list this catalog owns, when it has one. Drives the detach warning+ * and the price spreadsheet; absent on the create sheet, where the list+ * does not exist until Save.+ */+ priceList?: PriceList | null+ /** The mode as last saved, so a switch can be warned about before Save. */+ savedMode?: CatalogPricingMode}) {const { t } = useTranslation()const { errors } = form.formStateconst mode = form.watch('pricing_mode')+ const [priceEditorOpen, setPriceEditorOpen] = useState(false)+ const hasOwnedList = !!priceList+ // Hand-entered amounts beat the adjustment, so switching to a percentage+ // clears them — said before Save, since the rows are not recoverable.+ const willDiscardPrices = savedMode === 'fixed' && mode === 'automatic'const modeItems = CATALOG_PRICING_MODES.map((value) => ({value,@@ -166,14 +182,39 @@ export function CatalogPricingFields({</p>)}- {canEdit && hasOwnedList && mode === 'fixed' && onImport && (- <div>- <Button type="button" size="sm" variant="outline" disabled={importing} onClick={onImport}>- {importing ? t('admin.actions.saving') : t('admin.catalogs.import_from_price_list')}- </Button>- <FieldDescription>{t('admin.catalogs.import_from_price_list_help')}</FieldDescription>- </div>+ {willDiscardPrices && (+ <p className="rounded-md bg-destructive/10 px-3 py-2 text-sm text-destructive" role="alert">+ {t('admin.catalogs.discard_prices_warning')}+ </p>)}++ {/* Fixed pricing is only half-configured until amounts exist, so the+ spreadsheet is offered right here rather than on a page the+ merchant has no reason to know about. Unsaved first: the list is+ created by Save, and there is nothing to price until it is. */}+ {mode === 'fixed' &&+ (priceList ? (+ <div>+ <Button+ type="button"+ size="sm"+ variant="outline"+ disabled={!canEdit}+ onClick={() => setPriceEditorOpen(true)}+ >+ <TableIcon className="size-4" />+ {t('admin.catalogs.edit_prices_cta')}+ </Button>+ <FieldDescription>{t('admin.catalogs.edit_prices_help')}</FieldDescription>+ <BulkPriceEditorDialog+ open={priceEditorOpen}+ onOpenChange={setPriceEditorOpen}+ priceList={priceList}+ />+ </div>+ ) : (+ <FieldDescription>{t('admin.catalogs.edit_prices_after_save')}</FieldDescription>+ ))}</>)}diff --git a/packages/dashboard/src/locales/ar.json b/packages/dashboard/src/locales/ar.jsonindex 137017a9ec..47dcf58ecb 100644--- a/packages/dashboard/src/locales/ar.json+++ b/packages/dashboard/src/locales/ar.json@@ -116,15 +116,18 @@"message": "سيؤدي هذا إلى حذف {{name}} وتعييناته. لن تتأثر المنتجات وقوائم الأسعار.","title": "حذف الكتالوج؟"},- "detach_warning": "سيؤدي الحفظ إلى تحرير قائمة أسعار هذا الكتالوج. ستعود للمطابقة وفق قواعدها الخاصة، والقائمة بلا قواعد تنطبق على كل المتسوقين.",+ "detach_warning": "سيؤدي الحفظ إلى إزالة قائمة أسعار هذا الكتالوج والأسعار التي تتضمنها. سيدفع هذا الجمهور الأسعار العادية.","detail": {"delete_label": "حذف الكتالوج","load_error": "تعذر تحميل هذا الكتالوج",+ "pricing": "التسعير","settings": "الكتالوج"},+ "discard_prices_warning": "التبديل إلى نسبة مئوية سيتجاهل الأسعار المُدخلة لهذا الكتالوج، ولا يمكن استعادتها.",+ "edit_prices_after_save": "احفظ الكتالوج، ثم أدخل أسعار هذا الجمهور.",+ "edit_prices_cta": "إدخال الأسعار",+ "edit_prices_help": "حدّد سعر كل منتج لهذا الجمهور.","empty": "لا توجد كتالوجات بعد",- "import_from_price_list": "استيراد المنتجات من قائمة الأسعار",- "import_from_price_list_help": "ينسخ المنتجات التي يسعّرها هذا الكتالوج إلى تشكيلته.","messages": {"assigned": "تم تعيين الكتالوج","created": "تم إنشاء الكتالوج",@@ -919,6 +922,11 @@}},"catalog": {+ "description": {+ "help": "ملاحظة داخلية — لا تظهر للمتسوقين أبدًا.",+ "label": "الوصف",+ "placeholder": "الغرض من هذه الاتفاقية"+ },"name": {"placeholder": "البيع بالجملة"},diff --git a/packages/dashboard/src/locales/de.json b/packages/dashboard/src/locales/de.jsonindex 0bc36f190f..d77d0bb229 100644--- a/packages/dashboard/src/locales/de.json+++ b/packages/dashboard/src/locales/de.json@@ -116,15 +116,18 @@"message": "Dies löscht {{name}} und seine Zuweisungen. Produkte und Preislisten bleiben unberührt.","title": "Katalog löschen?"},- "detach_warning": "Beim Speichern wird die Preisliste dieses Katalogs freigegeben. Sie greift dann wieder nach ihren eigenen Regeln, und eine Liste ohne Regeln gilt für alle Kundinnen und Kunden.",+ "detach_warning": "Beim Speichern werden die Preisliste dieses Katalogs und die darin enthaltenen Preise entfernt. Diese Zielgruppe zahlt dann normale Preise.","detail": {"delete_label": "Katalog löschen","load_error": "Katalog konnte nicht geladen werden",+ "pricing": "Preisgestaltung","settings": "Katalog"},+ "discard_prices_warning": "Der Wechsel zu einem Prozentsatz verwirft die für diesen Katalog eingegebenen Preise. Sie lassen sich nicht wiederherstellen.",+ "edit_prices_after_save": "Katalog speichern, dann die Preise für diese Zielgruppe eingeben.",+ "edit_prices_cta": "Preise eingeben",+ "edit_prices_help": "Legen Sie fest, was jedes Produkt diese Zielgruppe kostet.","empty": "Noch keine Kataloge",- "import_from_price_list": "Produkte aus Preisliste importieren",- "import_from_price_list_help": "Kopiert die Produkte, die dieser Katalog bepreist, in sein Sortiment.","messages": {"assigned": "Katalog zugewiesen","created": "Katalog erstellt",@@ -905,6 +908,11 @@}},"catalog": {+ "description": {+ "help": "Interne Notiz — für Kundinnen und Kunden nie sichtbar.",+ "label": "Beschreibung",+ "placeholder": "Wozu diese Vereinbarung dient"+ },"name": {"placeholder": "Großhandel"},diff --git a/packages/dashboard/src/locales/en.json b/packages/dashboard/src/locales/en.jsonindex 22c22235c9..3acc16573d 100644--- a/packages/dashboard/src/locales/en.json+++ b/packages/dashboard/src/locales/en.json@@ -116,15 +116,18 @@"message": "This deletes {{name}} and its assignments. Products and price lists are not affected.","title": "Delete catalog?"},- "detach_warning": "Saving will release this catalog’s price list. It will start matching by its own rules again, and a list with no rules applies to every shopper.",+ "detach_warning": "Saving will remove this catalog’s price list and the prices in it. This audience will pay normal prices.","detail": {"delete_label": "Delete catalog","load_error": "Could not load this catalog",+ "pricing": "Pricing","settings": "Catalog"},+ "discard_prices_warning": "Switching to a percentage will discard the prices entered for this catalog. They cannot be recovered.",+ "edit_prices_after_save": "Save the catalog, then enter the prices for this audience.",+ "edit_prices_cta": "Enter prices",+ "edit_prices_help": "Set the price each product costs this audience.","empty": "No catalogs yet",- "import_from_price_list": "Import products from price list",- "import_from_price_list_help": "Copies the products this catalog prices into its assortment.","messages": {"assigned": "Catalog assigned","created": "Catalog created",@@ -905,6 +908,11 @@}},"catalog": {+ "description": {+ "help": "Internal note — never shown to shoppers.",+ "label": "Description",+ "placeholder": "What this agreement is for"+ },"name": {"placeholder": "Wholesale"},diff --git a/packages/dashboard/src/locales/fr.json b/packages/dashboard/src/locales/fr.jsonindex e14f9ab02b..c1cfe3e971 100644--- a/packages/dashboard/src/locales/fr.json+++ b/packages/dashboard/src/locales/fr.json@@ -116,15 +116,18 @@"message": "Cela supprime {{name}} et ses affectations. Les produits et listes de prix ne sont pas affectés.","title": "Supprimer le catalogue ?"},- "detach_warning": "L’enregistrement libérera la liste de prix de ce catalogue. Elle s’appliquera de nouveau selon ses propres règles, et une liste sans règle vaut pour tous les clients.",+ "detach_warning": "L’enregistrement supprimera la liste de prix de ce catalogue et les prix qu’elle contient. Cette audience paiera les prix normaux.","detail": {"delete_label": "Supprimer le catalogue","load_error": "Impossible de charger ce catalogue",+ "pricing": "Tarification","settings": "Catalogue"},+ "discard_prices_warning": "Passer à un pourcentage supprimera les prix saisis pour ce catalogue. Ils ne pourront pas être récupérés.",+ "edit_prices_after_save": "Enregistrez le catalogue, puis saisissez les prix de cette audience.",+ "edit_prices_cta": "Saisir les prix",+ "edit_prices_help": "Définissez le prix de chaque produit pour cette audience.","empty": "Aucun catalogue pour le moment",- "import_from_price_list": "Importer les produits de la liste de prix",- "import_from_price_list_help": "Copie dans l’assortiment les produits que ce catalogue tarifie.","messages": {"assigned": "Catalogue affecté","created": "Catalogue créé",@@ -905,6 +908,11 @@}},"catalog": {+ "description": {+ "help": "Note interne — jamais montrée aux clients.",+ "label": "Description",+ "placeholder": "À quoi sert cet accord"+ },"name": {"placeholder": "Grossiste"},diff --git a/packages/dashboard/src/locales/pl.json b/packages/dashboard/src/locales/pl.jsonindex fdea5b574b..c7fb0f90da 100644--- a/packages/dashboard/src/locales/pl.json+++ b/packages/dashboard/src/locales/pl.json@@ -118,15 +118,18 @@"message": "To usunie {{name}} wraz z przypisaniami. Produkty i cenniki pozostaną nietknięte.","title": "Usunąć katalog?"},- "detach_warning": "Zapis zwolni cennik tego katalogu. Zacznie on ponownie działać według własnych reguł, a cennik bez reguł obejmuje wszystkich klientów.",+ "detach_warning": "Zapis usunie cennik tego katalogu wraz z zawartymi w nim cenami. Ta grupa odbiorców będzie płacić zwykłe ceny.","detail": {"delete_label": "Usuń katalog","load_error": "Nie udało się wczytać tego katalogu",+ "pricing": "Ceny","settings": "Katalog"},+ "discard_prices_warning": "Przejście na wartość procentową usunie ceny wpisane dla tego katalogu. Nie będzie można ich odzyskać.",+ "edit_prices_after_save": "Zapisz katalog, a następnie wprowadź ceny dla tej grupy odbiorców.",+ "edit_prices_cta": "Wprowadź ceny",+ "edit_prices_help": "Ustal, ile każdy produkt kosztuje tę grupę odbiorców.","empty": "Brak katalogów",- "import_from_price_list": "Importuj produkty z cennika",- "import_from_price_list_help": "Kopiuje do asortymentu produkty, które ten katalog wycenia.","messages": {"assigned": "Katalog przypisany","created": "Katalog utworzony",@@ -917,6 +920,11 @@}},"catalog": {+ "description": {+ "help": "Notatka wewnętrzna — nigdy nie widoczna dla klientów.",+ "label": "Opis",+ "placeholder": "Czemu służy ta umowa"+ },"name": {"placeholder": "Hurt"},diff --git a/packages/dashboard/src/locales/zh-CN.json b/packages/dashboard/src/locales/zh-CN.jsonindex ed281485a5..3b83e48d5e 100644--- a/packages/dashboard/src/locales/zh-CN.json+++ b/packages/dashboard/src/locales/zh-CN.json@@ -116,15 +116,18 @@"message": "这将删除 {{name}} 及其分配。产品和价格表不受影响。","title": "删除目录?"},- "detach_warning": "保存后将释放此目录的价目表。它将重新按自身规则匹配,而没有规则的价目表会对所有顾客生效。",+ "detach_warning": "保存后将删除此目录的价目表及其中的价格。此受众将支付正常价格。","detail": {"delete_label": "删除目录","load_error": "无法加载该目录",+ "pricing": "定价","settings": "目录"},+ "discard_prices_warning": "切换为百分比将丢弃为此目录输入的价格,且无法恢复。",+ "edit_prices_after_save": "保存目录后,再为此受众输入价格。",+ "edit_prices_cta": "输入价格",+ "edit_prices_help": "设置每件商品对此受众的价格。","empty": "暂无目录",- "import_from_price_list": "从价格表导入产品",- "import_from_price_list_help": "将此目录定价的商品复制到其商品组合中。","messages": {"assigned": "目录已分配","created": "目录已创建",@@ -901,6 +904,11 @@}},"catalog": {+ "description": {+ "help": "内部备注 — 顾客永远不会看到。",+ "label": "描述",+ "placeholder": "此协议的用途"+ },"name": {"placeholder": "批发"},diff --git a/packages/dashboard/src/nav/default.ts b/packages/dashboard/src/nav/default.tsindex 95eb5f71fb..f3b9a549cf 100644--- a/packages/dashboard/src/nav/default.ts+++ b/packages/dashboard/src/nav/default.ts@@ -96,18 +96,20 @@ nav.add({subject: Subject.Product,position: 300,children: [- {- key: 'products.price-lists',- labelKey: 'admin.nav.price_lists',- path: '/products/price-lists',- subject: Subject.PriceList,- position: 100,- },+ // Catalogs first: the catalog is the agreement a merchant sets up, and+ // a price list is one thing a catalog can own.{key: 'products.catalogs',labelKey: 'admin.nav.catalogs',path: '/products/catalogs',subject: Subject.Catalog,+ position: 100,+ },+ {+ key: 'products.price-lists',+ labelKey: 'admin.nav.price_lists',+ path: '/products/price-lists',+ subject: Subject.PriceList,position: 200,},{diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/products/catalogs/$catalogId.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/products/catalogs/$catalogId.tsxindex 4ead27001b..a90ee6928c 100644--- a/packages/dashboard/src/routes/_authenticated/$storeId/products/catalogs/$catalogId.tsx+++ b/packages/dashboard/src/routes/_authenticated/$storeId/products/catalogs/$catalogId.tsx@@ -37,6 +37,7 @@ import {SelectItem,SelectTrigger,SelectValue,+ Textarea,useConfirm,} from '@spree/dashboard-ui'import { createFileRoute, useNavigate } from '@tanstack/react-router'@@ -53,7 +54,6 @@ import {useCatalog,useCatalogProducts,useDeleteCatalog,- useImportCatalogPriceListProducts,useSaveCatalog,useUnassignCatalog,} from '../../../../../hooks/use-catalogs'@@ -106,6 +106,11 @@ function CatalogBody({ catalog }: { catalog: Catalog }) {const canEdit = permissions.can('update', Subject.Catalog)+ // The mode as last saved, not as currently selected: switching away from+ // hand-entered prices has to clear them, and the warning has to know a+ // switch is what is about to happen.+ const savedPricingMode = catalogPricingValues(catalog.price_list).pricing_mode+const form = useForm<CatalogFormValues>({// eslint-disable-next-line @typescript-eslint/no-explicit-anyresolver: zodResolver(catalogFormSchema) as any,@@ -113,13 +118,14 @@ function CatalogBody({ catalog }: { catalog: Catalog }) {})// Hydrate (and re-baseline after save) from the source row, unless the- // merchant has unsaved edits in flight: importing from the price list- // refetches the catalog mid-edit, and an unguarded reset would drop both- // the settings being typed and any staged product changes.+ // merchant has unsaved edits in flight: entering prices refetches the+ // catalog mid-edit, and an unguarded reset would drop both the settings+ // being typed and any staged product changes.useEffect(() => {if (form.formState.isDirty) returnform.reset({name: catalog.name,+ description: catalog.description ?? '',active: catalog.active,...catalogPricingValues(catalog.price_list),staged_products: { adds: [], removes: [] },@@ -134,7 +140,7 @@ function CatalogBody({ catalog }: { catalog: Catalog }) {async function handleSave(values: CatalogFormValues) {try {await saveMutation.mutateAsync({- attributes: catalogValuesToParams(values),+ attributes: catalogValuesToParams(values, savedPricingMode),addProductIds: values.staged_products.adds.map((product) => product.id),removeProductIds: values.staged_products.removes,})@@ -202,7 +208,8 @@ function CatalogBody({ catalog }: { catalog: Catalog }) {}sidebar={<>- <CatalogSettingsCard catalog={catalog} form={form} canEdit={canEdit} />+ <CatalogSettingsCard form={form} canEdit={canEdit} />+ <CatalogPricingCard catalog={catalog} form={form} canEdit={canEdit} /><CatalogAssignmentsCard catalog={catalog} canEdit={canEdit} /></>}@@ -212,7 +219,12 @@ function CatalogBody({ catalog }: { catalog: Catalog }) {)}-function CatalogSettingsCard({+/**+ * What the agreement pays. Its own card rather than a field on the settings+ * card: pricing is the consequential half of a catalog, and burying it under+ * the name reads as an afterthought.+ */+function CatalogPricingCard({catalog,form,canEdit,@@ -222,7 +234,34 @@ function CatalogSettingsCard({canEdit: boolean}) {const { t } = useTranslation()- const importMutation = useImportCatalogPriceListProducts(catalog.id)++ return (+ <Card>+ <CardHeader>+ <CardTitle>{t('admin.catalogs.detail.pricing')}</CardTitle>+ </CardHeader>+ <CardContent>+ <FieldGroup>+ <CatalogPricingFields+ form={form}+ canEdit={canEdit}+ priceList={catalog.price_list}+ savedMode={catalogPricingValues(catalog.price_list).pricing_mode}+ />+ </FieldGroup>+ </CardContent>+ </Card>+ )+}++function CatalogSettingsCard({+ form,+ canEdit,+}: {+ form: UseFormReturn<CatalogFormValues>+ canEdit: boolean+}) {+ const { t } = useTranslation()const { errors } = form.formState@@ -244,13 +283,19 @@ function CatalogSettingsCard({<FieldError errors={[errors.name]} /></Field>- <CatalogPricingFields- form={form}- canEdit={canEdit}- hasOwnedList={!!catalog.price_list_id}- onImport={() => importMutation.mutate()}- importing={importMutation.isPending}- />+ <Field>+ <FieldLabel htmlFor="catalog-description">+ {t('admin.fields.catalog.description.label')}+ </FieldLabel>+ <Textarea+ id="catalog-description"+ rows={3}+ disabled={!canEdit}+ placeholder={t('admin.fields.catalog.description.placeholder')}+ {...form.register('description')}+ />+ <FieldDescription>{t('admin.fields.catalog.description.help')}</FieldDescription>+ </Field><Controllercontrol={form.control}diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/products/price-lists/index.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/products/price-lists/index.tsxindex a45a01c900..a248946bb6 100644--- a/packages/dashboard/src/routes/_authenticated/$storeId/products/price-lists/index.tsx+++ b/packages/dashboard/src/routes/_authenticated/$storeId/products/price-lists/index.tsx@@ -64,7 +64,10 @@ function PriceListsPage() {<ResourceTable<PriceList>tableKey="price-lists"queryKey="price-lists"- queryFn={(params) => adminClient.priceLists.list(params)}+ // Standalone lists only. A list a catalog owns has no rules and no+ // audience of its own — it is edited on that catalog, and listing it+ // here would offer a page whose controls do not apply to it.+ queryFn={(params) => adminClient.priceLists.list({ ...params, catalog_id_null: true })}searchParams={search}rowActions={(list) => (<RowActionsdiff --git a/packages/dashboard/src/schemas/catalog.ts b/packages/dashboard/src/schemas/catalog.tsindex 4958a16ce3..ca3b576a36 100644--- a/packages/dashboard/src/schemas/catalog.ts+++ b/packages/dashboard/src/schemas/catalog.ts@@ -1,4 +1,5 @@import type { CatalogParams } from '@spree/admin-sdk'+import { blankToNull } from '@spree/dashboard-core'import { requiredMessage } from '@spree/dashboard-ui'import i18n from 'i18next'import { z } from 'zod/v4'@@ -24,6 +25,7 @@ export type CatalogPricingMode = (typeof CATALOG_PRICING_MODES)[number]export const catalogFormSchema = z.object({name: z.string().min(1, { error: requiredMessage('name') }),+ description: z.string().trim().optional(),/*** Staged product membership, applied on Save through the nested products* endpoints. Opaque by design — it holds SDK `Product` records so a staged@@ -67,6 +69,7 @@ export type CatalogFormValues = z.infer<typeof catalogFormSchema>/** A new catalog: named on create, active, priced by base prices. */export const CATALOG_DEFAULTS: CatalogFormValues = {name: '',+ description: '',active: true,pricing_mode: 'base',adjustment_direction: 'decrease',@@ -82,15 +85,20 @@ export const CATALOG_DEFAULTS: CatalogFormValues = {* — which is a deliberate act, since a released list starts matching by its* own rules again.*/-export function catalogValuesToParams(values: CatalogFormValues): CatalogParams {+export function catalogValuesToParams(+ values: CatalogFormValues,+ /** The mode the catalog was saved in, so a switch can be told from a plain save. */+ previousMode?: CatalogPricingMode,+): CatalogParams {return {name: values.name,+ description: blankToNull(values.description),active: values.active,- price_list: priceListPayload(values),+ price_list: priceListPayload(values, previousMode),}}-function priceListPayload(values: CatalogFormValues) {+function priceListPayload(values: CatalogFormValues, previousMode?: CatalogPricingMode) {if (values.pricing_mode === 'base') return nullif (values.pricing_mode === 'fixed') {@@ -100,13 +108,20 @@ function priceListPayload(values: CatalogFormValues) {}const magnitude = parsePercentage(values.adjustment_magnitude)- if (magnitude === null) return { adjust_compare_at: values.adjust_compare_at }+ const base =+ magnitude === null+ ? { adjust_compare_at: values.adjust_compare_at }+ : {+ price_adjustment_percentage: String(+ values.adjustment_direction === 'decrease' ? -magnitude : magnitude,+ ),+ adjust_compare_at: values.adjust_compare_at,+ }- const signed = values.adjustment_direction === 'decrease' ? -magnitude : magnitude- return {- price_adjustment_percentage: String(signed),- adjust_compare_at: values.adjust_compare_at,- }+ // Switching away from hand-entered prices clears them. An explicit amount+ // beats the adjustment by design, so leaving the old rows behind would+ // keep charging them while the card claims a percentage is in effect.+ return previousMode === 'fixed' ? { ...base, prices: [] } : base}/**diff --git a/packages/dashboard/src/tables/catalogs.tsx b/packages/dashboard/src/tables/catalogs.tsxindex 248d207ba8..e4f22a69af 100644--- a/packages/dashboard/src/tables/catalogs.tsx+++ b/packages/dashboard/src/tables/catalogs.tsx@@ -18,7 +18,12 @@ defineTable<Catalog>('catalogs', {sortable: true,default: true,render: (catalog) => (- <ResourceNameCell id={catalog.id} dataAttr="data-catalog-id" name={catalog.name} />+ <ResourceNameCell+ id={catalog.id}+ dataAttr="data-catalog-id"+ name={catalog.name}+ secondary={catalog.description ?? undefined}+ />),},{diff --git a/spree/api/app/controllers/spree/api/v3/admin/catalogs_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/catalogs_controller.rbindex e0d4d16890..4f51f56d7c 100644--- a/spree/api/app/controllers/spree/api/v3/admin/catalogs_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/catalogs_controller.rb@@ -76,12 +76,17 @@ module Spree# leaves it alone.def permitted_paramspermitted = params.permit(*model_additional_permitted_attributes,- :name, :active, :position, :price_list_id,+ :name, :description, :active, :position, :price_list_id,metadata: {},price_list: [:name, :description, :status, :match_policy,:starts_at, :ends_at,- :price_adjustment_percentage, :adjust_compare_at+ :price_adjustment_percentage, :adjust_compare_at,+ # An empty array clears the hand-entered+ # amounts — what switching to a+ # percentage sends.+ { prices: [:id, :variant_id, :currency, :amount,+ :compare_at_amount] }])if permitted.key?(:price_list_id)permitted[:price_list_id] =diff --git a/spree/api/app/serializers/spree/api/v3/admin/catalog_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/catalog_serializer.rbindex 65d04b8ed5..dec367b259 100644--- a/spree/api/app/serializers/spree/api/v3/admin/catalog_serializer.rb+++ b/spree/api/app/serializers/spree/api/v3/admin/catalog_serializer.rb@@ -5,12 +5,13 @@ module Spree# Admin-only: catalogs are merchandising configuration with no# storefront surface — buyers see their effects, never the record.class CatalogSerializer < V3::BaseSerializer- typelize name: :string, active: :boolean, position: [:number, nullable: true],+ typelize name: :string, description: 'string | null',+ active: :boolean, position: [:number, nullable: true],price_list_id: [:string, nullable: true],products_count: :number,metadata: 'Record<string, unknown> | null'- attributes :name, :active, :position, :metadata,+ attributes :name, :description, :active, :position, :metadata,created_at: :iso8601, updated_at: :iso8601attribute :price_list_id do |catalog|diff --git a/spree/api/spec/controllers/spree/api/v3/admin/catalogs_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/catalogs_controller_spec.rbindex 99f75b0c5b..cdb38e0ee6 100644--- a/spree/api/spec/controllers/spree/api/v3/admin/catalogs_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/admin/catalogs_controller_spec.rb@@ -11,6 +11,14 @@ RSpec.describe Spree::Api::V3::Admin::CatalogsController, type: :controller do# Standing up an agreement is one request — the catalog and the list it# prices through (docs/plans/6.0-catalog-agreement-rework.md).+ it 'writes and returns the description' do+ patch :update, params: { id: catalog.prefixed_id, description: 'Negotiated 2026 terms' }, as: :json++ expect(response).to have_http_status(:ok)+ expect(json_response['description']).to eq('Negotiated 2026 terms')+ expect(catalog.reload.description).to eq('Negotiated 2026 terms')+ end+describe 'the inline price_list payload' doit 'creates the catalog and its owned list together' dopost :create,@@ -46,7 +54,9 @@ RSpec.describe Spree::Api::V3::Admin::CatalogsController, type: :controller doexpect(created.price_list.price_adjustment_percentage).to eq(-20)end- it 'detaches on an explicit null, keeping the list itself' do+ # A released list would price every shopper, since an owned list carries+ # no rules — so removal takes the list with it.+ it 'removes the owned list on an explicit null' dopost :create, params: { name: 'Tier', price_list: { price_adjustment_percentage: '-10' } }, as: :jsoncreated = store.catalogs.find_by(name: 'Tier')list_id = created.price_list.id@@ -55,7 +65,7 @@ RSpec.describe Spree::Api::V3::Admin::CatalogsController, type: :controller doexpect(response).to have_http_status(:ok)expect(created.reload.price_list).to be_nil- expect(Spree::PriceList.find(list_id).catalog_id).to be_nil+ expect(Spree::PriceList.where(id: list_id)).to be_emptyendit 'leaves the list alone when the key is omitted' do@@ -78,6 +88,21 @@ RSpec.describe Spree::Api::V3::Admin::CatalogsController, type: :controller doexpect(response).to have_http_status(:unprocessable_content)end+ it 'clears hand-entered amounts when the payload says to' do+ post :create, params: { name: 'Tier', price_list: { name: 'Fixed' } }, as: :json+ created = store.catalogs.find_by(name: 'Tier')+ variant = create(:variant)+ create(:price, variant: variant, currency: 'EUR', amount: 5, price_list: created.price_list)++ patch :update,+ params: { id: created.prefixed_id,+ price_list: { price_adjustment_percentage: '-15', prices: [] } },+ as: :json++ expect(response).to have_http_status(:ok)+ expect(created.reload.price_list.prices.first.amount).to be_nil+ end+it 'expands the owned list on read' dopost :create, params: { name: 'Tier', price_list: { price_adjustment_percentage: '-10' } }, as: :jsoncreated = store.catalogs.find_by(name: 'Tier')diff --git a/spree/core/app/models/spree/catalog.rb b/spree/core/app/models/spree/catalog.rbindex f28fed8d43..493c572b55 100644--- a/spree/core/app/models/spree/catalog.rb+++ b/spree/core/app/models/spree/catalog.rb@@ -22,11 +22,13 @@ module Spreebelongs_to :store, class_name: 'Spree::Store', inverse_of: :catalogs# The owned list, or nil for an assortment-only catalog priced at base.- # The FK lives on the list (a list is standalone or owned by exactly one- # catalog); detaching or destroying the catalog releases the list back to- # standalone — an explicit act, since a rule-less standalone list starts- # matching by its own (absent) rules.- has_one :price_list, class_name: 'Spree::PriceList', inverse_of: :catalog, dependent: :nullify+ # The FK lives on the list: a list is standalone or owned by exactly one+ # catalog.+ #+ # Destroyed with the catalog rather than released, because an owned list+ # carries no rules of its own — released, it would match every shopper in+ # the store. The list is paranoid, so this is a soft delete.+ has_one :price_list, class_name: 'Spree::PriceList', inverse_of: :catalog, dependent: :destroyhas_many :catalog_products, class_name: 'Spree::CatalogProduct', dependent: :destroy,inverse_of: :catalogdiff --git a/spree/core/app/workflows/spree/catalogs/set_price_list.rb b/spree/core/app/workflows/spree/catalogs/set_price_list.rbindex ced0b2cbbc..9e7c208982 100644--- a/spree/core/app/workflows/spree/catalogs/set_price_list.rb+++ b/spree/core/app/workflows/spree/catalogs/set_price_list.rb@@ -1,13 +1,11 @@module Spreemodule Catalogs# Writes the price list a catalog prices through, from an inline payload:- # creates the owned list, updates the one already owned, or detaches with- # nil (docs/plans/6.0-catalog-agreement-rework.md).+ # creates the owned list, updates the one already owned, or removes it+ # with nil (docs/plans/6.0-catalog-agreement-rework.md).#- # Detaching is an explicit act with a consequence — a released list starts- # matching by its own rules again, and a rule-less one matches everyone —- # so it happens only when the caller sends `price_list: null`, never as a- # side effect of omitting the key.+ # Removal happens only on an explicit `price_list: null`, never as a side+ # effect of omitting the key.class SetPriceList < Spree::Workflowattr_reader :catalog@@ -33,13 +31,14 @@ module Spreecreate_ownedend- # Releases the list back to standalone matching. The list itself is- # kept: it holds prices someone entered, and deleting it because an- # agreement moved on would lose them.+ # Removes the list the catalog owns, rather than releasing it to+ # standalone matching: an owned list carries no rules, so released it+ # would price every shopper in the store. Soft-deleted, since the model+ # is paranoid.def detachreturn if catalog.price_list.nil?- failure(catalog) unless catalog.update(price_list: nil)+ failure(catalog) unless catalog.price_list.destroyenddef update_existing(price_list)diff --git a/spree/core/db/migrate/20260825000001_create_spree_catalogs.rb b/spree/core/db/migrate/20260825000001_create_spree_catalogs.rbindex 1ad74e869e..5e7df9761b 100644--- a/spree/core/db/migrate/20260825000001_create_spree_catalogs.rb+++ b/spree/core/db/migrate/20260825000001_create_spree_catalogs.rb@@ -3,6 +3,9 @@ class CreateSpreeCatalogs < ActiveRecord::Migration[8.1]create_table :spree_catalogs do |t|t.references :store, null: falset.string :name, null: false+ # What the agreement is, in the operator's own words — never shown to+ # a shopper, like a price list's.+ t.text :descriptiont.boolean :active, null: false, default: truet.integer :positionif t.respond_to?(:jsonb)diff --git a/spree/core/spec/models/spree/catalog_spec.rb b/spree/core/spec/models/spree/catalog_spec.rbindex cd676270e0..fdc457b7ff 100644--- a/spree/core/spec/models/spree/catalog_spec.rb+++ b/spree/core/spec/models/spree/catalog_spec.rb@@ -286,18 +286,19 @@ describe Spree::Catalog, type: :model doexpect(price_list.reload.catalog_id).not_to eq(other.id)end- it 'releases the list back to standalone when the catalog is destroyed' do+ # Releasing the list would let it match by its own rules, and an owned+ # list has none — so it would price every shopper. It goes with the+ # catalog instead, soft-deleted so it stays recoverable.+ it 'takes the list with it when the catalog is destroyed' docatalog = create(:catalog, store: store, price_list: price_list)catalog.destroy!- expect(price_list.reload.catalog_id).to be_nil+ expect(Spree::PriceList.where(id: price_list.id)).to be_empty+ expect(Spree::PriceList.with_deleted.find(price_list.id)).to be_presentend- # `dependent: :nullify` releases the list with an update_all, which never- # runs PriceList's own callback — so without the catalog clearing it, the- # released list stays missing from this request's matching set.- it 'makes a list released by destroy visible to the rest of the request' do+ it 'does not leave the destroyed catalog list pricing the store' doprice_list.update!(status: 'active')catalog = create(:catalog, store: store, price_list: price_list)Spree::Current.store = store@@ -305,7 +306,7 @@ describe Spree::Catalog, type: :model docatalog.destroy!- expect(Spree::Current.price_lists.map(&:id)).to include(price_list.id)+ expect(Spree::Current.price_lists.map(&:id)).not_to include(price_list.id)end# The binding is written with update_all, which never touches thediff --git a/spree/core/spec/workflows/spree/catalogs/set_price_list_spec.rb b/spree/core/spec/workflows/spree/catalogs/set_price_list_spec.rbindex da05aa759e..f12c828267 100644--- a/spree/core/spec/workflows/spree/catalogs/set_price_list_spec.rb+++ b/spree/core/spec/workflows/spree/catalogs/set_price_list_spec.rb@@ -44,18 +44,29 @@ describe Spree::Catalogs::SetPriceList doexpect(catalog.price_list.price_adjustment_percentage).to eq(-20)end- # Detaching releases the list to standalone matching, so it is only ever an- # explicit act — and the list itself survives, since it holds prices someone- # entered.- it 'detaches on a blank payload, keeping the list' do+ # Releasing an owned list to standalone matching would let it price every+ # shopper, since an owned list has no rules of its own. The list goes with+ # the pricing it existed for — soft-deleted, so it stays recoverable.+ it 'removes the list on a blank payload rather than releasing it' docall(price_adjustment_percentage: '-15')list = catalog.reload.price_listexpect(described_class.call(catalog: catalog, attributes: nil)).to be_successexpect(catalog.reload.price_list).to be_nil- expect(list.reload.catalog_id).to be_nil- expect(list).to be_persisted+ expect(Spree::PriceList.where(id: list.id)).to be_empty+ expect(Spree::PriceList.with_deleted.find(list.id)).to be_present+ end++ it 'does not leave the removed list matching anyone' do+ variant = create(:variant)+ variant.prices.base_prices.with_currency('USD').update_all(amount: 20)+ call(price_adjustment_percentage: '-15')++ described_class.call(catalog: catalog, attributes: nil)++ context = Spree::Pricing::Context.new(variant: variant, currency: 'USD', store: store)+ expect(Spree::PricingProvider::Internal::Resolution.new(context).resolve.amount).to eq(20)endit 'is a no-op when detaching a catalog that owns nothing' do@@ -63,6 +74,31 @@ describe Spree::Catalogs::SetPriceList doexpect(catalog.reload.price_list).to be_nilend+ # An explicit amount beats the adjustment by design, so a merchant who+ # switches to a percentage must not keep paying the old hand-entered price.+ # The dashboard sends `prices: []` on that switch.+ it 'clears hand-entered amounts when asked, so the adjustment takes over' do+ variant = create(:variant)+ variant.prices.base_prices.with_currency('USD').update_all(amount: 20)+ call(price_adjustment_percentage: nil)+ list = catalog.reload.price_list+ create(:price, variant: variant, currency: 'USD', amount: 5.00, price_list: list)++ call(price_adjustment_percentage: '-15', prices: [])++ expect(list.prices.reload.first.amount).to be_nil++ group = create(:customer_group, store: store)+ customer = create(:customer)+ group.customer_group_users.create!(customer: customer)+ create(:catalog_assignment, catalog: catalog, assignable: group)+ context = Spree::Pricing::Context.new(+ variant: variant, currency: 'USD', store: store, user: customer+ )++ expect(Spree::PricingProvider::Internal::Resolution.new(context).resolve.amount).to eq(17)+ end+it 'fails without creating a list when the adjustment is invalid' doresult = nilexpect { result = call(price_adjustment_percentage: '-100') }.