--- id: CON-COM-CAT-003 name: Catalog Product feature: FEAT-COM-CAT-02 product_area: commerce module: catalog revision: 1 status: draft product_intent: confirmed implementation_evidence: partially-observed source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f definition: >- A catalog product is the Commerce presentation of an Accounting product, including its shelves, listing and any merchandise or download details. owned_by: MOD-COM-CAT synonyms: - Listing (the storefront presentation) - Merchandise item (for goods) not_to_be_confused_with: - >- The Accounting product, which retains the name, type, revenue accounts and price rows - 'An inventory item, which the fulfilment module retains for stock' - >- An entitlement, the right to download or use what was bought, retained by the orders module facets: - name: Category (shelf) meaning: >- Categories provide ordered, flat browsing groups with presentation choices. used_for: Organizing storefront navigation and offering selection. - name: Listing meaning: >- Publication state, text, slug, gallery, badges and related items describe the store presentation. used_for: Presenting the item and assessing public sale access. - name: Digital files meaning: >- Private files, labels and download settings support purchased digital goods. used_for: Delivering granted digital purchases. - name: Merchandise details meaning: >- Delivery, measures, stock and backorder settings describe how goods are handled. used_for: Supplying physical-sale and delivery context. - name: Variants and option sets meaning: >- Option sets define variant values and modifiers, with SKUs identifying variants. used_for: Selecting a product’s merchandise form. - name: Availability meaning: >- Stock assessment supplies descriptive availability and, where requested, a remaining count. used_for: The shelf and each checkout line. relationships: - to: CON-COM-CAT-002 statement: Category membership makes a listing eligible for an admitting store. provenance: test source: >- services-commerce:modules/catalog/tests/integration/services/storefront/storefront-listings.queries.integration.spec.js#says whether a product sits on a shelf the store admits - to: CON-COM-CAT-004 statement: >- Commerce reads Accounting price rows; supplied variant adjustments exist in the isolated engine but remain absent from the running loader. provenance: observed source: 'services-commerce:modules/pricing/services/persistence/catalog-products.ts' - to: CON-COM-CAT-006 statement: Listing associations supply candidates for related-item suggestions. provenance: observed source: >- services-commerce:modules/recommendations/services/evaluation/evaluate-offers.ts:1 lifecycle: - state: Draft meaning: >- Not displayed and not sold to the public; customer staff can still sell it. how_it_changes: Customer customer staff publish or unlist it. - state: Published meaning: On the shelf of each store that admits one of its categories. how_it_changes: Customer customer staff unlist it or return it to draft. - state: Unlisted meaning: Direct-page access remains available without public list inclusion. how_it_changes: Customer customer staff publish it or return it to draft. - state: Retired meaning: >- The Accounting product is retired; the merchandise record is retained for history. how_it_changes: Accounting controls retirement and this module provides no reversal. acted_on_by: - CAP-COM-CAT-005 - CAP-COM-CAT-006 - CAP-COM-CAT-007 - CAP-COM-CAT-008 - CAP-COM-CAT-009 visible_to: - ACT-COM-001 - ACT-COM-004 - ACT-COM-005 - ACT-COM-006 evidence: - >- Pinned service inputs: modules/catalog (categories, listings, storefront, downloads, assets), modules/merchandise (extensions, option sets, participant), COMM-M1 D8, D11; COMM-M1b R6 - >- Pinned console inputs: components/commerce/{merchandise,catalog}/**, components/configuration/resources/product-categories.tsx supersedes: [] --- # Catalog Product ## What It Is A catalog product is the item staff prepare for selling and shoppers recognize in a store. Accounting supplies the continuing product identity, classification and price rows. Commerce adds the information needed to arrange it on shelves, describe it to buyers and assess merchandise selections. These are connected views of the same product rather than separate copies staff reconcile by name. Its listing supplies the shopper-facing presentation. Staff can prepare that information without immediately making it public. Categories place the product into browsing groups, while stores decide which groups they offer. A recognizable headline, description and images help a buyer understand the item before asking for a price. Goods also carry merchandise details, such as delivery mode and selectable variants. A digital item can carry privately stored files used after purchase. Availability describes whether a requested quantity can proceed. Together these facets connect staff preparation, public browsing and checkout assessment without making every sub-record a separate product concept. ## What It Is Not The catalog product does not replace the Accounting product or take ownership of its revenue classification. A listing is its public presentation, not the purchased order line. A variant distinguishes a selectable form of merchandise rather than creating another unrelated product. Download files are assets; the entitlement to retrieve them is owned by the orders module. ## How It Is Used Administrators create or edit merchandise and its Storefront section together. They select shelves and review how the saved item appears before publishing. Gallery preparation can fail when an asset cannot be read, and saves can fail when an earlier version is submitted. Buyers later browse eligible listings, choose merchandise options and use granted downloads after purchase. Support staff can retrieve files while preserving member download capacity. ## Its Facets **Shelves.** Categories provide ordered, flat browsing groups with presentation choices. **Listing.** Publication state, text, slug, gallery, badges and related items describe the store presentation. **Digital delivery.** Private files, labels and download settings support purchased digital goods. **Merchandise.** Delivery, measures, stock and backorder settings describe how goods are handled. **Selections.** Option sets define variant values and modifiers, with SKUs identifying variants. **Availability.** Stock assessment supplies descriptive availability and, where requested, a remaining count. ## How It Relates Stores admit the product through their assortments, pricing calculates amounts from Accounting data and promotions assess qualifying lines. The merchandise participant supplies sale-time availability, while fulfilment owns stock operations. Recommendations can use related-product selections from the listing. Shared asset preparation keeps images and files connected to their owning records. ## What It Could Become The product should connect merchandise variant and modifier data to the running pricing loader before presenting their isolated engine support as ordinary quote behaviour. It should also complete shared upload adoption and resolve the public treatment of unlisted listings before designing the shopper journey.