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
Clarify how to set company price tiers with catalogs (#14573)
Kacper Mękarskia07861928faa
diff --git a/docs/developer/core-concepts/catalogs.mdx b/docs/developer/core-concepts/catalogs.mdxindex 4baf308c77..efac249221 100644--- a/docs/developer/core-concepts/catalogs.mdx+++ b/docs/developer/core-concepts/catalogs.mdx@@ -109,7 +109,7 @@ await adminClient.catalogs.assign(catalog.id, {## What a shopper ends up seeing-When several catalogs could apply, they combine rather than compete:+The three ways of reaching a buyer are tried in turn, and the first one that finds a catalog answers on its own. Once that's settled, everything it found combines:<Steps><Step title="Find the catalogs that apply">@@ -125,6 +125,14 @@ When several catalogs could apply, they combine rather than compete:Gated storefront access is checked before any of this — a shopper who has to sign in never reaches catalog resolution.+<Warning>+**A company buyer never picks up their customer group's catalogs.** As soon as any catalog is assigned to their company or one above it, that is their agreement, and group assignments are not consulted for them.++So don't express trade tiers as customer groups over a company tree — the tier catalogs would be unreachable for exactly the buyers they were meant for. Model tiers as company assignments: the group-wide range on the root, and each tier's catalog on the member companies or divisions in that tier. One tier catalog can carry as many company assignments as the tier has members, and nearest-first pricing means a buyer's own node beats anything inherited.++Customer group assignments are for buyers who aren't purchasing for a company at all — a retail loyalty tier, a staff discount.+</Warning>+## How pricing resolvesPrices are checked in order, and the first match wins:diff --git a/docs/plans/6.0-b2b-companies-and-catalogs.md b/docs/plans/6.0-b2b-companies-and-catalogs.mdindex 38f92e0558..dc4f29e81d 100644--- a/docs/plans/6.0-b2b-companies-and-catalogs.md+++ b/docs/plans/6.0-b2b-companies-and-catalogs.md@@ -401,7 +401,10 @@ amendments:their union; else if the customer's group has a catalog, intersect withthat; else all channel listings (channel default catalog if set). Thegated-access layer (5.6) still runs first — a `login_required` guest never- reaches this resolver.+ reaches this resolver. **Reaffirmed 2026-09-04 (V-3570):** those are+ alternatives, not layers — a buyer whose company subtree carries any+ catalog is never also served their customer group's, and trade tiers over+ a company tree are expressed as company assignments (see decisions.md).- **Pricing**: `Pricing::Resolver` checks the effective catalogs'PriceLists in **nearest-node-first** order (the purchase node's ownassignments before its parent's, catalog `position` breaking ties within adiff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex 440a5f9ddc..bb38afed39 100644--- a/docs/plans/decisions.md+++ b/docs/plans/decisions.md@@ -1,3 +1,11 @@+## 2026-09-04: Catalog audiences are alternatives, not layers — a company buyer is never also priced by their customer group (V-3570)++**Context:** `Catalog.for_context` consults a buyer's customer groups only when the company axis came back empty, so a merchant who put a shared range on a dealer group's company node and each trade tier on a customer group got tier prices that never applied — every dealer paid retail, with the catalog active, the audience assigned and the percentage saved. The code said two things about whether that was intended: the plan and the resolver describe a fallback chain, while `Spree::Catalog`'s class comment said visibility across applicable catalogs is their union, which reads as both audiences being consulted. The reading had to be ruled before either could be documented.++**Decision:** The fallback chain is the intended behaviour and stays: the company subtree if any of its nodes carry a catalog, otherwise the customer's groups, otherwise the channel's default catalog. A buyer is on one agreement, resolved from the nearest party to them — layering a personal segment's prices on top of a company's negotiated ones would price one purchase under two agreements at once, and which won would depend on catalog position rather than on anything a merchant chose. Trade tiers over a company tree are expressed as company assignments: the shared range on the root, each tier's catalog on the member companies or divisions in that tier (one tier catalog carries as many assignments as the tier has members). That route already works and is what the union-within-an-audience plus nearest-node-first pricing was built for. Customer group assignments remain for buyers not purchasing for a company at all — a retail loyalty tier, a staff discount.++**Consequences:** No behaviour change; the fix is that the code and the dashboard now say so. The class comment is corrected (it was the only place claiming the two audiences combine), the `for_context` and pricing-resolver comments read "or failing that" rather than "then", and the fallback carries an inline note. The dashboard states the precedence where a merchant can act on it: help text under the audience picker when a customer group is chosen, and a standing note on the audience card and wizard step whenever a group assignment is present, pointing at the company route for tier pricing. The developer docs stop framing the three ways of reaching a buyer as combining and carry the tier recipe as a warning. Three examples in `catalog_spec.rb` lock the ruling — the group dropping out once a company catalog exists, the group still applying when none does, and the subtree union when the tier is a company assignment. What is *not* solved: nothing detects a catalog assigned only to groups whose members are all company buyers, so such a catalog is still silently unreachable; a reachability warning needs the buyer population and is a separate piece of work.+## 2026-09-03: Labels and parcels are records; the carrier axis moves onto `Spree::Delivery` in 6.0 (supersedes 2026-08-11 "multiple trackings deferred to 6.1")**Context:** A shipping label was three EasyPost-private keys in `fulfillment.metadata`, surfaced by a per-read `provider.documents` call and bought through `PATCH .../purchase_label`. Spree never knew the postage cost, could not reprint once the carrier's hosted URL expired, could not buy a second label after a refund (idempotency keyed off the metadata), and had nowhere to put a return label — the returns plan had already sent that to "the URL in `metadata`". Tracking lived in seven columns on `spree_fulfillments`, one number per parcel, with a `spree_fulfillment_trackings` model deferred to 6.1 and required to absorb the whole axis when it came. Both were candidates for "promote to a model with RESTful routes"; only one of them is a thing.diff --git a/packages/dashboard/src/components/spree/catalog-audience.tsx b/packages/dashboard/src/components/spree/catalog-audience.tsxindex 841420e35b..de91fa1867 100644--- a/packages/dashboard/src/components/spree/catalog-audience.tsx+++ b/packages/dashboard/src/components/spree/catalog-audience.tsx@@ -160,6 +160,21 @@ function AudienceList({)}+function AudiencePrecedenceNote({ assignments }: { assignments: AssignmentEntry[] }) {+ const { t } = useTranslation()+ const hasGroup = assignments.some(+ (entry) => !entry.removed && entry.assignable_type === 'customer_group',+ )++ if (!hasGroup) return null++ return (+ <p className="text-muted-foreground text-sm">+ {t('admin.catalogs.assignments.customer_group_precedence')}+ </p>+ )+}+function AudienceEmpty({ canEdit, onAssign }: { canEdit: boolean; onAssign: () => void }) {const { t } = useTranslation()@@ -202,7 +217,10 @@ export function CatalogAudienceStep({{assignments.length === 0 ? (<AudienceEmpty canEdit onAssign={() => setAssigning(true)} />) : (- <AudienceList assignments={assignments} canEdit onRemove={remove} onRestore={restore} />+ <>+ <AudienceList assignments={assignments} canEdit onRemove={remove} onRestore={restore} />+ <AudiencePrecedenceNote assignments={assignments} />+ </>)}{assigning && (@@ -256,12 +274,15 @@ export function CatalogAudienceCard({{assignments.length === 0 ? (<AudienceEmpty canEdit={canEdit} onAssign={() => setAssigning(true)} />) : (- <AudienceList- assignments={assignments}- canEdit={canEdit}- onRemove={remove}- onRestore={restore}- />+ <div className="flex flex-col gap-3">+ <AudienceList+ assignments={assignments}+ canEdit={canEdit}+ onRemove={remove}+ onRestore={restore}+ />+ <AudiencePrecedenceNote assignments={assignments} />+ </div>)}</CardContent>@@ -380,11 +401,11 @@ function AssignCatalogForm({/>)}{duplicate && <FieldError>{t('admin.catalogs.assignments.already_assigned')}</FieldError>}- {assignableType === 'company' && (- <FieldDescription>- {t('admin.catalogs.assignments.company_subtree_help')}- </FieldDescription>- )}+ <FieldDescription>+ {assignableType === 'company'+ ? t('admin.catalogs.assignments.company_subtree_help')+ : t('admin.catalogs.assignments.customer_group_help')}+ </FieldDescription></Field></FieldGroup>diff --git a/packages/dashboard/src/locales/ar.json b/packages/dashboard/src/locales/ar.jsonindex d742112c87..a75fa38c82 100644--- a/packages/dashboard/src/locales/ar.json+++ b/packages/dashboard/src/locales/ar.json@@ -110,6 +110,8 @@"audience_label": "الجمهور","audience_placeholder": "بحث…","company_subtree_help": "تعيين شركة يشمل كامل شجرتها الفرعية.",+ "customer_group_help": "كتالوجات مجموعات العملاء تصل فقط إلى المشترين الذين لا تملك شركتهم كتالوجًا خاصًا بها.",+ "customer_group_precedence": "تعيينات الشركات لها الأسبقية. إذا كانت شركة المشتري — أو شركة أعلى منها — تملك أي كتالوج، فهذه الكتالوجات هي التي تُطبَّق، ولا تُؤخذ مجموعة العملاء في الحسبان. لمنح مشتري الشركات أسعارًا متدرجة، عيِّن هذا الكتالوج إلى شركاتهم أو أقسامها بدلاً من ذلك.","dialog_description": "من يرى هذا الكتالوج. تعيين شركة يشمل العقدة وكل ما تحتها.","empty": "غير معين لأي جمهور — لا أحد يرى هذا الكتالوج.","empty_description": "عيّن شركة أو مجموعة عملاء لتحديد الجمهور المقصود بهذا الكتالوج.",diff --git a/packages/dashboard/src/locales/de.json b/packages/dashboard/src/locales/de.jsonindex 274b1682b8..3e75a4dbff 100644--- a/packages/dashboard/src/locales/de.json+++ b/packages/dashboard/src/locales/de.json@@ -110,6 +110,8 @@"audience_label": "Zielgruppe","audience_placeholder": "Suchen…","company_subtree_help": "Die Zuweisung an ein Unternehmen gilt für dessen gesamten Teilbaum.",+ "customer_group_help": "Kundengruppen-Kataloge erreichen nur Käufer, deren Unternehmen keinen eigenen Katalog hat.",+ "customer_group_precedence": "Unternehmens-Zuweisungen haben Vorrang. Hat das Unternehmen eines Käufers — oder ein übergeordnetes — irgendeinen Katalog, gelten diese Kataloge, und seine Kundengruppe wird nicht berücksichtigt. Um Unternehmens-Käufern Staffelpreise zu geben, weisen Sie diesen Katalog stattdessen ihren Unternehmen oder Abteilungen zu.","dialog_description": "Wer diesen Katalog sieht. Eine Unternehmens-Zuweisung gilt für den Knoten und alles darunter.","empty": "Noch keiner Zielgruppe zugewiesen — niemand sieht diesen Katalog.","empty_description": "Weisen Sie ein Unternehmen oder eine Kundengruppe zu, um festzulegen, für wen dieser Katalog gilt.",diff --git a/packages/dashboard/src/locales/en.json b/packages/dashboard/src/locales/en.jsonindex 3ecf78e361..861a8ae96f 100644--- a/packages/dashboard/src/locales/en.json+++ b/packages/dashboard/src/locales/en.json@@ -110,6 +110,8 @@"audience_label": "Audience","audience_placeholder": "Search…","company_subtree_help": "Assigning to a company covers its whole subtree.",+ "customer_group_help": "Customer group catalogs reach only buyers whose company has no catalog of its own.",+ "customer_group_precedence": "Company assignments win. A buyer whose company — or one above it — has any catalog gets those catalogs, and their customer group is not consulted. To give company buyers tier pricing, assign this catalog to their companies or divisions instead.","dialog_description": "Who sees this catalog. A company assignment covers the node and everything below it.","empty": "Not assigned to any audience yet — nobody sees this catalog.","empty_description": "Assign a company or customer group to decide who this catalog is for.",diff --git a/packages/dashboard/src/locales/fr.json b/packages/dashboard/src/locales/fr.jsonindex 083a895d81..24842371ef 100644--- a/packages/dashboard/src/locales/fr.json+++ b/packages/dashboard/src/locales/fr.json@@ -110,6 +110,8 @@"audience_label": "Audience","audience_placeholder": "Rechercher…","company_subtree_help": "L’affectation à une entreprise couvre tout son sous-arbre.",+ "customer_group_help": "Les catalogues affectés à un groupe de clients ne touchent que les acheteurs dont l’entreprise n’a pas de catalogue propre.",+ "customer_group_precedence": "Les affectations à une entreprise l’emportent. Si l’entreprise d’un acheteur — ou une entreprise au-dessus — possède un catalogue, ce sont ces catalogues qui s’appliquent, et son groupe de clients n’est pas consulté. Pour donner des tarifs par palier aux acheteurs d’entreprise, affectez plutôt ce catalogue à leurs entreprises ou à leurs divisions.","dialog_description": "Qui voit ce catalogue. Une affectation à une entreprise couvre le nœud et tout ce qui se trouve en dessous.","empty": "Affecté à aucune audience — personne ne voit ce catalogue.","empty_description": "Assignez une entreprise ou un groupe de clients pour définir à qui s’adresse ce catalogue.",diff --git a/packages/dashboard/src/locales/pl.json b/packages/dashboard/src/locales/pl.jsonindex de295f1077..a39c24cf6e 100644--- a/packages/dashboard/src/locales/pl.json+++ b/packages/dashboard/src/locales/pl.json@@ -112,6 +112,8 @@"audience_label": "Odbiorca","audience_placeholder": "Szukaj…","company_subtree_help": "Przypisanie do firmy obejmuje całe jej poddrzewo.",+ "customer_group_help": "Katalogi przypisane do grupy klientów obejmują tylko kupujących, których firma nie ma własnego katalogu.",+ "customer_group_precedence": "Przypisania do firmy mają pierwszeństwo. Jeśli firma kupującego — lub firma nad nią — ma jakikolwiek katalog, obowiązują te katalogi, a grupa klientów nie jest brana pod uwagę. Aby dać kupującym firmowym ceny progowe, przypisz ten katalog do ich firm lub oddziałów.","dialog_description": "Kto widzi ten katalog. Przypisanie do firmy obejmuje węzeł i wszystko poniżej.","empty": "Nie przypisano do żadnego odbiorcy — nikt nie widzi tego katalogu.","empty_description": "Przypisz firmę lub grupę klientów, aby określić, dla kogo jest ten katalog.",diff --git a/packages/dashboard/src/locales/zh-CN.json b/packages/dashboard/src/locales/zh-CN.jsonindex 8c66425411..e5d41363bb 100644--- a/packages/dashboard/src/locales/zh-CN.json+++ b/packages/dashboard/src/locales/zh-CN.json@@ -110,6 +110,8 @@"audience_label": "受众","audience_placeholder": "搜索…","company_subtree_help": "分配给公司将覆盖其整个子树。",+ "customer_group_help": "分配给客户组的目录只对所属公司没有自己目录的买家生效。",+ "customer_group_precedence": "公司分配优先。如果买家所属公司(或其上级公司)有任何目录,则以这些目录为准,其客户组不会被考虑。若要为公司买家设置分级价格,请将该目录改为分配给他们的公司或下属单位。","dialog_description": "谁能看到该目录。分配给公司将覆盖该节点及其下所有单位。","empty": "尚未分配给任何受众——没有人能看到该目录。","empty_description": "指定公司或客户组,以决定本目录面向谁。",diff --git a/spree/core/app/models/spree/catalog.rb b/spree/core/app/models/spree/catalog.rbindex 96a5bcad5d..86c4c99b7a 100644--- a/spree/core/app/models/spree/catalog.rb+++ b/spree/core/app/models/spree/catalog.rb@@ -3,10 +3,19 @@ module Spree# specific audience — a B2B tier, a VIP group, a regional selection.## Who sees it is a {Spree::CatalogAssignment} (CustomerGroup or Company —- # where it covers the node's subtree). Visibility- # across several applicable catalogs is their union; pricing takes the- # attached price list of the nearest assignment first- # (docs/plans/6.0-b2b-companies-and-catalogs.md).+ # where it covers the node's subtree).+ #+ # **The two audiences do not combine.** A buyer is matched by one of them,+ # in the order {.for_context} walks: the company subtree if any of its+ # nodes carry a catalog, otherwise the customer's groups, otherwise the+ # channel's default catalog. So a company buyer never picks up their+ # customer group's catalogs — the nearer agreement answers on its own, and+ # trade tiers for company buyers are expressed by assigning the tier+ # catalog to those companies or divisions rather than to a group.+ #+ # Within whichever audience answered, visibility is the union of its+ # catalogs' assortments and pricing takes the price list of the nearest+ # assignment first (docs/plans/6.0-b2b-companies-and-catalogs.md).class Catalog < Spree.base_classhas_prefix_id :cat@@ -125,11 +134,16 @@ module Spreemap(&:catalog).select(&:active?).sort_by { |catalog| catalog.position.to_i }.uniqend- # Catalogs that apply to a buyer: the company subtree first, then the- # customer's groups, then the channel's default catalog — the one- # resolution chain both visibility ({Spree::Products::ForContext}) and- # pricing use. Pricing asks it once per request buyer via- # {Spree::Current#catalogs_for}.+ # Catalogs that apply to a buyer: the company subtree, or failing that+ # the customer's groups, or failing that the channel's default catalog —+ # the one resolution chain both visibility+ # ({Spree::Products::ForContext}) and pricing use. Pricing asks it once+ # per request buyer via {Spree::Current#catalogs_for}.+ #+ # The steps are alternatives, not layers: the first one that finds a+ # catalog answers, and the rest are not consulted. A buyer whose company+ # has an agreement is on that agreement, so their customer group's+ # catalogs are deliberately out of the picture (see the class comment).## @param store [Spree::Store, nil]# @param company [Spree::Company, nil]@@ -140,6 +154,10 @@ module Spreereturn [] if store.nil?catalogs = store.catalogs.for_company(company)+ # Only when the company axis found nothing: a buyer purchasing for a+ # company is on that company's agreement, and adding their personal+ # segment's catalogs on top would price one buyer under two agreements+ # at once.if catalogs.empty? && usergroups = user.try(:customer_groups)&.where(store_id: store.id) || []catalogs = store.catalogs.for_customer_groups(groups)diff --git a/spree/core/app/models/spree/pricing_provider/internal.rb b/spree/core/app/models/spree/pricing_provider/internal.rbindex 1c56cf2f82..1c25224ad4 100644--- a/spree/core/app/models/spree/pricing_provider/internal.rb+++ b/spree/core/app/models/spree/pricing_provider/internal.rb@@ -54,9 +54,11 @@ module Spreeend# Price lists reached through the buyer's effective catalogs, in- # catalog resolution order — company subtree first, then customer- # groups, then the channel's default catalog (the same fallback- # chain visibility uses).+ # catalog resolution order — the company subtree, or failing that the+ # customer's groups, or failing that the channel's default catalog.+ # The same chain visibility uses, and its steps are alternatives: a+ # company buyer is priced by their company's agreement and never+ # also by their customer group's ({Spree::Catalog.for_context}).## A catalog-attached list applies because the catalog applies: its# audience rules are not consulted, since the assignment alreadydiff --git a/spree/core/spec/models/spree/catalog_spec.rb b/spree/core/spec/models/spree/catalog_spec.rbindex c57092eb28..d7ad398e95 100644--- a/spree/core/spec/models/spree/catalog_spec.rb+++ b/spree/core/spec/models/spree/catalog_spec.rb@@ -131,6 +131,51 @@ describe Spree::Catalog, type: :model doexpect(described_class.for_context(store: store, channel: channel)).to eq([catalog])end++ # The audiences are alternatives, not layers: a buyer purchasing+ # for a company is on that company's agreement alone. Merchants express+ # trade tiers by assigning the tier catalog to the companies in it.+ describe 'company and customer group together' do+ let(:division) { create(:company, store: store, kind: 'division', parent: company) }+ let(:group) { create(:customer_group, store: store) }+ let(:buyer) { create(:customer) }++ let!(:company_catalog) do+ create(:catalog, store: store).tap do |catalog|+ create(:catalog_assignment, catalog: catalog, assignable: company)+ end+ end++ let!(:group_catalog) do+ create(:catalog, store: store).tap do |catalog|+ create(:catalog_assignment, catalog: catalog, assignable: group)+ end+ end++ before do+ Spree::CompanyMembership.create!(company: division, customer: buyer)+ Spree::CustomerGroupUser.create!(customer_group: group, customer: buyer)+ end++ it 'leaves the group out once the company subtree carries a catalog' do+ expect(described_class.for_context(store: store, company: division, user: buyer)).+ to eq([company_catalog])+ end++ it 'consults the group when no company catalog applies' do+ company_catalog.catalog_assignments.destroy_all++ expect(described_class.for_context(store: store, company: division, user: buyer)).+ to eq([group_catalog])+ end++ it 'unions the subtree, nearest node first, when the tier is a company assignment' do+ create(:catalog_assignment, catalog: group_catalog, assignable: division)++ expect(described_class.for_context(store: store, company: division, user: buyer)).+ to eq([group_catalog, company_catalog])+ end+ endenddescribe 'assignments' do