---
id: WF-MBR-MEM-019
title: Run one occurrence of a recurring billing run
trigger: The schedule consumer receives recurring billing work.
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
  - STATE-MBR-MEM-009
crosses:
  - SVC-MBR-MEM-billing
  - SVC-MBR-MEM-memberships
idempotency: >-
  The recurring configuration and local occurrence date uniquely identify a run.
  Retry reuses the stored run and resumes only the draft or planned stages that
  remain.
concurrency: >-
  Schedule claiming and run uniqueness protect occurrence duplication. Run
  operations retain their own lock and version checks.
hops:
  - 'n': 1
    actor_or_service: Schedule dispatcher and consumer
    action: Consume the claimed recurring occurrence in its workspace context.
    anchor: 'services-membership:modules/memberships/aws/lambda/SCHEDULE_CONSUMER.ts'
    seam: schedule
    on_failure: Scheduled-work delivery handles retry through its schedule contract.
    left_inconsistent: The dated batch may still be absent before successful occurrence handling.
    observer: Scheduled occurrence record
    provenance: observed
    source: >-
      services-membership:modules/billing/services/recurring/recurring-billing-runs.ts
      (header)
  - 'n': 2
    actor_or_service: Billing service
    action: >-
      Skip unavailable or paused configuration; otherwise reuse or create its
      dated batch from the template and offsets.
    anchor: >-
      services-membership:modules/billing/services/recurring/recurring-billing-runs.ts:runOccurrence
    seam: sync
    on_failure: The local transaction rolls back; the caller retries the work.
    left_inconsistent: No partial local change remains.
    observer: Renewal batch list
    provenance: test
    source: >-
      services-membership:modules/billing/tests/integration/billing-runs.integration.spec.ts#creates
      and plans one run per occurrence of a recurring run, a redelivere
  - 'n': 3
    actor_or_service: Billing service
    action: >-
      Plan a draft batch and execute a planned batch only when automatic
      execution is enabled.
    anchor: >-
      services-membership:modules/billing/services/runs/billing-run-operations.ts:planRun
    seam: sync
    on_failure: >-
      Retain completed stages and let retry or an administrator continue the
      remaining batch work.
    left_inconsistent: A created batch can remain draft or planned after partial occurrence work.
    observer: Renewal batch list
    provenance: observed
    source: >-
      services-membership:modules/billing/services/recurring/recurring-billing-runs.ts:runOccurrence
branches: []
waits: []
evidence:
  - >-
    services-membership at 5994c270:
    modules/billing/services/recurring/recurring-billing-runs.ts;
    modules/memberships/services/sweep/status-sweep-schedule.ts (registers this
    work)
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]
---

# Run one occurrence of a recurring billing run

## What It Does

Each active recurring occurrence creates or reuses one dated renewal batch. It plans that batch on the occurrence date and optionally starts execution.

## The Flow

```mermaid
flowchart TD
  H1["Consume the claimed recurring occurrence in its workspace context"]
  H2["Skip unavailable or paused configuration; otherwise reuse or create its dated batch from the template and offsets"]
  H1 --> H2
  H3["Plan a draft batch and execute a planned batch only when automatic execution is enabled"]
  H2 --> H3
```

## When Something Fails

A partial occurrence can leave a draft or planned batch that retry or an administrator can continue. A missing or paused configuration is reported skipped without creating work.