--- id: SVC-COM-CAT-promotions title: 'Promotions: promotions, codes, issuance, redemptions and performance' product_area: commerce module: catalog repository: services-commerce source_module: modules/promotions revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owns: - DOM-COM-CAT-005 does_not_own: - MOD-COM-ORD controls the order changes that consume and release promotion uses. - MOD-ACC-TRX owns invoices and financial discount reversals. - MOD-PFM-ELG evaluates campaign and code eligibility. - Each participating application implements its own selling areas. operations: - operation_id: createPromotion intent: Prepare a new campaign with validated configuration. access: console permission: commerce.promotions.manage realises: - CAP-COM-CAT-014 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: listPromotions intent: Browse the workspace’s campaigns using supported filters. access: console permission: commerce.promotions.read realises: - CAP-COM-CAT-014 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: getPromotion intent: Inspect the selected campaign and its retained details. access: console permission: commerce.promotions.read realises: - CAP-COM-CAT-014 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: updatePromotion intent: Save permitted changes to the selected campaign at its read version. access: console permission: commerce.promotions.manage realises: - CAP-COM-CAT-014 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: duplicatePromotion intent: Copy the campaign configuration into a distinct draft without codes or usage. access: console permission: commerce.promotions.manage realises: - CAP-COM-CAT-014 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: activatePromotion intent: Launch the campaign after required activation checks. access: console permission: commerce.promotions.activate realises: - CAP-COM-CAT-014 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: pausePromotion intent: Suspend participation by the campaign while retaining its records. access: console permission: commerce.promotions.manage realises: - CAP-COM-CAT-014 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: resumePromotion intent: Restore participation by the paused campaign after activation checks. access: console permission: commerce.promotions.activate realises: - CAP-COM-CAT-014 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: endPromotion intent: Stop the campaign permanently while keeping its history. access: console permission: commerce.promotions.manage realises: - CAP-COM-CAT-014 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: archivePromotion intent: Retain the eligible campaign as archived and exclude it from ordinary use. access: console permission: commerce.promotions.manage realises: - CAP-COM-CAT-014 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: listPromotionHistory intent: Review the campaign’s attributed history in reverse chronological order. access: console permission: commerce.promotions.read realises: - CAP-COM-CAT-014 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: listPromotionAreas intent: Inspect registered selling areas and their allowed criteria. access: console permission: commerce.promotions.read realises: - CAP-COM-CAT-014 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: createPromotionCode intent: Prepare a new claim code with validated configuration. access: console permission: commerce.promotions.manage realises: - CAP-COM-CAT-015 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: listPromotionCodes intent: Browse the workspace’s claim codes using supported filters. access: console permission: commerce.promotions.read realises: - CAP-COM-CAT-015 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: listAllPromotionCodes intent: Search claim codes across all campaigns. access: console permission: commerce.promotions.read realises: - CAP-COM-CAT-015 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: getPromotionCode intent: Inspect the selected claim code and its retained details. access: console permission: commerce.promotions.read realises: - CAP-COM-CAT-015 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: updatePromotionCode intent: Save permitted changes to the selected claim code at its read version. access: console permission: commerce.promotions.manage realises: - CAP-COM-CAT-015 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: disablePromotionCode intent: Temporarily prevent claims through the claim code. access: console permission: commerce.promotions.manage realises: - CAP-COM-CAT-015 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: enablePromotionCode intent: Restore claims through the disabled claim code. access: console permission: commerce.promotions.manage realises: - CAP-COM-CAT-015 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: revokePromotionCode intent: Permanently prevent further claims through the claim code. access: console permission: commerce.promotions.manage realises: - CAP-COM-CAT-015 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: createPromotionCodeIssuance intent: Save a generation batch and request execution of its code worker. access: console permission: commerce.promotions.manage realises: - CAP-COM-CAT-015 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: getPromotionCodeIssuance intent: Inspect batch progress and restart stale unfinished work when necessary. access: console permission: commerce.promotions.read realises: - CAP-COM-CAT-015 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: exportPromotionCodeIssuanceCodes intent: Download the batch’s saved codes as a spreadsheet-safe CSV. access: console permission: commerce.promotions.read realises: - CAP-COM-CAT-015 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: listPromotionRedemptions intent: Review a campaign’s retained order uses and line allocations. access: console permission: commerce.promotions.read realises: - CAP-COM-CAT-017 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: listPromotionCodeRedemptions intent: Review retained uses attributed to one claim code. access: console permission: commerce.promotions.read realises: - CAP-COM-CAT-017 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: listOrderPromotionRedemptions intent: Inspect the promotion uses recorded on an order. access: console permission: commerce.promotions.read realises: - CAP-COM-CAT-017 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: releasePromotionRedemption intent: Restore one applied use with an authorized explanation while retaining monetary evidence. access: console permission: commerce.promotions.override realises: - CAP-COM-CAT-017 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: readPromotionPerformance intent: Calculate campaign usage and monetary measures separately by currency. access: console permission: commerce.promotions.read realises: - CAP-COM-CAT-017 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: previewPromotions intent: Assess a sample cart without saving checkout or usage records. access: console permission: commerce.promotions.read realises: - CAP-COM-CAT-018 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: promotions.resolveCheckoutCandidates intent: 'Supply campaign candidates, parts, restrictions and relevant usage to checkout assessment.' access: internal permission: none (in-process) realises: - CAP-COM-CAT-016 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: promotions.recordRedemption intent: Acquire usage and retain frozen discount allocations within order placement. access: internal permission: none (in-process) realises: - CAP-COM-CAT-017 - CAP-COM-CAT-016 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: promotions.releaseVoidedOrderRedemptions intent: Restore applied campaign capacity when the owning order is voided. access: internal permission: none (in-process) realises: - CAP-COM-CAT-017 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: promotions.releaseRedemptionsForCancelledLines intent: Restore eligible uses after full cancellation of all allocated lines. access: internal permission: none (in-process) realises: - CAP-COM-CAT-017 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: promotions.listOrderLineDiscountsForBilling intent: Provide frozen allocations and campaign labels for invoice descriptions. access: internal permission: none (in-process) realises: - CAP-COM-CAT-016 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: promotions.findPromotionDiscountDrift intent: 'Identify mismatched order, redemption and allocation totals for reconciliation.' access: internal permission: none (in-process) realises: - CAP-COM-CAT-017 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: promotions.runPromotionCodeIssuance intent: Generate the batch’s remaining codes and retain progress or failure. access: internal permission: none (worker) realises: - CAP-COM-CAT-015 published_to_submissions: 'not published: this operation has no registered Submissions binding' events: - name: order.promotion_released direction: produced when: 'A staff override, order void or eligible full-line cancellation releases an applied use.' payload_summary: >- The order history retains the releasing actor and explanation; this record is not an externally published event. jobs: - >- An asynchronously invoked promotion-code worker resumes batch generation; no queue or schedule triggers it. integrations: - system: Promotion area providers direction: outbound contract: >- Area providers validate criteria and qualify lines; only the in-process merchandise provider is registered. - system: Platform number seeds direction: outbound contract: The shared numbering service supplies workspace campaign numbers. - system: Workspace data export direction: outbound contract: 'Campaign export includes parts, generated batches, codes, redemptions and history.' consistency: - rule: >- Placement acquires code capacity before campaign capacity, in stable campaign order within the order transaction. kind: transactional compensation: Refused capacity acquisition rolls back placement. - rule: Commit checks require each retained redemption total to equal its allocations. kind: transactional compensation: The inconsistent sale cannot commit. - rule: Void and eligible cancellation restore applied usage at most once within their caller’s transaction. kind: transactional compensation: Release changes capacity while preserving charged discount evidence. - rule: Resumed code generation never inserts more than the batch’s remaining requested count. kind: eventual compensation: Retries and stale reads can resume unfinished work; failed batches keep completed codes. - rule: Attributed campaign changes append their corresponding history within the same save. kind: transactional compensation: The configuration transaction rolls back failed history writes. evidence: - >- services-commerce at c8b66a98: modules/promotions/aws/api/*.routes.ts, services/**/*.ts, db/*.table.ts, aws/lambda/*.ts, aws/logic/*.ts, metadata/promotions.object.ts, export/*.ts. - 'react-console at baf6dae3: lib/commerce/promotions/live.ts.' controls: [TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, 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-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-AVL-002, TC-AVL-003, TC-AVL-004, TC-MON-001, TC-MON-002, TC-MON-003, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-VEN-001, TC-VEN-002, TC-VEN-003, TC-PRV-001, TC-PRV-002] --- # Promotions: promotions, codes, issuance, redemptions and performance ## What This Service Is For Promotions prepares campaign benefits, controls claim codes and generation batches, compares allowed discounts and retains accountable order usage. ## Boundary Orders owns placement, voids and cancellations and calls use functions within its transactions. Accounting owns monetary documents and reversals. Platform owns eligibility definitions; registered area providers qualify lines. ## Operations in Words Management authority prepares and edits campaigns and codes; activation authority launches or resumes them. Read operations review codes, history, batches, uses and performance or test a sample cart. Override authority permits explained manual release. Internal entries provide candidate assessment, redemption, release and billing allocation reads. ## Events and Jobs Code generation uses a directly invoked asynchronous worker rather than a work queue or schedule. Use release writes order history but does not publish an external event. ## Consistency Guarantees Conditional capacity acquisition and frozen allocations commit with placement. Release restores capacity without altering discount evidence. Batch progress survives partial generation, with bounded retries and retained failure explanations.