---
id: STATE-MBR-MEM-009
title: Recurring billing run schedule
object: DOM-MBR-MEM-005
product_area: membership
module: memberships
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
source_sha:
  services-membership: 5994c270e8a37a30f848e99ba5b5ee6b87c08893
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
states:
  - name: active
    meaning: Due occurrences can create and plan the configured renewal batch.
  - name: paused
    meaning: The recurring configuration causes delivered occurrences to be skipped.
transitions:
  - from: active
    to: paused
    trigger: A manager pauses recurring work.
    guard: The submitted version is current.
    side_effects:
      - Disable its schedule.
    who: Membership administrator
    provenance: observed
    source: >-
      services-membership:modules/billing/services/recurring/recurring-billing-runs.ts:updateRecurringRunOf
  - from: paused
    to: active
    trigger: A manager resumes recurring work.
    guard: The submitted version matches.
    side_effects:
      - Enable its schedule.
    who: Membership administrator
    provenance: observed
    source: >-
      services-membership:modules/billing/services/recurring/recurring-billing-runs.ts:updateRecurringRunOf
  - from: active
    to: active
    trigger: An active occurrence arrives or a manager changes its schedule.
    guard: >-
      Occurrence work reuses an existing batch; configuration changes require
      the read version.
    side_effects:
      - 'Create or reuse the dated run, plan its draft and execute if enabled.'
    who: Schedule dispatcher and consumer; Membership administrator
    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
invalid: []
concurrency: >-
  Occurrences use the configured customer time zone. Recurring updates lock and
  version-check the configuration, and occurrence uniqueness protects batch
  creation.
invariants:
  - INV-DOM-MBR-MEM-005-02
  - INV-DOM-MBR-MEM-005-09
evidence:
  - >-
    services-membership at 5994c270:
    modules/billing/services/recurring/recurring-billing-runs.ts;
    db/recurring-billing-runs.table.ts
---

# Recurring billing run schedule

## The Lifecycle

```mermaid
stateDiagram-v2
  state active
  state paused
  active --> paused
  paused --> active
  active --> active
```

## Transitions Explained

The active flag controls whether delivered occurrences create work. Pause and resume update the underlying schedule, while rescheduling changes its rule. An occurrence reuses its existing batch and continues only unfinished stages.

## What Cannot Happen

A paused occurrence returns a skipped answer. Pausing an already paused configuration is not a forbidden lifecycle transition; version checks still apply.

## Concurrency and Timing

Occurrences use the configured customer time zone. Recurring updates lock and version-check the configuration, and occurrence uniqueness protects batch creation.