Skip to main content

Attributes

An Attribute is a single named property that can be attached to a Product — color, gear_ratio, material, weight. Attributes are the lower-level primitive consumed by everything that decorates a product: the storefront filter sidebar, the PDP "Parametry produktu" tab, the Compare page, the Promotion Rule editor, the search index, and the configurable-product variant picker.

Attributes are grouped into Attribute Sets which are then pinned to a Product so the admin editor renders just the fields that family actually needs. This page covers the attribute itself; the set ↔ product wiring lives on the Attribute sets page.

Anatomy​

Every attribute carries:

FieldPurpose
keyStable, URL-safe identifier — ^[a-z][a-z0-9_]*$, unique platform-wide (case-insensitive). Used in filter URLs, search payloads, and the product JSONB key.
labelRecord<bcp47-tag, string> per-locale label map.
labelDefaultFallback label used when the active storefront / admin locale is missing from label.
valueTypeOne of string, number, boolean, price, date, select, multiselect, enum, page_builder.
options[]Ordered list of selectable options — only for select / multiselect / enum. See Option lists below.
adminAccessAdmin access: edit (Editable, the default), read (Read-only) or hidden (Hidden), stored on the attribute's custom-field definition and answered on every attribute response. It only changes the admin panel: it does not restrict the API, filters, exports or the audit log. A required attribute must stay edit — anything else is refused with 400 VALIDATION_FAILED, and the attribute editor keeps Read-only and Hidden unavailable while the attribute is required.

Plus the behavioural flags and a numeric position:

FlagDefaultConsumed by
isFilterablefalseStorefront filter sidebar
isSearchablefalseSearch indexer (Meilisearch)
isComparablefalseStorefront Compare page
isVariantAxisfalseConfigurable-product variant picker
isRequiredfalseProduct-save validator (only when the attribute is in the assigned Attribute Set)
isPromoRulefalsePromotion Rule criterion picker
isPriceRulefalsePrice books (the price_lists module) — shown as Price list rules: whether a price book may price products by this attribute's value, on an attribute value line or a category and attribute value line. Only a single-choice, multiple-choice or yes/no attribute that is neither per-language nor per-channel qualifies. A variant matches on its own axis values, overlaid on its product's values. Clearing the flag deactivates the lines that use the attribute — they stop affecting prices, the price grid shows them as Inactive, and they resume when the flag is set again; it never causes a pricing error.
isVisibleOnProductPagefalsePDP "Parametry produktu" tab
displayAsSliderfalseStorefront sidebar — renders a range slider; only valid for valueType ∈ ('number','price')
filterPosition0Storefront sidebar sort key (ascending; ties broken alphabetically by the resolved label)

Value types​

TypeStorageNotes
stringstringFree-text.
numbernumberNumeric; supports displayAsSlider for range filters.
booleanbooleanTwo-state.
pricenumberMoney amount — formatted in the active currency / locale. Supports displayAsSlider.
dateISO 8601 date string
selectoption valueSingle choice from options[]. At most one option may carry isDefault = true.
multiselectarray of option valuesMultiple choices from options[]. Any number of options may carry isDefault = true.
enumoption valueSame storage shape as select; renders as a compact pill / segmented control on storefront filters and the PDP rather than a dropdown.
page_builderone Page Builder document per language, stored apart from attribute_valuesPage Builder content — see Product content.

Changing valueType while any product holds a value for the attribute is refused with 409 ATTRIBUTE_VALUE_TYPE_LOCKED; clear the values first.

Page Builder content​

A page_builder attribute holds a Page Builder document per language for each product, authored on its own screen and shown in the product page's description tab (Product content). Its settings are fixed:

  • its languages are those of its documents, so it is never scopable: it has no value per sales channel or per channel language;
  • isSearchable, isFilterable, isVariantAxis, displayAsSlider, isComparable, quickSearchable, isPromoRule, isPriceRule, massEditable, isRequired, isVisibleOnProductPage and scopable stay false. Setting any of them is refused and nothing is stored: on create with 400 VALIDATION_FAILED, one detail per setting; on update, where the stored type refuses it, with 400 CONTENT_ATTRIBUTE_CAPABILITY_LOCKED;
  • it has no options;
  • its type cannot be changed, and no attribute can be changed into it (409 ATTRIBUTE_VALUE_TYPE_LOCKED, token page_builder).

