--- id: CON-MBR-MEM-005 name: Billing Run feature: FEAT-MBR-MEM-05 product_area: membership module: memberships revision: 1 status: draft product_intent: confirmed implementation_evidence: partially-observed source_sha: services-membership: 5994c270e8a37a30f848e99ba5b5ee6b87c08893 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f definition: >- A billing run selects ending membership periods for a program, records planned renewal and closure actions, and tracks their execution outcomes. owned_by: MOD-MBR-MEM synonyms: - renewal run - dues billing run not_to_be_confused_with: - Other billing domains own invoice runs for their products. - Commerce owns the orders requested by membership billing. facets: - name: Billing template meaning: 'Reusable program, selection, action and drop-reason settings establish a renewal cycle.' used_for: Preparing repeated billing work without recreating its configuration. - name: Filters and actions meaning: The run stores its own selected filters and action choices. used_for: Keeping the run independent of later template edits. - name: Candidates and classes meaning: Eligible ending periods are classified as renewing or lapsed using the planning date and grace. used_for: Selecting the actions appropriate to each candidate. - name: Planned actions meaning: Each term-specific action retains its planned version and later outcome and external references. used_for: 'Reviewing intended work and distinguishing completed, skipped, stale and failed processing.' - name: Statistics meaning: 'Selection, exclusion and action counts summarize the plan and execution.' used_for: Reviewing the scale and result of the run. - name: Status meaning: 'Draft, planned, executing, executed and cancelled govern available operations.' used_for: 'Coordinating planning, review, execution and cancellation.' - name: Execution job meaning: A durable background job processes the run’s actions and retains progress. used_for: Handling long-running execution with inspectable steps and events. - name: Recurring run meaning: A scheduled definition creates dated occurrences from a template in the association’s time zone. used_for: Repeating renewal work with optional automatic execution. relationships: - to: CON-MBR-MEM-002 statement: The run selects ending terms and retains the term and planned version on each action. provenance: observed source: 'services-membership:modules/billing/db/billing-run-actions.table.ts' - to: CON-MBR-MEM-001 statement: >- Suspension and origin affect candidate selection, while do-not-renew and do-not-drop govern which actions are planned for candidates. provenance: observed source: 'services-membership:modules/billing/services/planning/run-plan.ts:runPlanOf' acted_on_by: - CAP-MBR-MEM-013 visible_to: - ACT-MBR-006 - ACT-MBR-008 lifecycle: - state: draft meaning: The run exists but has not yet selected its candidates. how_it_changes: 'Planning records candidates and actions, or cancellation stops the run.' - state: planned meaning: The recorded plan is available for review. how_it_changes: 'The administrator can replan, execute or cancel it.' - state: executing meaning: The run has an execution job responsible for its planned actions. how_it_changes: Completion marks it executed; the matching job’s failure consequence can return it to planned. - state: executed meaning: Execution has settled the available actions. how_it_changes: Another execution request can create a job without repeating already settled actions. - state: cancelled meaning: The run stops before execution while retaining its planned work. how_it_changes: No further run operation resumes the cancelled plan. evidence: - >- services-membership at 5994c270e8a37a30f848e99ba5b5ee6b87c08893: modules/billing/db/*.table.ts, billing-vocabularies.ts; services/planning/run-plan.ts, billing-documents.ts; services/runs/billing-run-operations.ts; services/execution/*; services/recurring/recurring-billing-runs.ts; docs/migrations/participant/README.md#Billing runs. supersedes: - 'inventory:CAP-MBR-BIL-001' - 'inventory:CAP-MBR-BIL-002' --- # Billing Run ## What It Is A billing run organizes a defined piece of membership renewal work. It selects terms ending within a date range for one program, classifies candidates and records the actions proposed for them. The administrator reviews that plan before execution, rather than discovering its scope only after orders or notices have been requested. A run can copy a reusable template or use directly supplied filters and action choices. Its own stored settings preserve the selected work independently of later template changes. The planning date determines whether a candidate is still renewing or has passed grace and lapsed. Execution then tracks each action and its outcome through a durable background job. ## What It Is Not The run does not own invoices, prices or payments. Membership prepares the renewal offer; Commerce and Accounting perform their parts of order and financial processing. A notice action is a request to Platform communications rather than proof that a message reached a member. The run therefore coordinates renewal work without making every external seam operational by itself. ## How It Is Used An administrator creates the run, selects its ending-date range and plans it against a business date. They review candidate and action counts before asking for execution. Replanning inserts newly identified actions without discarding the existing action record. Readers can inspect the run without permission to perform these changes. Execution prepares renewal orders through the same membership preparation path used by checkout. Drops use the term-termination behavior, and communication actions request the configured messages. A changed term makes its planned action stale. External order placement is currently unwired, organization notice recipients are unresolved and communication purposes do not yet produce sent notices. These delivery limits remain visible even when the run and its plan exist. ## Its Facets **Billing template.** Program, filters, requested actions and the closing reason form a reusable definition. A run that drops members requires an applicable termination reason. **Filters and actions.** The run copies its selections. Do-not-renew and do-not-drop affect action planning rather than necessarily removing the term from the candidate list. **Candidates and classes.** Ending committed periods from principal holdings are considered. Configuration filters, later periods, suspension and open-ended terms affect eligibility; grace distinguishes renewing candidates from lapsed candidates. **Planned actions.** Term references, planned versions, action kinds and reminder numbers identify the work. Outcomes retain whether execution completed, skipped, encountered stale facts or failed. **Statistics.** Counts summarize candidates, exclusions and selected actions, allowing review of both the intended workload and recorded result. **Status.** The run’s state limits planning, cancellation and execution. Executed is not an irrevocable terminal state: another execution request can create a job while settled actions remain settled. **Execution job.** Background processing retains progress and uses a failure consequence to return the matching executing run to planned. A job that never starts still needs reconciliation, which is not deployed for this module. **Recurring run.** A scheduled definition derives an occurrence’s ending-date range from configured offsets and can request execution after planning. It uses the association’s time zone for the occurrence. ## How It Relates Terms supply candidates, and member settings influence planned actions. Checkout preparation supplies renewal eligibility and purchase details. Termination supplies the closing action. Commerce, Platform communications and durable jobs provide the external services required for execution; expiry attention separately highlights members whose renewal still needs action. ## What It Could Become The product should choose an organizational notice recipient and use actual card expiry before issuing card warnings. It should complete the external ports and reconcile execution jobs that fail to start. A reviewable file of planned actions could also help administrators assess a season’s work before committing to execution.