Use promotion codes before the sale

Purpose

Customers can request promotion savings while staff see which offers contribute to the reviewed sale. Refusals explain why the requested saving is unavailable.

How It Works

The clerk enters the code supplied by the customer and requests an updated summary. Commerce matches the code and evaluates the offers against the purchase. The summary distinguishes applied savings from rejected offers. Staff explanations can include details that a portal buyer does not receive. Removing a code requests a fresh summary without that entry. Placement provides the final point at which accepted promotion uses become recorded redemptions.

Relationships

Preview supplies eligible items and prices, while placement records the accepted redemption and voiding can release it.

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: Equivalent code entry produces one applied promotion.Rejected offers give the customer a readable explanation.
Surfaces: consoleapi
Intent sources: services-commerce:docs/milestones/plans/COMM-M2-plan.md#A8services-commerce:docs/milestones/plans/COMM-M2-plan.md#D10services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D12

Controls

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

Permissions

Key	Checked at	Scope
`commerce.checkouts.update`	api	tenant

Business Rules

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

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Confirmed	Code matching normalizes case, spaces and compatible full-width characters, displays the configured code and retains the entered spelling after trimming the request text. no proof recorded yet	validation	service	test services-commerce:modules/checkout/tests/e2e/promotions.e2e.spec.js#applies the one code to each, full-width letters and an ideographic space included (D-REC-12), shown by its display code, the entered code kept as typed (trimmed at the boundary)
`02`must prove Confirmed	Invalid promotion-code characters produce a readable validation refusal and are not stored on the cart. no proof recorded yet	validation	api, service	test services-commerce:modules/checkout/tests/e2e/checkout-promotion-code-refusals.e2e.spec.js#refuses a code holding a NUL character, 400, where the database would refuse the text as a 500
`03`must prove Confirmed	A promotion cannot apply twice through repeated entry or a different code for the same promotion; the refusal explains that it is already applied and enters the cart history. no proof recorded yet	validation	service	test services-commerce:modules/checkout/tests/e2e/promotions.e2e.spec.js#refuses the same code entered again, 409 already_applied with the customer’s message
`04`must prove Confirmed	A code with no qualifying items contributes no discount and remains in the placed snapshot as rejected with its reason. no proof recorded yet	validation	service	test services-commerce:modules/checkout/tests/e2e/promotions.e2e.spec.js#rejects the code nothing_qualifies, with the customer’s message, and takes nothing off
`05`must prove Confirmed	A valid code that adds no savings consumes no redemption, including when earlier discounts already make the item free. no proof recorded yet	policy	service	test services-commerce:modules/checkout/tests/e2e/promotions.e2e.spec.js#consumes no use of TENTH
`06`must prove Confirmed	Placement records the applied promotion and code use together with the discount allocation, while previews consume no uses. origin: services-commerce:docs/milestones/plans/COMM-M2-plan.md#A8 no proof recorded yet	lifecycle	service, database	test services-commerce:modules/checkout/tests/e2e/promotions.e2e.spec.js#takes one use of the code and of the promotion
`07`must prove Confirmed	Eligibility-limited promotions evaluate their declared subject during preview and placement; an indeterminate result fails both matching and non-matching requirements. origin: services-commerce:docs/milestones/plans/COMM-M2-plan.md#D10 no proof recorded yet	policy	service	test services-commerce:modules/checkout/tests/e2e/promotion-eligibility.e2e.spec.js#refuses it even for must_not_match: an indeterminate decision is not "does not match"
`08`must prove Confirmed	Portal buyers receive customer wording without staff-only explanations in their readable snapshot, while staff can also see operational details such as business-unit conflicts. no proof recorded yet	policy	service	test services-commerce:modules/checkout/tests/e2e/promotions.e2e.spec.js#keeps the staff message out of the price snapshot the portal member reads
`09`must prove Confirmed	Removing an entered code recalculates the preview and records the removal; removal of an absent code returns not found. no proof recorded yet	lifecycle	service	test services-commerce:modules/checkout/tests/e2e/checkout-promotion-code-refusals.e2e.spec.js#answers 404 to the removal of a code the checkout does not carry, naming the code
`10`must prove Confirmed	Automatic promotions enter pricing by priority without code entry, and an exclusive code displaces them only when it provides a better price. origin: services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D12 no proof recorded yet	calculation	service	test services-commerce:modules/checkout/tests/e2e/automatic-promotions.e2e.spec.js#lets VIP20 replace the automatic promotion when it leaves less to pay: $20.00
`11`must prove Confirmed	A portal buyer cannot add a promotion code to a cart outside their permitted parties. no proof recorded yet	permission	service	test services-commerce:modules/checkout/tests/e2e/promotions.e2e.spec.js#refuses another member entering a code on a checkout that is not theirs, 403

Scenarios

Id	Given	When	Then	Provenance
`01`	Jane’s book is priced at eighty dollars for the Member audience.	Staff enter the twenty-five-percent early-bird code.	The documented example reduces the book to sixty dollars and identifies the early-bird saving.	documented services-commerce:docs/milestones/plans/COMM-M2-plan.md#3. How it works for the user
`02`	Pat qualifies as a member.	Staff enter the welcome code restricted to non-members.	The code contributes no discount and the summary explains its refusal.	documented services-commerce:docs/milestones/plans/COMM-M2-plan.md#3. How it works for the user

Planning

Use promotion codes before the sale ​

Purpose ​

How It Works ​

Relationships ​