The attribute editor hides those settings for this type, and the list shows the row's flags locked. The type is admissible for products only.

Option lists​

For select / multiselect / enum attributes the option list is authored inline on the attribute editor. Each option carries:

FieldPurpose
valueStable identifier — ^[a-z0-9_-]{1,200}$, unique within the attribute. Encoded into filter URLs and stored on every product that carries that value.
labelRecord<bcp47-tag, string> per-locale label map.
labelDefaultFallback label when the active locale is missing from label.
isDefaultOptional pre-selection on new products. select / enum allow at most one; multiselect allows any number.
sortOrderRender order; ties broken by value ASC.

Option values are immutable while any product still carries them — the operator must migrate dependent values first. Option labels can always be renamed. Deleting an option is refused with 409 ATTRIBUTE_OPTION_IN_USE while any product still carries that value.

Public surface​

Admin routes are gated by catalog:read (list / get) / catalog:write (mutations).

Verb + PathAudiencePurpose
GET /api/v1/admin/catalog/attributesadminList attributes
GET /api/v1/admin/catalog/attributes/by-flag?flag=isPromoRule|isComparable|...adminPicker payload — every attribute carrying the requested flag
GET /api/v1/admin/catalog/attributes/:idOrKeyadminSingle attribute read
POST /api/v1/admin/catalog/attributesadminCreate attribute (accepts the flags, adminAccess + inline options[] for select-style types)
PATCH /api/v1/admin/catalog/attributes/:keyadminUpdate labels and hot-toggle isFilterable / isSearchable / isVariantAxis / isPromoRule / isPriceRule / isComparable / isVisibleOnProductPage / isRequired / filterPosition. Re-emits attribute.updated.v1.
GET /api/v1/admin/catalog/attributes/:idOrKey/usageadmin (catalog:read)What deleting the attribute would meet: { attributeSetCount, productValueCount, productContentCount } — see Deleting an attribute
DELETE /api/v1/admin/catalog/attributes/:idOrKeyadmin (catalog:write)Delete an attribute of any type; refused with 409 while an Attribute Set contains it or a product holds a value for it — see Deleting an attribute
GET /api/v1/admin/catalog/attributes/:idOrKey/optionsadminList option rows for select / enum / multiselect attributes
POST /api/v1/admin/catalog/attributes/:idOrKey/optionsadminAppend an option
PATCH /api/v1/admin/catalog/attributes/:attributeId/options/:optionIdadminPatch label / labelDefault / isDefault / sortOrder (option value is immutable)
DELETE /api/v1/admin/catalog/attributes/:attributeId/options/:optionIdadminRemove; refused with 409 ATTRIBUTE_OPTION_IN_USE while any product still carries the value

Filter sidebar reads consume GET /api/v1/catalog/filters (defined on the Catalog page) — that endpoint resolves the currently visible filterable attributes per Sales Channel and orders them by filterPosition.

Deleting an attribute​

Delete is offered on every attribute row, whatever its type. The confirmation first reads GET …/attributes/:idOrKey/usage and says what stands in the way and what goes with the attribute:

CountMeaningEffect
attributeSetCountAttribute Sets that contain the attributeRefuses: remove it from them first
productValueCountProducts that hold a value for the key — on the product, as a per-sales-channel override, or on a variantRefuses: clear the values first
productContentCountProducts that carry content for a page_builder attributeThe content is deleted with the attribute

A deleted product does not count, and does not block the delete. The dialog and the delete use the same query, so a refusal can only come from a change made after the dialog opened; the dialog then shows the API's message.

