Manage merchandise selections and sale availability

Purpose

Administrators describe merchandise options while Commerce assesses whether requested lines can proceed.

How It Works

Staff create or edit merchandise together with its Accounting product. Variant sets and modifier sets describe the available choices for buyers. Commerce resolves a line selection and asks the availability logic to assess its quantity. Insufficient stock becomes a warning or refusal according to the configured backorder treatment. Stock references also matter when staff remove variants or merchandise. Retirement retains the extension while changing the product’s standing. The product should connect variant pricing inputs to the running product loader before relying on those adjustments outside isolated engine tests.

Relationships

The prepare and publish product presentations capability supplies related configuration or assessment used in this work.

The calculate and explain a buyer’s item price capability supplies related configuration or assessment used in this work.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes: Merchandise preparation retains atomic persistence with its Accounting product.A buyer is does not sold stock that is not there except when backorders are allowed.
Surfaces: consoleapi
Intent sources: services-commerce:docs/milestones/walkthroughs/COMM-M1-handoff.md#What changed after your review (6)services-commerce:docs/milestones/COMM-M1b-promotions-and-codes.md#Decisions (R6)

Controls

22 controls apply, from the corpus control catalogue.

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-DAT-004 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PI-002 TC-PI-003 TC-PI-005 TC-PRV-001 TC-PRV-002

Permissions

Key	Checked at	Scope
`commerce.merchandise.read`	api	tenant
`commerce.merchandise.create`	api	tenant
`commerce.merchandise.update`	api	tenant
`commerce.merchandise.delete`	api	tenant
`commerce.merchandise.bulk`	api	tenant

Business Rules

