Skip to content

armgit / spree

Public Imported from GitHub
0

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.

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.mdx
index 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>
## Related
diff --git a/docs/plans/6.0-catalog-agreement-rework.md b/docs/plans/6.0-catalog-agreement-rework.md
index 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** (revised
2026-08-30 after review — supersedes the same-day "deprecated + data
task" decision). `PriceRules::CustomerGroupRule` and
diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.ts
index 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 | null
active?: boolean
position?: number
/**
diff --git a/packages/admin-sdk/src/types/generated/Catalog.ts b/packages/admin-sdk/src/types/generated/Catalog.ts
index 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.tsx
index 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.formState
const 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.json
index 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.json
index 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.json
index 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.json
index 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.json
index 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.json
index 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.ts
index 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.tsx
index 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-any
resolver: 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) return
form.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>
<Controller
control={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.tsx
index 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) => (
<RowActions
diff --git a/packages/dashboard/src/schemas/catalog.ts b/packages/dashboard/src/schemas/catalog.ts
index 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 null
if (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.tsx
index 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.rb
index 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_params
permitted = 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.rb
index 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: :iso8601
attribute :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.rb
index 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' do
it 'creates the catalog and its owned list together' do
post :create,
@@ -46,7 +54,9 @@ RSpec.describe Spree::Api::V3::Admin::CatalogsController, type: :controller do
expect(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' do
post :create, params: { name: 'Tier', price_list: { price_adjustment_percentage: '-10' } }, as: :json
created = 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 do
expect(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_empty
end
it 'leaves the list alone when the key is omitted' do
@@ -78,6 +88,21 @@ RSpec.describe Spree::Api::V3::Admin::CatalogsController, type: :controller do
expect(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' do
post :create, params: { name: 'Tier', price_list: { price_adjustment_percentage: '-10' } }, as: :json
created = store.catalogs.find_by(name: 'Tier')
diff --git a/spree/core/app/models/spree/catalog.rb b/spree/core/app/models/spree/catalog.rb
index f28fed8d43..493c572b55 100644
--- a/spree/core/app/models/spree/catalog.rb
+++ b/spree/core/app/models/spree/catalog.rb
@@ -22,11 +22,13 @@ module Spree
belongs_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: :destroy
has_many :catalog_products, class_name: 'Spree::CatalogProduct', dependent: :destroy,
inverse_of: :catalog
diff --git a/spree/core/app/workflows/spree/catalogs/set_price_list.rb b/spree/core/app/workflows/spree/catalogs/set_price_list.rb
index 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 Spree
module 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::Workflow
attr_reader :catalog
@@ -33,13 +31,14 @@ module Spree
create_owned
end
- # 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 detach
return if catalog.price_list.nil?
- failure(catalog) unless catalog.update(price_list: nil)
+ failure(catalog) unless catalog.price_list.destroy
end
def 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.rb
index 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: false
t.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 :description
t.boolean :active, null: false, default: true
t.integer :position
if t.respond_to?(:jsonb)
diff --git a/spree/core/spec/models/spree/catalog_spec.rb b/spree/core/spec/models/spree/catalog_spec.rb
index 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 do
expect(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' do
catalog = 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_present
end
- # `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' do
price_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 do
catalog.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 the
diff --git a/spree/core/spec/workflows/spree/catalogs/set_price_list_spec.rb b/spree/core/spec/workflows/spree/catalogs/set_price_list_spec.rb
index 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 do
expect(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' do
call(price_adjustment_percentage: '-15')
list = catalog.reload.price_list
expect(described_class.call(catalog: catalog, attributes: nil)).to be_success
expect(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)
end
it 'is a no-op when detaching a catalog that owns nothing' do
@@ -63,6 +74,31 @@ describe Spree::Catalogs::SetPriceList do
expect(catalog.reload.price_list).to be_nil
end
+ # 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' do
result = nil
expect { result = call(price_adjustment_percentage: '-100') }.