---
id: WF-MBR-MEM-017
title: Create and plan a billing run
trigger: An administrator creates a dated renewal batch and requests its plan.
product_area: membership
module: memberships
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-membership: 5994c270e8a37a30f848e99ba5b5ee6b87c08893
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
implements:
  - CAP-MBR-MEM-013
moves:
  - STATE-MBR-MEM-007
crosses:
  - SVC-MBR-MEM-billing
  - SVC-MBR-MEM-memberships
idempotency: >-
  Action uniqueness prevents duplication of the kind, reminder index and term
  combination. Replanning can add previously absent actions.
concurrency: Planning locks the run and checks its version and permitted status.
hops:
  - 'n': 1
    actor_or_service: Billing manager through the API
    action: >-
      Create a draft batch with copied template settings or supplied filters and
      actions.
    anchor: >-
      services-membership:modules/billing/services/runs/billing-run-operations.ts:createRun
    seam: sync
    on_failure: Reject program mismatch or missing drop reason before creating the run.
    left_inconsistent: No partial local change remains.
    observer: Caller-visible API result
    provenance: test
    source: >-
      services-membership:tests/e2e/billing-api.e2e.spec.ts#creates a run from
      the template
  - 'n': 2
    actor_or_service: Billing service
    action: >-
      Select ending principal terms and exclude later coverage, unlimited
      periods and suspended or derived holdings.
    anchor: >-
      services-membership:modules/billing/services/persistence/billing-runs.ts:candidateTermsOf
    seam: sync
    on_failure: Reject the operation before committing any writes.
    left_inconsistent: No partial local change remains.
    observer: Caller-visible API result
    provenance: test
    source: >-
      services-membership:modules/billing/tests/unit/run-plan.spec.ts#leaves out
      a term already renewed
  - 'n': 3
    actor_or_service: Billing service
    action: >-
      Classify candidates by the planning date and grace and select actions
      using renewal and drop preferences.
    anchor: >-
      services-membership:modules/billing/services/planning/run-plan.ts:runPlanOf
    seam: sync
    on_failure: Reject the operation before committing any writes.
    left_inconsistent: No partial local change remains.
    observer: Caller-visible API result
    provenance: test
    source: >-
      services-membership:modules/billing/tests/unit/run-plan.spec.ts#classes a
      term ending before the date less its grace as lapsed
  - 'n': 4
    actor_or_service: Billing service
    action: 'Insert versioned action plans, count statistics and mark the run planned.'
    anchor: >-
      services-membership:modules/billing/services/runs/billing-run-operations.ts:planRun
    seam: sync
    on_failure: Reject stale or non-plannable runs and roll back planning.
    left_inconsistent: No partial local change remains.
    observer: Batch record and action list
    provenance: test
    source: >-
      services-membership:modules/billing/tests/unit/run-plan.spec.ts#counts the
      candidates, their classes, the exclusions and the planned actions
branches:
  - >-
    Planning card warnings does not inspect card expiry; it selects
    automatic-renewal holdings with stored methods.
waits:
  - >-
    Planning creates reviewable work; execution requires another authorized
    request unless recurrence enables it.
evidence:
  - >-
    services-membership at 5994c270:
    modules/billing/services/runs/billing-run-operations.ts;
    services/planning/run-plan.ts; services/persistence/billing-runs.ts
controls: [TC-AVL-002, TC-AVL-003, TC-AVL-004, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-007, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-SEC-001, TC-SEC-004, TC-TEN-001, TC-TEN-002, TC-TEN-003]
---

# Create and plan a billing run

## What It Does

Planning turns a renewal selection into a reviewable list of proposed actions. Creating a run and planning it are separate transactions and perform no renewal effects.

## The Flow

```mermaid
flowchart TD
  H1["Create a draft batch with copied template settings or supplied filters and actions"]
  H2["Select ending principal terms and exclude later coverage, unlimited periods and suspended or derived holdings"]
  H1 --> H2
  H3["Classify candidates by the planning date and grace and select actions using renewal and drop preferences"]
  H2 --> H3
  H4["Insert versioned action plans, count statistics and mark the run planned"]
  H3 --> H4
```

## When Something Fails

Creation and planning independently roll back on refusal. Candidate changes after planning are handled during execution by term-version checks. Action readback lacks a fully stable order for rows sharing the same creation instant.