14 rules, 12 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Proposed	Commerce permits one merchandise extension for an existing Accounting merchandise product and refuses unknown products, other product types and duplicate extensions. proved by `ATS-COM-CAT-007-01`, `TST-COM-CAT-044`, `TST-COM-CAT-050`	validation	service, database	test services-commerce:modules/merchandise/tests/e2e/merchandise.e2e.spec.js#answers 400 to a product the tenant has not, a selection off the sets, a SKU in use and a second extension, naming the rule
`02`must prove Proposed	Merchandise and Accounting product creation or replacement commit together, rolling back both when either validation fails. proved by `ATS-COM-CAT-007-02`, `TST-COM-CAT-050`	invariant	service	test services-commerce:modules/merchandise/tests/integration/services/persistence/merchandise-products.queries.integration.spec.js#leaves no product when the database refuses the extension row
`03`must prove Proposed	Accounting refuses a merchandise price grid without a Standard price in the product’s base currency. origin: COMM-M1 D6 (docs/milestones/COMM-M1-set-up-what-you-sell.md) proved by `ATS-COM-CAT-007-02`, `TST-COM-CAT-050`	validation	service	test services-commerce:modules/merchandise/tests/integration/services/persistence/merchandise-products.queries.integration.spec.js#refuses a grid without a standard price 400 with Accounting’s rule
`04`must prove Proposed	Retirement changes the Accounting product’s status while retaining its merchandise extension, and a repeated retirement is refused. proved by `ATS-COM-CAT-007-03`, `TST-COM-CAT-044`, `TST-COM-CAT-051`	lifecycle	service	test services-commerce:modules/merchandise/tests/e2e/merchandise.e2e.spec.js#retires the product at its version, keeping the extension; a second retirement is 409
`05`must prove Proposed	Stock references to merchandise variants prevent deletion of the merchandise extension. proved by `ATS-COM-CAT-007-03`, `TST-COM-CAT-044`, `TST-COM-CAT-051`	lifecycle	service	test services-commerce:modules/merchandise/tests/integration/services/persistence/merchandise.integration.spec.js#refuses to delete an extension whose SKUs inventory items hold (409), deletes one that has none, and answers 404 for one the tenant has not
`06`must prove Proposed	Variant SKUs are unique within the workspace, each selection supplies exactly one permitted value per variant option set, and selections cannot repeat within a product. proved by `ATS-COM-CAT-007-04`, `TST-COM-CAT-046`, `TST-COM-CAT-051`	validation	service, database	test services-commerce:modules/merchandise/tests/integration/db/merchandise-tables.table.integration.spec.js#refuses one SKU twice in a tenant (merchandise_variants_sku_uq) and one selection twice for a product (merchandise_variants_selection_uq), while another tenant may use the SKU
`07` Proposed	Replacement retains variant identities for retained SKUs and removes omitted SKUs, preserving inventory references to the retained variants. proved by `ATS-COM-CAT-007-12`	invariant	service	test services-commerce:modules/merchandise/tests/integration/services/persistence/merchandise.integration.spec.js#replaces the extension at its version: the kept SKU keeps its id, a new SKU is added, a dropped one goes
`08`must prove Proposed	Option sets distinguish variant values from modifiers: modifiers must use permitted values, variant sets have no modifier options, and empty sets are refused. proved by `ATS-COM-CAT-007-04`, `TST-COM-CAT-046`, `TST-COM-CAT-051`	validation	service, database	test services-commerce:modules/merchandise/tests/integration/services/persistence/merchandise.integration.spec.js#refuses a modifier option off the set’s values, a variant set with options, and an empty set, 400
`09`must prove Proposed	Availability compares requested quantity with tracked stock: sufficient stock above the threshold is available, a smaller remainder is limited, and shortfalls either become permitted backorders or refusals; untracked stock remains available. proved by `ATS-COM-CAT-007-05`, `TST-COM-CAT-052`	calculation	service	test services-commerce:modules/merchandise/tests/unit/participant/merchandise-availability.spec.js#is unavailable with what is left when stock is short and the product prohibits backorders: the line is refused
`10`must prove Proposed	Merchandise lines reject notes exceeding two hundred counted characters and selections that identify no variant. proved by `ATS-COM-CAT-007-06`, `TST-COM-CAT-053`	validation	service	test services-commerce:modules/merchandise/tests/unit/participant/merchandise-payload.spec.js#limits a note to 200 characters, counted as the person sees them: an emoji is one, so 201 characters are refused and 200 are not (COM-ACC-0015)
`11`must prove Proposed	The isolated pricing engine uses supplied variant prices and modifiers, but ordinary product loading supplies empty lists and does not connect those adjustments to quotes. proved by `ATS-COM-CAT-007-07`, `ATS-COM-CAT-007-11`	calculation	service	observed services-commerce:modules/pricing/services/persistence/catalog-products.ts:toCatalogProduct
`12`must prove Proposed	Merchandise reads require read permission, writes require administrator permissions, and the merchandise contract rejects custom fields. proved by `ATS-COM-CAT-007-08`, `TST-COM-CAT-044`	permission	api, console	test services-commerce:modules/merchandise/tests/e2e/merchandise.e2e.spec.js#lets a reader list and read, and refuses it every write 403 permission_missing, leaving the records as they were
`13` Proposed	Staff manage merchandise and its listing in one item screen, and the former listing address redirects to that item. origin: COMM-M1 walkthrough ruling R1 (docs/milestones/walkthroughs/COMM-M1-handoff.md) proved by `ATS-COM-CAT-006-16`, `ATS-COM-CAT-007-10`	policy	console	test react-console:e2e/mock/merchandise.mock.spec.ts#the old Listings address opens the same item
`14`must prove Proposed	A full lock prevents replacing a merchandise extension, and either full or deletion-only locking prevents removing it. proved by `ATS-COM-CAT-007-09`	policy	service	observed services-commerce:modules/merchandise/services/persistence/merchandise-extensions.ts

Scenarios

Id	Given	When	Then	Provenance
`01`	One cap remains and backorders are prohibited	Request two caps	Availability refuses the line for insufficient stock and reports one remaining	test services-commerce:modules/merchandise/tests/integration/services/participant/merchandise-participant.integration.spec.js#answers one cap too many unavailable, insufficient_stock, with what is left
`02`	Tracked shirt stock is insufficient and backorders are enabled	Request more shirts than available stock	The line proceeds with the shortfall reported as a backorder	test services-commerce:modules/merchandise/tests/integration/services/participant/merchandise-participant.integration.spec.js#answers the shirt short of stock ok with backorders allowed, the shortfall named as a warning and in the conditions, the SKU resolved from the selection

Edge Cases

Id	Given	When	Then	Provenance
`03`	A new backordered SKU has no inventory row	Run competing placement claims for that SKU	Both claims succeed while sharing one inventory item	test services-commerce:modules/merchandise/tests/integration/services/participant/backorder-race.integration.spec.js#leaves exactly one inventory item for the SKU

Planning

Implementation

Manage merchandise selections and sale availability ​

Purpose ​

How It Works ​

Relationships ​