---
id: WF-COM-CAT-005
title: Save a merchandise item from the console in three steps
trigger: >-
  The merchandise editor saves one visible item through separate Accounting, goods-detail and storefront
  requests. Failure can leave an item partially prepared.
product_area: commerce
module: catalog
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
implements:
  - CAP-COM-CAT-007
  - CAP-COM-CAT-006
moves:
  - STATE-COM-CAT-003
crosses:
  - SVC-COM-CAT-merchandise
  - SVC-COM-CAT-catalog
idempotency: >-
  No request key spans all three saves. A creation retry can collide with the Accounting product already
  saved; staff reopen the incomplete item to continue.
concurrency: >-
  Product, goods details and listing each have separate versions. A competing edit can reject a later save
  while earlier requests remain committed.
hops:
  - 'n': 1
    actor_or_service: Console
    action: 'Save the Accounting product and Standard price, preserving other price rows during replacement.'
    anchor: 'react-console:lib/commerce/merchandise/live.ts:createLiveMerchandiseAdapter'
    seam: sync
    on_failure: Stop and display the Accounting refusal.
    left_inconsistent: No later Commerce step has run.
    observer: The requesting person or service receives the result and any returned refusal.
    provenance: observed
    source: 'react-console:lib/commerce/merchandise/live.ts:createLiveMerchandiseAdapter'
  - 'n': 2
    actor_or_service: Console to merchandise service
    action: 'Save delivery, packaging, stock, option-set and variant details for the product.'
    anchor: 'services-commerce:modules/merchandise/aws/api/merchandise.routes.ts'
    seam: sync
    on_failure: Stop and report an incomplete item; the prior Accounting write is retained.
    left_inconsistent: The product may exist or have changed without matching goods details.
    observer: The requesting person or service receives the result and any returned refusal.
    provenance: observed
    source: 'react-console:lib/commerce/merchandise/live.ts:createLiveMerchandiseAdapter'
  - 'n': 3
    actor_or_service: Console to catalog service
    action: Create or replace storefront content when the item is offered in the store.
    anchor: 'react-console:lib/commerce/catalog/live.ts:createLiveCatalogAdapter'
    seam: sync
    on_failure: Report an incomplete item without undoing the product or merchandise write.
    left_inconsistent: The item can retain missing or outdated storefront content.
    observer: The requesting person or service receives the result and any returned refusal.
    provenance: observed
    source: 'react-console:lib/commerce/merchandise/live.ts:createLiveMerchandiseAdapter'
branches:
  - 'Edits skip unchanged components but keep the same Accounting, merchandise and listing order.'
waits: []
evidence:
  - >-
    react-console at baf6dae3: lib/commerce/merchandise/live.ts (the three-record adapter and
    MerchandiseIncompleteError); lib/commerce/catalog/live.ts (saveListing);
    components/commerce/merchandise/merchandise-edit-page.tsx.
  - >-
    services-commerce at c8b66a98: modules/merchandise/services/persistence/merchandise-extensions.ts (the
    product base written in the same transaction when stated).
controls: [TC-IAM-006, 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-DAT-001, TC-DAT-002, TC-DAT-003, TC-LOG-004, TC-LOG-005, TC-AVL-004, TC-MON-001, TC-MON-002, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002]
---

# Save a merchandise item from the console in three steps

## What It Does

The merchandise editor saves one visible item through separate Accounting, goods-detail and storefront requests. Failure can leave an item partially prepared.

## The Flow

```mermaid
sequenceDiagram
  participant S as Staff
  participant C as Console
  participant A as Accounting products
  participant M as Merchandise service
  participant L as Catalog service
  S->>C: save item
  C->>A: create or replace product
  A-->>C: product
  C->>M: create or replace details
  alt details refused
    M-->>C: refusal
    C-->>S: item incomplete (product kept)
  end
  C->>L: create or replace listing
  alt listing refused
    L-->>C: refusal
    C-->>S: item incomplete (product and details kept)
  end
  C-->>S: saved
```

## When Something Fails

Stop and display the Accounting refusal. No later Commerce step has run. Stop and report an incomplete item; the prior Accounting write is retained. The product may exist or have changed without matching goods details. Report an incomplete item without undoing the product or merchandise write. The item can retain missing or outdated storefront content.

## Open Design Questions

The implemented recovery and concurrency behaviour above defines the current boundary. Any change to transaction scope or product authority requires a recorded decision.