The delete removes the attribute's definition, its options, its content and its catalogue settings in one transaction, with one audit entry (catalog.attribute.delete, whose before-state counts the content removed). It then emits attribute.updated.v1 with the key and both isSearchable and isFilterable set to false, so the search index and price lists stop using the key.

Promotion conditions, price-list rows and feed rules that use the attribute are neither refused nor deleted — the catalogue cannot see them. They stop matching products: a promotion condition on the key no longer matches a cart line, a price-list row on it shows as inactive, and a feed whose selection rule names it records a configuration error on its next run. The confirmation says so in one sentence. Fix or remove them in their own screens.

Behaviour change (feature 172). A per-sales-channel override or a variant value now refuses the delete, as a value on the product always did; a value on a deleted product no longer does; and the delete now emits attribute.updated.v1.

Errors​

Each refusal the stored attribute or its options make has its own code and a sentence in English and Polish that names the values in details. Until issue #624 (and issue #1218 for Page Builder content attributes) they were VALIDATION_FAILED with an English message or a machine token (option_in_use: …). A malformed request — a key that does not match ^[a-z][a-z0-9_]*$, an option value that does not match its pattern, options, a slider or a content attribute's locked setting on a type the same request names — stays 400 VALIDATION_FAILED.

CodeStatusWhendetails
ATTRIBUTE_KEY_TAKEN409Another attribute already has the keyattributeKey
ATTRIBUTE_VALUE_TYPE_LOCKED409The value type is changed while products hold values for the attribute; token page_builder: changed to or from Page Builder contentattributeKey
ATTRIBUTE_IN_USE409Delete blocked: an attribute set contains the attribute (token attribute_sets), or products hold its values (token products)attributeKey, attributeSetCount or productCount
ATTRIBUTE_OPTION_VALUE_TAKEN409The attribute already has an option with the valueattributeKey, value
ATTRIBUTE_DEFAULT_OPTION_TAKEN409A second default option on a single-choice attribute, on create or when an option is made the defaultattributeKey, value
ATTRIBUTE_OPTIONS_NOT_SUPPORTED400An option is written to an attribute whose type takes noneattributeKey, valueType
ATTRIBUTE_OPTION_IN_USE409Delete blocked: products carry the option (token products with the count)attributeKey, value, productCount
ATTRIBUTE_SLIDER_NOT_SUPPORTED400displayAsSlider is turned on for an attribute whose stored type is not a number or a priceattributeKey, valueType
CONTENT_ATTRIBUTE_CAPABILITY_LOCKED400An update switches on a setting a Page Builder content attribute holds offattributeKey, capabilities (joined)
NOT_FOUND404:idOrKey or :optionId missing—

Storefront integration​

Filter sidebar​

Category and search pages render a chip per isFilterable attribute that has at least one value across the currently visible products. Chips appear ordered by filterPosition ascending, ties broken alphabetically by the resolved per-locale label. Attributes with no values across the current page are omitted (no empty filter).

PDP "Parametry produktu" tab​

The PDP's Parametry produktu tab lists every attribute meeting both:

  • the product has a value for the attribute, and
  • the attribute is flagged isVisibleOnProductPage = true.

Each row shows the attribute's label and its rendered value — never a technical key or a raw stored value. An attribute not flagged visible is never shown, and the tab itself is shown only when at least one attribute qualifies. Page Builder content never appears in it.

For select / multiselect / enum values the tab renders the option's per-locale label, not the raw value. The detail payload field is assembled by CatalogQueryService.buildVisibleAttributesProjection().

Search index​

Toggling isSearchable propagates into the Meilisearch indexer's payload on the next refresh cycle. Textual types (string, plus the option labels of select / multiselect / enum) feed the lexical and (when enabled) semantic index; numeric / boolean / price / date types feed range / exact-match filters.

Compare page​

Comparison rows on the storefront Compare page list every attribute flagged isComparable = true for which at least one product in the comparison carries a value. The list is sourced via CatalogQueryService.comparableAttributeKeys().

Variant picker​

Configurable products expose a variant picker whose axes come from the attributes flagged isVariantAxis = true on the product's currently assigned Attribute Set.

