Issue promotion codes with controlled access

Purpose

Coordinators distribute code claims with identity, qualification and usage controls.

How It Works

Staff add individual codes to a code-claimed promotion or request a generated batch. Restrictions and eligibility govern permitted claims independently of a code’s listed owner. Saving checks normalized identity, dates and capacity. Generated batches run in the background and remain available for progress inspection and export. Later actions disable, enable or revoke codes with history retained. An interrupted batch resumes its remaining work, and a terminal failure preserves the codes already made. The product should confirm character policy and mixed personal/shared cancellation defaults.

Relationships

The prepare and control a promotion’s lifecycle capability supplies related configuration or assessment used in this work.

The choose the best permitted promotional result capability supplies related configuration or assessment used in this work.

The retain and review promotion usage 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: Claim restrictions identify the intended permitted purchasers.Batch issuance supplies unique claims with protected spreadsheet export.
Surfaces: consoleapijob
Intent sources: services-commerce:docs/milestones/COMM-M1b-promotions-and-codes.md#Decisions (D-R2)services-commerce:docs/milestones/COMM-M1b-promotions-and-codes.md#Scopeservices-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D13services-commerce:docs/milestones/plans/COMM-M1-plan.md#4. Assumptions (A22, A23)

Controls

27 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-CRY-004 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-DAT-004 TC-DAT-005 TC-LOG-001 TC-LOG-002 TC-LOG-003 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.promotions.read`	api	tenant
`commerce.promotions.manage`	api	tenant

Business Rules

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

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Proposed	Code identity is workspace-wide across promotions after case and space normalization, while the originally entered spelling remains available for display. origin: COMM-M1 plan A22 (DEF-COM-0817, Q03) (docs/milestones/plans/COMM-M1-plan.md) proved by `ATS-COM-CAT-015-01`, `TST-COM-CAT-092`	validation	service, database	test services-commerce:modules/promotions/tests/e2e/promotion-codes.e2e.spec.js#refuses “EARLY25” beside “early 25”, 409 code_taken
`02`must prove Proposed	Only code-claimed promotions accept individual or generated codes. origin: COMM-M1b D-R2 (docs/milestones/COMM-M1b-promotions-and-codes.md) proved by `ATS-COM-CAT-015-02`, `TST-COM-CAT-091`, `TST-COM-CAT-096`	validation	service	test services-commerce:modules/promotions/tests/e2e/promotions.e2e.spec.js#refuses a code, 409 automatic_promotion_has_no_codes
`03`must prove Confirmed	A code’s effective interval must fit within its promotion’s interval. origin: COMM-M1 D12 Q6 (docs/milestones/decisions/COMM-M1-D12-evaluation-algorithm.md) proved by `ATS-COM-CAT-015-03`, `TST-COM-CAT-092`, `TST-COM-CAT-132`	validation	service	test services-commerce:modules/promotions/tests/e2e/promotion-codes.e2e.spec.js#refuses a window ending after the promotion’s, 400 window_exceeds_promotion
`04`must prove Proposed	After width and space normalization, codes accept one to sixty-four ASCII letters, digits, hyphens or underscores and reject other characters during creation and entry. proved by `ATS-COM-CAT-015-04`, `TST-COM-CAT-092`, `TST-COM-CAT-125`, `TST-COM-CAT-126`	validation	api, service	test services-commerce:modules/promotions/tests/e2e/promotion-codes.e2e.spec.js#refuses a code with a slash or a percent sign, 400, naming code and saying the sentence (D-REC-6)
`05`must prove Proposed	Checkout entry uses the same normalization as stored-code lookup, including full-width forms and spaces. proved by `ATS-COM-CAT-015-04`, `TST-COM-CAT-092`, `TST-COM-CAT-125`, `TST-COM-CAT-126`	calculation	service	test services-commerce:modules/promotions/tests/unit/pricing/code-normalization.spec.js#resolves the full-width ＥＡＲＬＹ２５ to EARLY25 (NFKC)
`06`must prove Proposed	Single-use codes impose one total use and one use per customer and reject conflicting limits. origin: COMM-M1b D-R2 (docs/milestones/COMM-M1b-promotions-and-codes.md) proved by `ATS-COM-CAT-015-05`, `TST-COM-CAT-092`, `TST-COM-CAT-120`	validation	service	test services-commerce:modules/promotions/tests/e2e/promotion-codes.e2e.spec.js#refuses a single-use code with another limit, 400
`07`must prove Proposed	Codes may restrict contacts and organizations or apply their own eligibility rule; their listed owner organizes the code without restricting redemption. origin: COMM-M1b D-R2 (docs/milestones/COMM-M1b-promotions-and-codes.md) proved by `ATS-COM-CAT-015-06`, `ATS-COM-CAT-015-16`, `TST-COM-CAT-132`	policy	service	test services-commerce:modules/promotions/tests/unit/pricing/validation.spec.js#does not restrict by owner
`08`must prove Proposed	Staff cannot reduce code limits below recorded usage. proved by `ATS-COM-CAT-015-07`, `ATS-COM-CAT-015-17`, `ATS-COM-CAT-017-10`, `TST-COM-CAT-092`	validation	service	test services-commerce:modules/promotions/tests/e2e/promotion-codes.e2e.spec.js#refuses a limit below the uses made, 409 limit_below_uses
`09`must prove Proposed	Codes can move between active and disabled and from either to permanently revoked, with transitions retained in promotion history. proved by `ATS-COM-CAT-014-13`, `ATS-COM-CAT-015-08`, `ATS-COM-CAT-015-15`, `ATS-COM-CAT-015-18`, `ATS-COM-CAT-015-19`, `TST-COM-CAT-092`	lifecycle	service	test services-commerce:modules/promotions/tests/e2e/promotion-codes.e2e.spec.js#keeps a revoked code revoked: no operation moves it again
`10`must prove Proposed	Generation templates use digit, letter and mixed wildcards excluding ambiguous characters, require six wildcards, permit one to five thousand codes and require a possibility space ten thousand times the requested count. origin: COMM-M1b scope item 1 (docs/milestones/COMM-M1b-promotions-and-codes.md) proved by `ATS-COM-CAT-015-09`, `TST-COM-CAT-118`	validation	service	test services-commerce:modules/promotions/tests/unit/issuance/code-template.spec.js#refuses the same template for 27 codes, saying what it can make and what was asked
`11`must prove Proposed	Unless staff override it, a promotion enables cancellation release when its first code is personal and single-use. origin: COMM-M1 D13 (docs/milestones/COMM-M1-set-up-what-you-sell.md) proved by `ATS-COM-CAT-015-10`, `ATS-COM-CAT-015-17`, `ATS-COM-CAT-017-10`, `TST-COM-CAT-106`	policy	service	test services-commerce:modules/promotions/tests/integration/services/persistence/promotion-codes.integration.spec.js#turns release on cancellation on when the first code is personal and single-use, and says so in the history
`12`must prove Proposed	Code issuance starts asynchronously, reuses the batch for a repeated request, resumes missing codes after interruption and retains completed codes with a readable failure message. proved by `ATS-COM-CAT-015-11`, `ATS-COM-CAT-015-18`, `ATS-COM-CAT-015-19`, `TST-COM-CAT-091`, `TST-COM-CAT-119`	lifecycle	service	test services-commerce:modules/promotions/tests/unit/issuance/issuance-job.spec.js#continues from the codes that exist after a crash, making only the missing ones
`13`must prove Proposed	CSV exports prefix cells beginning with formula characters so opening the file cannot interpret those cells as formulas. proved by `ATS-COM-CAT-015-12`, `TST-COM-CAT-120`	policy	service	test services-commerce:modules/promotions/tests/unit/issuance/issuance-request-csv.spec.js#prefixes cells starting with = + - @ with a single quote
`14`must prove Confirmed	Code management and issuance require management permission, while code, redemption and batch inspection require read permission. origin: COMM-M1 plan A15 (promotions D-06) (docs/milestones/plans/COMM-M1-plan.md) proved by `ATS-COM-CAT-015-13`, `TST-COM-CAT-095`	permission	api, console	test services-commerce:modules/promotions/tests/e2e/promotions-security.e2e.spec.js#is refused every write, 403 permission_missing

Scenarios

Id	Given	When	Then	Provenance
`01`	A promotion already owns EARLY25	Create its spaced case variant on another promotion	Workspace-wide normalized identity prevents the duplicate	test services-commerce:modules/promotions/tests/e2e/promotion-codes.e2e.spec.js#refuses a code another promotion of the tenant has, 409 code_taken
`02`	A generated code batch has completed	Export its codes	The response is a downloadable CSV with a header and the batch’s code rows	test services-commerce:modules/promotions/tests/e2e/promotion-code-issuances.e2e.spec.js#exports the codes as text/csv: a header and 25 lines

Planning

Implementation

Issue promotion codes with controlled access ​

Purpose ​

How It Works ​

Relationships ​