--- id: SVC-COM-CAT-merchandise title: 'Merchandise: goods details, variants, option sets and the merchandise participant' product_area: commerce module: catalog repository: services-commerce source_module: modules/merchandise revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owns: - DOM-COM-CAT-003 does_not_own: - MOD-ACC-PRD owns product definitions and financial prices; Accounting functions perform their writes. - MOD-COM-FUL manages inventory reservations and allocations. - SVC-COM-CAT-catalog maintains listings and categories. operations: - operation_id: createMerchandise intent: Prepare a new goods details with validated configuration. access: console permission: commerce.merchandise.create realises: - CAP-COM-CAT-007 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: listMerchandise intent: Browse the workspace’s goods details using supported filters. access: console permission: commerce.merchandise.read realises: - CAP-COM-CAT-007 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: getMerchandise intent: Inspect the selected goods details and its retained details. access: console permission: commerce.merchandise.read realises: - CAP-COM-CAT-007 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: updateMerchandise intent: Save permitted changes to the selected goods details at its read version. access: console permission: commerce.merchandise.update realises: - CAP-COM-CAT-007 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: retireMerchandise intent: Retire the Accounting product while retaining its goods details. access: console permission: commerce.merchandise.update realises: - CAP-COM-CAT-007 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: deleteMerchandise intent: Remove the selected goods details when protection and dependencies permit. access: console permission: commerce.merchandise.delete realises: - CAP-COM-CAT-007 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: createMerchandiseOptionSet intent: Prepare a new merchandise option set with validated configuration. access: console permission: commerce.merchandise.create realises: - CAP-COM-CAT-007 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: listMerchandiseOptionSets intent: Browse the workspace’s merchandise option sets using supported filters. access: console permission: commerce.merchandise.read realises: - CAP-COM-CAT-007 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: getMerchandiseOptionSet intent: Inspect the selected merchandise option set and its retained details. access: console permission: commerce.merchandise.read realises: - CAP-COM-CAT-007 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: updateMerchandiseOptionSet intent: Save permitted changes to the selected merchandise option set at its read version. access: console permission: commerce.merchandise.update realises: - CAP-COM-CAT-007 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: deleteMerchandiseOptionSet intent: Remove the selected merchandise option set when protection and dependencies permit. access: console permission: commerce.merchandise.delete realises: - CAP-COM-CAT-007 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: merchandise.prepare_purchase intent: Assess a goods purchase and prepare participant claims and fulfilment advice. access: internal permission: none (participant contract) realises: - CAP-COM-CAT-007 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: merchandise.extend_hold intent: Renew a merchandise hold through the participant contract. access: internal permission: none (participant contract) realises: - CAP-COM-CAT-007 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: merchandise.fulfill intent: Produce the goods participant’s fulfilment response. access: internal permission: none (participant contract) realises: - CAP-COM-CAT-007 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: merchandise.prepare_cancellation intent: Prepare the participant’s effects for cancelling merchandise. access: internal permission: none (participant contract) realises: - CAP-COM-CAT-007 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: merchandise.prepare_change intent: Prepare participant effects for a merchandise amendment. access: internal permission: none (participant contract) realises: - CAP-COM-CAT-007 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: merchandise.readMerchandiseCatalog intent: Supply goods attributes and variant data to Commerce callers. access: internal permission: none (in-process) realises: - CAP-COM-CAT-007 - CAP-COM-CAT-013 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: merchandise.findMerchandiseProductIds intent: Identify merchandise products matching the requested selection. access: internal permission: none (in-process) realises: - CAP-COM-CAT-014 published_to_submissions: 'not published: this operation has no registered Submissions binding' events: [] jobs: [] integrations: - system: Accounting product write functions direction: outbound contract: >- Accounting product save, retirement and serialization functions run inside Commerce’s transaction through its writer role and copied product contract. - system: Participant registry (orders module) direction: inbound contract: >- The in-process goods participant supplies purchase, hold, claim, fulfilment, cancellation and amendment methods. consistency: - rule: A request carrying the Accounting base product commits that product and its goods details together. kind: transactional compensation: Either writer’s refusal rolls back both components. - rule: Variant reconciliation preserves the identifiers of retained stock codes. kind: transactional compensation: The variant transaction rolls back a refused replacement. - rule: 'The console saves the Accounting product, goods details and listing in independent requests.' kind: eventual compensation: 'Earlier commits remain after a later failure, and staff receive incomplete-item feedback.' evidence: - >- services-commerce at c8b66a98: modules/merchandise/aws/api/merchandise.routes.ts, services/**/*.ts, db/*.table.ts. - 'react-console at baf6dae3: lib/commerce/merchandise/live.ts.' controls: [TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-DAT-001, TC-DAT-004, TC-LOG-004, TC-AVL-002, TC-AVL-003, TC-MON-001, TC-MON-003, TC-MON-004, TC-PI-001, TC-PI-003, TC-PI-005] --- # Merchandise: goods details, variants, option sets and the merchandise participant ## What This Service Is For Merchandise supplies delivery, packaging, variant and stock-policy information around an Accounting product and participates in checkout and fulfilment. ## Boundary Accounting retains the product and price grid. Fulfilment retains inventory, holds and allocations. Catalog retains storefront content and shelves. ## Operations in Words Staff maintain goods details and reusable option sets, retire base products or remove eligible extensions. A request may include an Accounting product write in the same transaction. Internal participant entries describe purchase, holding, fulfilment, cancellation and amendment seams. ## Events and Jobs No module-owned queue or background job handles these writes. Participant execution runs within the owning checkout or order flow, and no external change event is emitted. ## Consistency Guarantees The combined service write is atomic and variant matching preserves inventory references. The built console instead commits product, goods details and listing separately, so later failure leaves earlier work saved.