Catalog (catalog)
The product catalog: Products, ProductVariants, Categories, ProductAttributes, and the products' per-Sales-Channel scopes (the Sales Channel itself is the platform's). Owns all read paths the storefront depends on and the admin-side authoring surface.
Public surface
Admin routes are gated by catalog:read (list / get) /
catalog:write (mutations).
The storefront reads that carry a price — the product list, the product detail and
/products/:idOrSlug/links — accept ?currency= (an ISO 4217 code). The response is priced in
that currency when the Sales Channel offers it, and in the channel's default currency
otherwise; every price names its currency either way. A malformed code is refused with
400 VALIDATION_FAILED.
| Verb + Path | Audience | Purpose |
|---|---|---|
GET /api/v1/catalog/products | storefront / API key | List/search/filter products in the active Sales Channel |
GET /api/v1/catalog/products/:idOrSlug | storefront | Product detail (no amount where the viewer's price display mode is None); ?include=content adds the product's Page Builder content (Product content) |
GET /api/v1/catalog/categories | storefront | Nested category tree |
GET /api/v1/catalog/categories/:id/content | storefront | One category's page content, resolved to the caller's language |
GET /api/v1/catalog/filters | storefront | Filterable attributes for the active Sales Channel |
GET /api/v1/catalog/sitemap.xml | crawlers | SEO sitemap |
GET /api/v1/admin/catalog/products?status&archived | admin | Admin product list. status is active or inactive (any other value: 400 VALIDATION_FAILED); archived is exclude (default), include or only — the legacy includeArchived=1 means include. counts is { all, active, inactive, archived } — see Product status and archiving |
GET /api/v1/admin/catalog/products/:id | admin | Product detail |
POST /api/v1/admin/catalog/products | admin | Create product (type immutable post-create; sku is editable) |
PATCH /api/v1/admin/catalog/products/:id | admin | Update (incl. sku); writes an audit row with stateBefore / stateAfter; refuses with 409 SKU_ALREADY_EXISTS (token held_by_product or held_by_variant, details.sku) if the new SKU already belongs to another product or a variant |
DELETE /api/v1/admin/catalog/products/:id | admin | Delete (soft) — not the Archive action; frees the SKUs of the product and its variants (below) |
POST /api/v1/admin/catalog/products/:id/archive | admin (catalog:write) | Archive one product — see Product status and archiving |
POST /api/v1/admin/catalog/products/:id/restore | admin (catalog:write) | Restore one archived product |
GET, POST /api/v1/admin/catalog/products/list-views; PATCH, DELETE …/list-views/:id | admin | Saved views on the product list — see Saved views below |
GET /api/v1/admin/catalog/bulk-operations, GET …/bulk-operations/:id | admin (catalog:read) | The background bulk operations and one operation's per-product outcome |
POST /api/v1/admin/catalog/bulk-operations/:id/undo | admin (catalog:write) | Undo a finished bulk operation; refused with 409 BULK_OPERATION_RUNNING while it is pending or running, 409 BULK_OPERATION_ALREADY_REVERTED once undone and 409 BULK_OPERATION_NOT_REVERSIBLE when there is nothing to restore (until issue #501 all three were 409 VERSION_CONFLICT) |
GET /api/v1/admin/catalog/attributes | admin | List attributes |
GET /api/v1/admin/catalog/attributes/by-flag?flag=isPromoRule|isComparable|... | admin | Picker payload — every attribute carrying the requested flag |
GET /api/v1/admin/catalog/attributes/:idOrKey | admin | Single attribute read |
POST /api/v1/admin/catalog/attributes | admin | Create attribute (accepts the new flags + inline options[] for select-style types) |
PATCH /api/v1/admin/catalog/attributes/:key | admin | Hot-toggle isFilterable / isSearchable / isVariantAxis / isPromoRule / isPriceRule / isComparable / isVisibleOnProductPage / isRequired / filterPosition (re-emits attribute.updated.v1) |
GET /api/v1/admin/catalog/attributes/:idOrKey/usage | admin | What deleting the attribute would meet — set memberships, product values, product content (Attributes) |
DELETE /api/v1/admin/catalog/attributes/:idOrKey | admin | Delete an attribute of any type; refused with 409 while an Attribute Set contains it or a live product holds a value for it (on the product, per sales channel or on a variant) |
GET /api/v1/admin/catalog/attributes/:idOrKey/options | admin | List option-list rows for select/enum/multiselect attributes |
POST /api/v1/admin/catalog/attributes/:idOrKey/options | admin | Append an option |
PATCH /api/v1/admin/catalog/attributes/:attributeId/options/:optionId | admin | Patch label / labelDefault / isDefault / sortOrder (option value is immutable) |
DELETE /api/v1/admin/catalog/attributes/:attributeId/options/:optionId | admin | Remove; refused with 409 ATTRIBUTE_OPTION_IN_USE while any product still carries the value |
POST /api/v1/admin/catalog/products/:id/attribute-set-preview | admin (catalog:write) | Preview which Set's attributes will be edited / hidden when an operator switches a product's Attribute Set |
GET /api/v1/admin/catalog/categories | admin | Flat list, the UI folds into a tree |
POST /api/v1/admin/catalog/categories | admin | Create (parent must exist); a slug a sibling already holds is 409 CATEGORY_SLUG_TAKEN (details.slug, parentCategoryId), on create and on update. customFieldValues are checked against the category custom-field definitions and stored with the category; a refused value is 422 CUSTOM_FIELD_VALUE_INVALID (details entries { path, issue }) and creates nothing. A required category field is enforced on every create, also when the request sends no values |
PATCH /api/v1/admin/catalog/categories/:id | admin | Update (incl. customFieldValues, refused as on create); reparenting walks the new parent's chain to refuse cycles (409 CATEGORY_MOVE_CYCLE, details.categoryId, parentCategoryId) |
DELETE /api/v1/admin/catalog/categories/:id | admin | Soft-delete; rejects with 409 CATEGORY_HAS_CHILDREN (details.categoryId, childCount) if any active child still references the row |
GET /api/v1/admin/catalog/categories/:id/content | admin | The category's page content — one Page Builder document per language (Category page content) |
PUT /api/v1/admin/catalog/categories/:id/content | admin | Replace the category's page content; null clears it |
GET /api/v1/admin/catalog/products/:id/content | admin | The product's content attributes with a per-language summary (Product content) |
GET /api/v1/admin/catalog/products/:id/content/:attributeKey | admin | One content attribute's envelope — one Page Builder document per language |
PUT /api/v1/admin/catalog/products/:id/content/:attributeKey | admin | Replace one content attribute's envelope; null clears it |
PUT /api/v1/catalog/products/by-sku/:sku | API key | Idempotent upsert (PIM sync); an update is audited as product.update naming the key (apiKeyId) and is never checked for completeness |
Product status and archiving
A product's status is active or inactive, globally and as an override per
Sales Channel and per channel × language. inactive at any scope is plain off
there: the product is not listed, not searchable, not orderable and its page answers as
a product that does not exist. Switching a product off never archives it. New and
duplicated products start inactive. Any other status value is refused with
400 VALIDATION_FAILED — on the admin API, the API-key upsert
PUT /api/v1/catalog/products/by-sku/:sku and an import; archiving is not a status.
Archiving is a separate, product-wide action, offered as Archive and
Restore (POST …/products/:id/archive, …/restore) and gated by catalog:write.
Archive sets the product's archived time and takes it out of every channel; Restore
clears it. Neither changes the status at any scope, and each writes one audit entry
with the archived time before and after. Archiving an archived product, or restoring
one that is not archived, answers 200 and changes nothing — no audit entry, no event.
- Bulk.
POST /api/v1/admin/catalog/products/bulk-updatewithfields: { archived: true }archives every selected product,falserestores them, each through the same action and audit entry.archivedmust be the only field of its request. Large selections run as a background bulk operation, and the operation's undo puts every product back as it was. A background operation audits each product with the admin who requested it, as a direct one does. Archive and Restore lock the product, so two concurrent Archives of one product archive it once. - Setting
activenever restores. An archived product stays archived whatever its status; only Restore brings it back. Restoring aninactiveproduct leaves it off. - Products archived before this change. Until this release a product was archived by
setting it
inactive. Every productinactiveat the upgrade therefore stays archived (keeping its archived time, or its last-update time when it had none), and needs an explicit Restore to come back — setting itactivealone leaves it archived. - The product page. An archived product's page answers
410 PRODUCT_ARCHIVED("gone"), but only to a buyer who could otherwise see it there: the check takes the archive away and reads the global status asactive, while every channel and channel × language status, the membership, the channel's languages, the publication window and the audience still apply. Everywhere else, and for any product that is off without being archived, the page answers404exactly as for a product that does not exist. - The admin list. Archived products are hidden by default, whatever their status;
archived=onlylists them andarchived=includelists them beside the rest. Theinactivecount and filter cover products that are off but not archived. On the product list the Archived tab has its own address,/catalog/products/archived, so the browser's Back button and a reload return to it, and the command palette (⌘K / CTRL+K) opens it as Archived products — search for "archived" or "archiwum". With a selection, its bar offers Restore, Bulk edit and Delete; Edit price is shown on the other tabs but disabled, because prices are set in price books. - From the admin assistant. The assistant's
catalog.archive_productandcatalog.restore_producttools (catalog:write) archive and restore products after you confirm the plan it shows, through the same action and audit entry, with you as the actor; larger selections run as the bulk operation above. Its status tool,catalog.set_product_status, only switches products on or off and never archives or restores, and its product search lists archived products and says which they are.
Status per channel and language, in bulk
POST /api/v1/admin/catalog/products/bulk-update with
fields: { scopedStatus: { channelId, languageCode, value } } sets the status of every
selected product at one scope — the Sales Channel (languageCode: null) or one
channel × language — to active or inactive, or removes the override there with
inherit. Only that scope changes on each product; every other scope and the global
status stay as they were. A product that is not in the channel, or a language the
channel does not offer, is skipped and reported as scope_invalid — the product is
never added to the channel. scopedStatus cannot be combined with status in one
request. Each product's change is one audit entry naming the scope; large selections
run as a background bulk operation whose undo puts every scope back as it was and
reports any product changed since.
Completeness check when switching a product on
When an operator's status change switches a product on for a sales channel and
language — the global status, a channel or channel × language status, single or in
bulk — the product must have, at that channel and language: a non-empty effective
name (Channel × language → Channel → Global; a deliberately empty override counts
as missing), a URL key (the Global key counts) and an effective value for every
required attribute of its attribute set. The setting Completeness check when switching a
product on (catalog.scope_completeness_gate, one value for the whole platform)
decides what happens when something is missing:
warn(the default) — the change is saved and the answer lists what is missing per channel and language (warnings, kindcompleteness).refuse— the change is not saved:422 SCOPE_INCOMPLETEnames every channel and language with what it lacks. A change that would switch the product on in several places is refused as a whole if any of them fails. In a bulk edit the products that pass are changed and the others are skipped ascompleteness_gate.
Only a status change is checked. A product that goes live because it joins a channel,
a channel gains a language, its publication window opens, its audience changes, or it
is restored is not checked; the scope map of the product editor shows what is
missing at every channel and language instead. Setting an archived product active is
checked like any status change, although the product stays archived. Imports, PIM
synchronisation and the API-key upsert are never checked.
Prices
A product carries no price of its own. Every price is a row of a price book of the
price_lists module: the product's base price per currency, its variants' prices, and any
catalogue, buyer or sale price. Set a product's base price on the product editor's Pricing tab
— the Base prices panel there, and the list of the price books that price the product, are
contributed by price_lists — or in the base book's grid. Variant prices are set in the same
places, never on the variant itself. The price_lists module's page explains how the price a
buyer pays is chosen.
- Listing cards, the product page and related products show the viewer's own price — their
organization's and customer group's prices on the request's sales channel and currency. A product
whose variants cost different amounts shows its lowest price as a from price
(
ProductSummary.pricecarriesvariesByVariantandmaxAmount); a charged sale carries the buyer's regular price as the compare-at price; withpricing.show_list_priceon, a lower buyer price carries the catalogue price aslistPrice. A product nothing prices has no price and follows the quote-request path. - Sorting and filtering by price —
?sort=price,?sort=-price,minPrice,maxPriceonGET /api/v1/catalog/products— order and select by the same quantity-1 price the cards show to that viewer, the from price for a variant product. Priced products always come before unpriced ones. A price ordering is always answered from PostgreSQL, never from the search index. Paging through a price ordering with the cursor meets every product once, provided its price does not change meanwhile; a product repriced during the walk may be met twice or not at all, as with any cursor over a live price. A page may be short, or even empty, and still have more after it (hasMore: true) when most of the rows it read are hidden from the viewer; follow its cursor. The cursor of a price ordering or a price range is sealed: it cannot be read or altered, because the position it continues from can be a product the viewer may not see. A cursor that does not open — altered, issued by a release before the seal, or before the instance's session key was changed — starts the listing again at its first page. - Paging and creation time — the default ordering, and the order of the unpriced products that
follow a price ordering, is the product's creation time, newest first. It is stored to the
millisecond: a value written by SQL, such as an import's or a bulk insert's
now(), is rounded to the millisecond as it is stored. So a walk through the listing by its cursor meets every product once, including products created within the same millisecond. - Reading named products —
?ids=<id>,<id>,…onGET /api/v1/catalog/productsrestricts the listing to those products: at most 24 distinct ids, each a uuid, or400 VALIDATION_FAILED. The answer is the subset the viewer may see, priced exactly as any listing card for that viewer, in the listing's own order — a caller that cares about its order re-orders by id. It combines with the other filters and is always answered from PostgreSQL. A blog post's related products are read this way. - Where the viewer's price display mode is None — for instance an anonymous visitor on a
channel that hides prices until sign-in — the listing and the product detail carry no amount, and
a price ordering or range is refused for that page with
400 PRICE_ORDERING_UNAVAILABLE. Sales channels have no price-visibility flag of their own any more: the display mode decides, for each viewer. - Gross prices use each product's own VAT rate. Every product on the listing and the product
detail carries
vatRate, the VAT rate the viewer is charged for it, as a fraction (0.08= 8 %). It is the rate the cart and the order apply: the product's tax class (its type) against the viewer's organization — its VAT status and registered country. A VAT-exempt or reverse-charge organization gets0; an anonymous visitor, or a buyer with no organization, is treated as a VAT payer in Poland. The storefront derives every product's gross price — on the cards, the list rows and the product page — from this rate. Where a reply carries no rate (nullwhen the rate could not be read, or no field from an older backend), the storefront shows the net price, labelled net, and never a gross at an assumed rate.
For developers: the listing paths price a whole page in one batched call —
resolveListingPrices, or resolveListingPriceDetails where the page renders the split
(ProductSummary.resolvedPrice: basePrice, salePrice, listPrice, displayMode) — through the
pricingService port slices of @endora-commerce/contracts, passing the viewer's organization and
customer account rather than a resolved group. A price ordering reads ListingPriceOrderPort
(orderByUnitPrice, pricedProductIds) over price_lists' precomputed price surface and composes
the unpriced tail itself (catalog-query.service.ts). The external catalogue API prices through
resolveLinePrices and builds a bound organization's tier ladder from listTierStarts. Product,
category and attribute writes publish the events price_lists subscribes to, which clear the
pricing caches and mark on the price surface the products each event concerns, for the surface
worker to refresh.
vatRate is resolved per reply by createProductTaxRateResolver (@endora-commerce/contracts),
the rule the cart uses too, over organizations' organizationTaxProfilePort and taxes'
taxService. It depends on the viewer's organization and nothing else about the viewer, so it
follows the same cache rule as the price: a reply for a viewer naming an organization is
Cache-Control: private, no-store, and the shareable reply is the anonymous one, which carries the
guest's rate. A failed resolution answers vatRate: null on every product rather than refusing the
listing.
Removed price fields (migration note)
The release that introduced price books removed the product's Default unit price (the
defaultPrice and price keys of attributeValues, and the editor field) and the variant price
override (product_variants.price_override, and the variant editor's price field), without
converting either. Product and variant create and update, and the products import, refuse those
fields with 400 PRICE_SET_IN_PRICE_BOOKS (PRICE_FIELDS_REFUSED_ON_PRODUCTS,
PRICE_FIELDS_REFUSED_ON_VARIANTS in @endora-commerce/contracts), saying that prices are set in
price books. The catalogue's migration 20261022T111811_catalog_price_fields_removed.ts dropped the
column and stripped the keys.
Editing a category
Catalog → Categories shows the category tree; Edit on a category opens its editor beside the tree. The editor holds the category's own fields — its names, slug, parent and custom fields — and, while the Price lists module is on, the category's Price display mode, contributed by that module and shown above the Save and Cancel buttons.
The editor has one Save for all of it. Changing the price display mode only stages it: it is no longer saved the moment you choose it. Save reads "Save" while there is nothing to save and "Save 2 changes" once there is, counting the category's own changes and the display mode together.
- Save checks everything first; if anything is refused, nothing is written.
- The category is written first, then the display mode. If the category is refused — a slug already in use, an invalid custom field — the display mode is not written either.
- If the category is saved and the display mode is not, the editor stays open and a summary says what was saved and what was not. The next Save writes only the display mode.
- Cancel discards every unsaved change without asking.
- Edit on another category with unsaved changes asks first: Save and continue, Discard changes or Stay here. Following a link elsewhere in the admin, or closing or reloading the browser tab, asks too. The open category is not part of the page address, so the browser's Back button leaves the page without asking.
Entities
Product, ProductVariant, Category, ProductAttribute (the
SalesChannel entity is the platform's), plus the M:N bridges
product_categories, sales_channel_products, product_assets, and
ProductListSavedView (product_list_saved_views, the product list's saved
views).
Saved views
A saved view is a named set of product-list filters that an admin can apply again with one selection.
Using saved views
The product list's toolbar carries a Saved views selector, whose first entry is — Select a view —, and two buttons beside it: Save view and Delete view.
- What a view remembers. The status, the type and the search text — and nothing else. The Stock, Category and Channel chips are not saved. Choosing a view sets status, type and search to the view's values (a value the list no longer offers loads as All), resets the Stock chip to All, discards anything you had changed and not saved, clears the row selection and goes back to the first page.
- Saving. Save view opens one dialog with a Name field and a Share with every admin who can open this list checkbox. The checkbox starts unchecked, so a new view is private unless you tick it. The name is required, leading and trailing spaces are removed, and it can be at most 160 characters long. Problems are shown on the field and nothing is sent until they are fixed; a refusal from the server is shown inside the dialog, which stays open with what you typed.
- Private or shared. A private view is listed only for you. A shared view is listed for every admin who can open the product list, with (shared) after its name. The selector does not show who saved a shared view.
- One name per admin. You cannot hold two views on this list whose names differ only in letter case or in surrounding spaces. The dialog answers You already have a view with this name. before sending anything, and the server refuses the name as well. Accented letters are different letters: Wózki and Wozki are two names. Names other admins use, and names used on other lists, do not count.
- Deleting. Delete view is enabled only when the selected view is one you may delete. It asks for confirmation and names the view — Delete the view “…”? — and for a shared view adds that it will disappear for every admin who can open this list. Nothing is deleted until you press Delete.
- Who may delete or change a shared view. Its owner, or any admin whose
role is not
sales_representative— not only theplatform_adminrole: a custom role such as a catalog manager counts as well. Such a deletion or change leaves no audit trail: saved views are not written to the audit log. Decide which roles you grant with that in mind before your team relies on shared views. A sales representative can delete only their own views, and nobody can see or delete another admin's private view. - Only save, load and delete. The Admin UI does not rename a view, change whether it is shared, or overwrite it with the current filters; save a new view and delete the old one instead. There is no limit on the number of views.
Saved views API
| Method and path | Answers |
|---|---|
GET /api/v1/admin/catalog/products/list-views | 200 — the caller's own views plus every shared view, ordered by name |
POST /api/v1/admin/catalog/products/list-views | 201 — the created view |
PATCH /api/v1/admin/catalog/products/list-views/:id | 200 — the modified view; any of name, shared, filters. The Admin UI does not call it. A body that changes nothing — empty, or every value as stored — writes nothing, logs nothing and answers the current view |
DELETE /api/v1/admin/catalog/products/list-views/:id | 200 — { data: { deleted: <id> } } |
- Gate. All four routes are gated by
catalog:read— the code that gates reading the product list; there is no separate permission code. A request without an admin actor is refused with401 UNAUTHORIZED. The staticlist-viewssegment takes precedence overproducts/:id. - Body.
name(trimmed, 1–160 characters, no Unicode control or format characters),shared(boolean) andfilters(an object, at most 8192 bytes as UTF-8 JSON). The product list has no sort or column control, so a view stores nosortorvisibleColumns; those keys are dropped. The Admin UI writesfiltersas{ status?, type?, q? }, only the non-default ones. Anything outside those bounds is400 VALIDATION_FAILED. The shapes arecreateProductSavedViewRequestSchemaandupdateProductSavedViewRequestSchemain@endora-commerce/contracts. - Two caller-relative flags. Every view in a response carries
ownedByCallerandcanModify—truewhen the caller owns the view, or the view is shared and the caller is a platform admin in the sense below. The Admin UI enables Delete view fromcanModify, and before saving runs a best-effort duplicate-name pre-check against the listed views withownedByCaller. The server'slower(btrim(name))comparison is authoritative: a name the pre-check lets through can still be refused with409. - Platform admin, for saved views, is an admin whose request tenant context
has
mode === 'all'— every role exceptsales_representative. The order, product and quote request lists derive it the same way, and it fails closed: an admin whose reach cannot be resolved is not a platform admin. - Refusals. An absent view, or another admin's private view, is
404 NOT_FOUND— the two are indistinguishable. A shared view the caller neither owns nor may modify as a platform admin is403 FORBIDDEN. A name whose key the view's owner already uses on this list is409 PRODUCT_SAVED_VIEW_NAME_TAKEN, "You already have a saved view with this name on the product list. Choose a different name.", in the request's language. - The name key is the name trimmed and lower-cased — no accent folding. The
rule binds the view's owner: a platform admin renaming a colleague's
shared view is refused when the colleague already uses that key. Creating a
view and changing a name's key take a transaction-scoped advisory lock keyed
on the owner, and a unique index on
(owner_admin_user_id, lower(name))backs it, so two concurrent saves under one name leave exactly one view. - No audit. Saved views are personal UI configuration and do not run
through the Command Bus. When an admin modifies or deletes a view they do not
own, the service writes one
infolog record:{ event: 'saved_view.updated' | 'saved_view.deleted', list: 'product_list_saved_views', viewId, ownerAdminUserId, actorAdminUserId }. That log line is the only trace. - Storage.
product_list_saved_views(ProductListSavedView) is platform-global, not organization-scoped: it holds filter values, never list results, and every list read after a view is applied runs under the loader's own scope.
Events emitted
product.created.v1, product.updated.v1, product.archived.v1,
attribute.updated.v1. Picked up by the search indexer. The three product
events are also offered to outbound webhooks (next section);
attribute.updated.v1 is not.
category.updated.v1 and category.content.updated.v1 both flush the
storefront's category cache; the first also re-indexes the products of the
changed category's subtree.
Events offered to outbound webhooks
The module contributes three event types to the webhooks module's
webhookEventRegistry, so a webhook subscription can name them while both
modules are present. The payload is sent whole; the strict schemas are
CATALOG_WEBHOOK_EVENT_SCHEMAS in @endora-commerce/contracts.
| Event | Sent when | Payload, beside eventId and occurredAt |
|---|---|---|
product.created.v1 | A product is created — in the Admin UI, through the API-key upsert, by an import or a PIM synchronisation, or by duplicating another product. | productId (UUID), sku — the SKU it was created with; it can change later, productId cannot. |
product.updated.v1 | A product is written, or one of its variants is created, changed or deleted. | productId, changedFields — the names of the product fields whose stored value the write changed (name, status, categoryIds, …; variants for a variant write). Names only, an open list, and it may be empty. A product update that changes nothing is not announced. |
product.archived.v1 | A product is archived by the Archive action — for one product or in bulk. Once per transition: archiving an archived product sends nothing. A status change never sends it: inactive is plain off. | productId |
- Order. Archive sends
product.updated.v1(witharchivedAtinchangedFields) and thenproduct.archived.v1, for one product and for each product of a bulk Archive. - Restore has no event of its own. Restore sends
product.updated.v1witharchivedAtinchangedFieldsand nothing else. Switching a product on or off sendsproduct.updated.v1withstatus. To tell them apart, read the product: itsstatusandarchivedAtare the answer. - Undo. Undoing a bulk edit sends
product.updated.v1for every product it put back, naming the fields it restored, andproduct.archived.v1where it archives a product again. - Deletion is not delivered. Deleting a product emits
product.deleted.v1on the in-process event bus only; it is not offered to webhooks, and noproduct.archived.v1is sent for it. A receiver that mirrors the catalogue learns of a deletion by reading: the product is no longer returned by the API. Reconcile against a full listing if deletions matter to you. - After the commit. Each event is sent for a write that was committed. A write that is refused or rolled back sends nothing.
- No content leaves. No name, description, price, attribute value or Organization allow-list is in any payload. A receiver reads the product through the API with its own key.
- Platform-wide subscriptions only. A product is not one Organization's
data, so the payloads carry no
organizationIdand a subscription bound to an Organization never receives a product event. - Volume. One event per product written. A bulk edit, an import or a PIM
synchronisation writes products one by one and therefore sends one
product.updated.v1per product; nothing is batched. With no subscription naming the type, nothing is enqueued.
Extension points
- Per-Sales-Channel listing — the query service receives a SalesChannel
context, and every price it renders is resolved for that channel; new gating
(e.g. customer-segment-specific catalogs) is added by composing into
catalog-query.service.ts. - Product editor zones — the editor mounts admin zones other modules contribute to;
product.editor.seo.after, at the end of the SEO tab (props:productId), is where the SEO module puts its link to the meta-tag editor, so the catalog never names that module. - Slug uniqueness — the slug is unique across all Sales Channels by
default; override the slugifier in
catalog-admin.service.tsif locale collisions become a concern.
Order rules: minimum order quantity and returnable
Two rules on a product decide how it may be ordered and whether it may be sent back. Both are edited in the Order rules card on the product editor's Inventory tab.
Upgrading: every existing product starts as not returnable. A product on which nobody has set Returnable reads as not returnable, and that includes every product that existed before the setting was introduced. Lines of orders placed after the upgrade are therefore not returnable until you mark their products. To mark many at once, select them on the product list and use Bulk edit → Returnable → Yes — returnable. Orders placed before the upgrade are unaffected: their lines stay returnable under the usual rules.
Minimum order quantity
- Minimum order quantity (pcs) — the fewest pieces of the product a buyer
may order in one order. Optional; a whole number from 1 to 1 000 000, or
empty for no minimum. It applies to
simpleandconfigurableproducts only: on agrouped,bundleorvirtualproduct the card says so, and the API refuses the field with422 MIN_ORDER_QUANTITY_NOT_SUPPORTED_FOR_TYPEnamingminOrderQuantity(details.field,productType), on create, on update and per channel. A value outside the range is refused with400 VALIDATION_FAILED. - A minimum per packaging unit — each packaging unit may carry its own minimum number of units; see Packaging Units.
The minimum is judged on the product total: every line of the product in the basket counts — single-piece and packaging-unit lines, every variant. A packaging-unit minimum counts the units of that unit ordered for the product, over every variant. The two checks are independent; a basket must satisfy every minimum that is set. Variants inherit the product's minimum.
Every way into a basket, a quote request or an order applies it — the cart,
checkout, quick order, one-click buy, shopping lists, quote requests, the
admin's Create order screen and the external order API. Each of those modules'
pages says what its path does with a line below the minimum. A refusal answers
422 PRODUCT_BELOW_MINIMUM_QUANTITY (pieces) or
422 PACKAGING_UNIT_BELOW_MINIMUM_QUANTITY (a packaging unit), with a message
in the buyer's language naming the product and the minimum. Removing a line is
always allowed.
A product a buyer may not see, or that the request's sales channel does not publish, is reported as an unknown product on every path — its name and its minimum are never disclosed.
The storefront product detail, the product list, search results and the
comparison carry minOrderQuantity (null when there is none, or when the
product's type takes no minimum); the product detail's packagingUnits[]
carries each unit's minOrderUnits. The storefront starts the quantity at the
minimum and does not offer less.
Returnable
Returnable (yes / no, on every product type) says whether buyers may include the product in a return. It does not restrict complaints. The default is no.
The value is recorded on each order line when the order is placed
(order_items.returnable_at_purchase); changing the flag later changes no
order already placed. A line whose product could not be read at placement is
recorded as not returnable. What the Returns module does with the recorded
value is on its own page.
Per sales channel
Both rules can be overridden for one sales channel — Order rules per channel in the
product's scopes — in the product editor at a channel, or through
PUT /api/v1/admin/catalog/products/:id/scoped-values (minOrderQuantity, returnable) or
PATCH /api/v1/admin/catalog/products/:id/scopes for API clients. { "inherit": true } uses
the Global value again; null on the minimum stores "no minimum" for that channel. The channel's value
applies wherever a basket, an order or a quote request belongs to that channel: adding to
the basket, the basket view, submitting for approval, the checkout preview, placement, the
admin order preview, quote requests and the buyer's quick-order import. A channel minimum
of 1 means no minimum in that channel, whatever the global value. Placement records the
order channel's returnable flag on each line, so returns follow the channel the order was
placed in. The storefront product detail and listing report the minimum of the request's
channel.
Audit and copies
Setting or clearing either rule is audited like any product edit, with the old and the new value. Bulk edit → Returnable writes one audit entry per product it changes, for up to 200 products in one synchronous request and through the queued bulk edit beyond. Changing a rule never alters an existing cart, order, quote request or return. Duplicate does not copy either rule: the copy starts with no minimum and as not returnable.
API
| Field | Where | Values |
|---|---|---|
minOrderQuantity | POST / PATCH /api/v1/admin/catalog/products[/:id], the admin product response | integer 1…1000000, or null to clear |
returnable | the same, and POST /api/v1/admin/catalog/products/bulk-update | boolean |
minOrderUnits | POST / PATCH …/packaging-units[/:unitId], the packaging-unit response | integer 1…1000000, or null to clear |
The catalogue read port (CatalogProductReadPort) reports minOrderQuantity
and returnable on each product record and minOrderUnits on each packaging
unit, and gains listPackagingUnitsByProductIds for batch reads. Like every
method of the port it applies no visibility policy: a caller passes only
product ids it has already vetted.
Migration 20261016T082008_catalog_order_rules.ts adds
products.min_order_quantity (nullable, CHECK 1–1 000 000),
products.returnable (not null, default false) and
product_packaging_units.min_order_units (nullable, CHECK 1–1 000 000).
Product structure and composition surfaces
The catalog grew several capability surfaces, each with its own page:
- Attribute Sets — reusable attribute schemas pinned to Products, with a system Default
- Product Gallery — image / video gallery with Base / Small / Thumbnail label invariants enforced at the database level
- Attachments — downloadable files (certificates, tech specs, ...) with a typed dictionary
- Product Links — Related, Up-sell, Cross-sell pairings driving cross-merchandising on the PDP and cart
- Composite Products —
grouped(fixed children),bundle(configurable slots),virtual(digital delivery) - Product content — Page Builder documents kept per product in content attributes and shown in the product page's description tab
Five product types are now supported: simple, configurable,
grouped, bundle, virtual. simple and configurable are the
original pair; the other three were added later.
Page Builder blocks
The catalog declares the Page Builder's product and category blocks. Their data is read on the server, so the products are in the page's HTML.
Product grid and product slider (catalog.ProductGrid,
catalog.ProductSlider) keep every option they had — the product source
(picked products, a category, a search), the limit, columns, gap and view —
and add:
| Option | Meaning |
|---|---|
| Header | An optional heading, lead text and button (for example "See all") above the products. |
| Card style | Default, compact, horizontal, or showcase: the product image on a neutral backdrop, its name, a short summary and a "more" link — no price or SKU. |
| Text under the product name | The one line under each card's name: the card style's default (the SKU on the default, compact and horizontal cards, the short description on showcase), the Short description (the first words of the product's description, at most 160 characters), the SKU, or none. The page editor's preview shows the same line as the storefront. |
| Card title weight | The weight of each card's product name: Default (the card style's own) or 300–800. |
| Card image background | The colour of the box behind each card's image: a brand colour or a hex value. Empty keeps the card style's own light grey. |
| Divider under each card | None (as before) or Line: a 1 px line under each card, in the Divider color you pick or the neutral border colour. A bordered card's bottom edge becomes the line; a showcase card gets it 16 px below its text. |
| Card link label | The text of the showcase card's link; "More" when empty. |
| Gap (grid) | A spacing step or Custom gap (px), per breakpoint. A grid saved with a gap in pixels opens on Custom with that number and looks as before. The category grid's gap works the same way. |
| Equal items height (grid) | Per breakpoint, next to the columns and the view, on the Responsive tab; a value saved before applies at every width. The category grid's works the same way. |
| Button below the products | An optional button under the grid or slider. |
The slider takes the Page Builder carousel's options: slides per view per
breakpoint, gap, slide or fade effect, arrow and dot placement, bleed to the
viewport edge and optional autoplay. A grid or slider saved before these
options existed renders as it did. To give any of these blocks an anchor, a
colour scheme, a background, spacing or a width, place it inside a Section
block (cms.Section). The header texts, the card
link label and the footer button label are translatable with the Page
Builder's Translate action.
The product summary. The storefront product list and product detail
(GET /api/v1/catalog/products, GET /api/v1/catalog/products/:idOrSlug)
return summary: the product description in the request language as plain
text, cut at a word boundary to at most 160 characters with …, or null
when the product has no description. It is derived from the description the
read already loads, so it costs no extra query per product (the module's
src/backend/services/product-summary-text.ts).
The showcase card shows it.
Attribute extensions on the Catalog read paths
The Attributes work added the operational surface the storefront needs to render rich product information and the search / promotions modules need to resolve customer queries. The dedicated Attributes page covers the attribute authoring surface in full — this section only summarises what changed on the Catalog read paths.
New attribute flags
ProductAttribute gains four behavioural flags + a numeric position +
a per-locale label fallback:
isPromoRule(boolean) — picker eligibility for the Promotion Rule editor'sattributecriterion variantisVisibleOnProductPage(boolean) — surface the attribute on the storefront PDP "Parametry produktu" tab when the product carries a valueisRequired(boolean) — enforced at product save time when the attribute is part of the product's Attribute SetfilterPosition(number) — sort key for the storefront filter sidebar (lower comes first; ties broken by label)labelDefault(string) — fallback used when the active locale has no matching key in the per-localelabelJSONB
Option lists
Select-style attribute types (select, enum, multiselect) carry an
ordered option list — each row keyed by (definition, value) with
per-locale label + fallback + sort order + default flag. The legacy
enum_values: string[] JSONB column on product_attributes was
decommissioned by migration
20260505T060113_catalog_attribute_options_and_flags.ts (into the catalog-owned
attribute_options table), and migration
20260723T230401_catalog_attributes_on_custom_fields.ts moved the
rows into the generic custom_field_options table. Existing readers
project the option list back into the legacy form for backward
compatibility at the API boundary.
Editable SKU
Product sku is mutable. The internal canonical reference for every
cross-module link (assets, links, RFQ items, ...) is the Product.id
UUID, which never changes. Updating the SKU writes an audit row and
refuses with 409 SKU_ALREADY_EXISTS if the new value already belongs to
another product or a variant — the code create answers with. The refusal
token says which (held_by_product, held_by_variant), and details carries
sku and conflictingProductId or conflictingVariantId. Until issue #624
it was 400 VALIDATION_FAILED with the token sku_in_use in the message.
A deleted product frees its SKU
Deleting a product (DELETE /api/v1/admin/catalog/products/:id) frees its
SKU and the SKUs of its variants: a new product or variant can take them at
once — in the Admin UI, through PUT /api/v1/catalog/products/by-sku/:sku
(which then creates a new product rather than updating the deleted one), or
from an import or a PIM synchronisation. Products and variants share one SKU
namespace, so a deleted variant's SKU can be reused by a product and the
other way round. This also applies to products deleted before the change.
The deleted product keeps its real SKU, so the audit log and a reconciliation with an ERP or PIM still show it, and orders, invoices and quotes keep the SKU they recorded at the time. A deletion cannot be undone, and a deleted product cannot be restored.
Every lookup by SKU addresses the live product. A product import and the CSV
stock import write the live product; on the catalogue's read port
(catalogProductReadPort), findBySku, findBySkus and findVariantsBySkus
answer the live product or variant when there is one, and otherwise the most
recently deleted one holding that SKU — at most one per SKU. Pass
{ liveOnly: true } to findBySku and findBySkus to ignore deleted
products altogether.
Attribute Set swap
When an operator assigns a different Attribute Set to a Product, the
admin form re-renders to show only the new Set's attributes. Values
for attributes outside the new Set stay in the JSONB column server-side
— switching back surfaces them again. The
attribute-set-preview endpoint lets the editor warn the operator
which fields will be hidden vs. retained before they confirm.
Cross-module read surface
Two methods on CatalogQueryService cross module boundaries (the
documented service ports):
comparableAttributeKeys(): string[]— ComparepromoRuleAttributeKeys(): string[]+getAttributeWithOptions(key)— PromotionsbuildVisibleAttributesProjection()— internal, used by the PDP detail response to assemble thevisibleAttributes[]payload
Attributes as Custom Field extensions
The attribute definition store has converged onto the generic Custom
Fields layer that the custom_fields module owns, adapter-shaped rather
than rewritten. Nothing changed on the
HTTP surface — every endpoint above keeps its shape — but the storage
and ownership model is different:
- A product attribute is a catalog extension of a product-host Custom
Field definition. The generic identity (
key, per-localelabel+labelDefault,valueType,required) lives on acustom_field_definitionsrow withentity_type = 'product'. Theproduct_attributestable remains, rebuilt as a thin 1:1 extension row (custom_field_definition_idUNIQUE FK) carrying only the catalog behaviour flags (isSearchable,isFilterable,isVariantAxis,displayAsSlider,isComparable,quickSearchable,isPromoRule,isPriceRule,filterPosition,isVisibleOnProductPage,scopable,massEditable) plus two presentation refinements (selectDisplay,numericKind) that keep the legacyenum/selectandnumber/pricedistinctions lossless. Flags stay catalog-owned — the generic core never interprets them. - Options live in
custom_field_options. The catalog-ownedattribute_optionstable is gone; option lists are ordinary Custom Field option rows on the product-host definition. - Single write surface:
/catalog/attributes. Attribute and option mutations are catalog Commands that create/update/delete the definition and the extension together in one transaction (one audit row), using the transactional apply seam exported bycustom_fields. The generic Custom Fields admin surface lists product definitions read-only and refuses mutations with409 CUSTOM_FIELD_HOST_MANAGED. - Migration
20260723T230401_catalog_attributes_on_custom_fields.tsperformed the one-time convergence in a single transaction: backfilled one definition per legacy attribute (key, labels, mapped value type, required, deterministic sort order), movedattribute_optionsrows intocustom_field_options, re-keyedattribute_set_attributesto definition ids, addedcustom_field_definition_id/select_display/numeric_kindtoproduct_attributes, dropped the duplicated columns (key,label,label_default,value_type,is_required), and droppedattribute_options. The migration is reversible (down()restores the legacy shape) and aborts loudly on a reserved-key collision. - Attribute values did not move —
products.attribute_values,product_variants.variant_attribute_values, andproduct_value_overrideskeep their shape and catalog ownership (the host owns its data).
Internal consumers (search, quick order, comparisons, bulk edit, the
promotions port, the scope editor) read attributes through the
catalog-exported CatalogAttributeReadService, which composes the
definition and the extension into the legacy-shaped
CatalogAttributeView.
Global search
The admin's global search (the command palette, ⌘K / Ctrl+K) finds products and categories. This module offers the fields below; which of them are used is chosen on the Global search configuration screen.
| Field | Searched by default |
|---|---|
| Product: SKU | yes |
| Product: Name | yes |
| Product: URL key (slug) | no |
| Product: Quick-search attributes | no |
| Category: Name | yes |
| Category: URL key (slug) | yes |
Names match in every language and are shown in the admin's language. Inactive and archived products are found and show their status; deleted products and categories are not. A category result opens the category tree with that category highlighted. Both appear for a role holding catalog:read.