Storage​

Since migration 20260723T230401_catalog_attributes_on_custom_fields.ts an attribute is split between the generic Custom Fields layer that the custom_fields module owns and a catalog-owned extension row. The API shape above is unchanged — the admin surface composes the two back into the legacy form.

custom_field_definitions (owned by custom_fields, rows with entity_type = 'product'):

  • id uuid PK, key (unique per entity type), label jsonb, label_default, value_type (generic six-type set: text | number | boolean | date | select | multiselect), required, sort_order. The legacy eight-value valueType form is derived bijectively from the generic type plus the extension refinements below (enum = select + select_display='pill', price = number + numeric_kind='price', ...).

custom_field_options (owned by custom_fields):

  • Option rows keyed UNIQUE (definition_id, value) with per-locale label, label_default, is_default, sort_order. The catalog-owned attribute_options table (migration 20260505T060113_catalog_attribute_options_and_flags.ts) was dropped by migration 20260723T230401_catalog_attributes_on_custom_fields.ts after its rows moved here.

product_attributes (owned by catalog) — the 1:1 extension:

  • id uuid PK (stable — admin API attribute ids survived the migration), custom_field_definition_id uuid NOT NULL UNIQUE FK → custom_field_definitions.id ON DELETE RESTRICT.
  • Boolean flags: is_searchable, is_filterable, is_variant_axis, is_comparable, quick_searchable, is_promo_rule, is_price_rule, is_visible_on_product_page, display_as_slider, scopable, mass_editable.
  • filter_position int NOT NULL DEFAULT 0.
  • Presentation refinements: select_display varchar(16) NULL (pill = legacy enum, dropdown = legacy select) and numeric_kind varchar(8) NULL (number | price).
  • The duplicated definition columns (key, label, label_default, value_type, is_required) were dropped by migration 20260723T230401_catalog_attributes_on_custom_fields.ts — the definition row is the single source of truth for them.

products.attribute_values jsonb carries the per-product map keyed by attribute key; the values themselves have never moved out of it. Values are retained server-side even when the attribute leaves the product's currently assigned Attribute Set — switching back surfaces them again.

All attribute and option mutations flow through the catalog Commands behind /catalog/attributes — the generic Custom Fields admin surface lists product definitions read-only and refuses mutations with 409 CUSTOM_FIELD_HOST_MANAGED.

Events emitted​

  • attribute.updated.v1 — on create, update and delete; picked up by the search indexer and bridged to webhook subscribers.

Audit log​

Attribute and option CRUD writes one AuditLogEntry per mutation with stateBefore and stateAfter so the audit page surfaces who flipped which flag.

Cross-module consumers​

Three methods on CatalogQueryService are the documented service ports other modules call — a module never reaches into catalog internals:

  • comparableAttributeKeys(): string[] — the storefront Compare page.
  • promoRuleAttributeKeys(): string[] + getAttributeWithOptions(key) — the Promotion Rule criterion picker and resolver.
  • buildVisibleAttributesProjection() — internal, used by the PDP detail response to assemble the visibleAttributes[] payload.

isPriceRule has no method of its own. price_lists reads it through the catalogAttributeReadPort — listByFlag('isPriceRule') for the attributes a price-book line may name, and isPriceRule on every attribute view to refuse one that may not — once per pricing batch, so a flag change takes effect on the next resolution; an attribute.updated.v1 event also clears the pricing caches and marks on the price surface the products that price-book rows naming the attribute select. The price-book editor's picker is GET /api/v1/admin/price-books/targets/attributes, which lists only the eligible attributes with their option values.

See also​

  • Attribute Sets — bundling attributes into per-family schemas pinned to a Product.
  • Catalog — the parent module, including the storefront GET /api/v1/catalog/filters endpoint that consumes filterPosition.
  • The search module's Meilisearch indexer, which consumes the isSearchable flag.
  • The promotions module's Promotion Rule editor, which consumes the isPromoRule flag.